Markdown

About usage of Markdown

Commonmark reference implementation was first used for Markdown. What I found is that it was not very configurable, even if some extensions could be added (like Table and Image extension) in addition to just use the Commonmark standard. I startet to use Flexmark instead. But I have later found that this library is not actively maintained anymore. I have started to go back to CommonMark again, and I have found this library sufficient for my web app.

GitHub flavored Markdown is the most used Markdown dialect, also used in Intellij. I have implemented support for most of it. Support for tables, links and images is absolutely required in a blog system. GitHub flavored Markdown s code and code blocks. I have enabled this too.

One disadvantage with Markdown is the limited set of formatting options for individual HTML tags. It is possible to do some of it with either smart CSS or including HTML in the Markdown. My experience with these smart Markdown tricks, is that it is difficult to obtain the desired layout effects without a lot of effort. The best is to accept the limitations of Markdown. One option is to add more Markdown extensions.

The Markdown is embedded in the HTML. It is two ways to add Markdown to this website:

• To include static Markdown files
• To use embedded text editor and store the Markdown in a database.

The Markdown content is selected from a menu:

• Hard coded menu for the static Markdown files
• Storing metadata in a database and produce a menu from it.

Alternatives to Markdown

• AsciiDoc (Extended markdown for better layout, e.g. for tables)
• Plain HTML (too much work and includes coding).
• language resource file text (tried that, not ideal).
• To use RTF.
• XML / XHTML (non-standard legacy solutions)

The RTF option is the best alternative, but needs an RTF editor and a more complex parser. The generated embedded HTML also is not as clean as if Markdown is used. Language resource files is used in this project, but only for short text.

Security

Markdown does not prevent HTML injection, since it is possible to add plan HTML to Markdown. To avoid security problems a sanitizer is used to remove dangerous HTML. A problem with this is that it removes some useful HTML tags that can be included in the Markdown. The Owasp sanitizer is configurable, so I have allowed some HTML tags and attributes that was denied in the default setup. The right adjustment of numbers used in the table example below, is removed by the sanitizer. The title attribute of image is also removed I have to whitelist some tags and attributes I need in the sanitizer.

Markdown links

Examples of links:
Link to home
Link to about electrical power
Link to tech
Link to energy view
Relative link to blog politics
Absolute link blog web page politics
Link to external web page ChatGPT

The code uses the Markdown parser to convert Markdown links to HTML links on the web page.
This enables the link to work correctly in GitHub, Intellij and web page. My blog system can use all these link types, but the absolute URL is preferred.

Anchor links (not implemented)

It is possible to link to headlines with id's defined, as in HTML.
Link to internal Bottom headline INTERNAL ANCHOR NOT IMPLEMENTED
Link to tech how to headline EXTERNAL ANCHOR NOT IMPLEMENTED
If you try this is will not work in my blog. It works in Intellij. I got this to work with Flexmark. It is possible with Commonmark, but not tested. My intent is to skip this because it is not much used, and it is not very useful either with blog pages usually been less than 3 pages. It is generally hard to implement because it can collide with internal id’s and need to be prefixed. The parser need to be configured to generate ids for headlines, and the Sanitizer must be configured not to remove them.
If the headline you link to is changed, it will not work either. This often introduces a lot of broken links in documentation systems.

The links to blog content stored in a database, only works on the produced web page. All link examples contain relative links, except the bottom link that is just a regular external link.

Tables

Example of embedded table in Markdown.

Media files in Markdown

Example of embedded image in Markdown, stored in the Docker container.

Example of embedded images in Markdown, stored on volume (bind mount) outside the Docker container

There is no difference in syntax for the two methods. I use a visitor pattern to be able to detect where the images are stored. I have not yet made any GUI for uploading images, so an upload or syncronization tool is required to the VPS (e.g. Jottacloud).

Code and code blocks

An example of a code block. Below is a standard Kotlin utility function to check if a number is a prime number:

fun isPrime(number: Int): Boolean {
    if (number <= 1) return false
    for (i in 2..Math.sqrt(number.toDouble()).toInt()) {
        if (number % i == 0) return false
    }
    return true
}

Single quote block:

This is a single line code block with a very long text to check if it breaks.

Math

Example of a formula in a math block and a simpler inlined math expression.

The total energy increases quadratically, as shown in the formula E_total = gamma * N_inn².

Note: Intellij uses more advanced Latex parsing, not included in my simple Commonmark configuration. GitHub uses a different syntax for inline math expressions. I have used what is simple to implement with Commonmark.

Printing

Some additional css are added, to exclude top and bottom line and more, with the @media print tag. For most of my web pages, this is enough to enjoy beautiful web page printing. For even better result, print the blog post as PDF, download and enjoy.

The end

The page ends, and the answer is 42.