Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support Markdown in Documentation/Purpose field #1032

Open
Phillipus opened this issue Mar 11, 2024 · 5 comments
Open

Support Markdown in Documentation/Purpose field #1032

Phillipus opened this issue Mar 11, 2024 · 5 comments

Comments

@Phillipus
Copy link
Member

Phillipus commented Mar 11, 2024

I'm opening this as a new issue so we can start with a clean discussion, as the other ones are a bit out of date.

#34
#293

@Phillipus
Copy link
Member Author

Phillipus commented Mar 11, 2024

The feature request is to support the rendering of MD in the Documentation/Purpose field.

Where should the MD be rendered?

  • HTML Report
  • Jasper Report

Where should the MD not be rendered?

  • In Archi itself

What Java library to use?

Example code:

Parser parser = Parser.builder().build();
Node document = parser.parse("This is *Markdown*");
HtmlRenderer renderer = HtmlRenderer.builder().build();
String text = renderer.render(document);  // "<p>This is <em>Markdown</em></p>\n"

@Phillipus
Copy link
Member Author

Phillipus commented Mar 11, 2024

The Documentation text has to be converted to HTML from MD before exporting to the reports.

  • When is the conversion done?
  • Is it optional?
  • How do we know that the field contains MD or plain text?

The HTML report renders documentation text using StringTemplate like this:

<div class="convertlinks documentation" style="white-space:pre-wrap">^element.Documentation;format="xml-encode"^^element.Purpose;format="xml-encode"^^element.Content;format="xml-encode"^</div>

In order to render HTML the format="xml-encode" part would have to be removed.

  • How to make this conditional?
  • How do we know if the Documentation contains MD or plain text?

Similar questions for Jasper Reports:

@Phillipus
Copy link
Member Author

Phillipus commented Mar 11, 2024

In summary, it's easy enough to add a Java library to convert MD to HTML, the problems are where to do that rendering and how to handle escaped or unescaped HTML in the reports. And to know when text is MD and when it is plain text. Until that is solved, we can't implement it.

@Phillipus
Copy link
Member Author

Phillipus commented Mar 11, 2024

I created a POC implementation here

The main problems are:

  • The rendering in the HTML report looks bad because it uses the host report's style-sheet. It needs to have its own style-sheet.
  • Very limited support of rendering HTML in Jasper Reports. It's so limited that it's useless.

From my tests, I'd say that it's a non-starter for the Jasper report and only possible in the HTML report if we can figure out how to attach a separate style-sheet to the resulting documentation HTML.

Another thing is label expressions. Let's suppose you have markdown in your documentation field and you use a label expression ${documentation}. Then you will not see the rendered markdown in the diagram because it cannot render it there.

So, the main issue here is not how to convert MD to HTML but how well HTML is rendered in the target. In our case we have two targets, HTML and Jasper reports, and HTML does not render well.

It might be better to apply a JavaScript MD renderer to the HTML report as was suggested here.

@rgoubet
Copy link

rgoubet commented Jun 27, 2024

I definitely support this one, especially for HTML reports!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants