Markdown rules!

It appears that almost all websites that publish text in some form use Markdown as the format to write texts in. The first website for one of my projects already did that in 2010. At that time the conversion of markdown to web page required a lot of programming. Surely that must be different in 2025. What's the best way to do that?

Contenders for all-in-one tools

For such a widespread text entering format for websites, it is a bit disappointing that a search engine does not overflow when searching for tools to create a website from Markdown. I did a similar search in 2017 for one of my professional projects, and then there was even less. What is complicating the choice is a few requirements:

• The conversion of the source material to the website must be done on a desktop (while editing content) and in a CI/CD pipeline.
• Custom conversions are required for specific tasks, e.g., to handle embedding of images from my photo archive on Flickr, or to automatically create pages and/or navigation structures based on itinerary schedules or thematic overlaps.
• It must be applicable using the skills I have now. If I have to learn a lot of new things, I've forgotten most of it next time I have to make modifications to the tooling.
• It must be available for the next couple of decades.

There are a few good options, the main ones are:

• MkDocs and the extension Material for MkDocs comes quite close. It is in Python, so I could write simple extensions for it. In the end I couldn't figure out how I could get some navigation options working: different ordering of list of pages on an index page within the same site, support for multi-part stories.
• Jekyll is probably good enough and well supported, but it is coded in Ruby - that's my family name but we're definitely not related. I would have to use it as a stand-alone tool and build custom tools to run before and possibly after Jekyll.
• Docusaurus generates a complete app while sometimes I need to have my own app and use the web pages as source material. Apart from that, I don't trust its owner (Facebook) to maintain the tool long-term and for free.

There are other choices, but they are similar to one of these three and have similar issues for me.

Site generation is the issue

While investigating the all-in-one tools I realized that the main issue is the requirements for the generation of the complete website, rather than the conversion of markdown to a HTML-fragment that still needs a web-page wrapper. The hard part of the conversion is to get the HTML fragment from markdown, and there is more choice in tools that do that well. The all-in-one tool selection failed because of the embedding of the HTML fragment in a web page, or of a single web page in the website. What if I would create a custom tool that did the web page embedding, created the website from a collection of pages, and optionally did some pre-processing of the markdown; could I then use a standard solution for the generation of a HTML fragment?

Fortunately, the answer is yes. For my favourite programming environment (.NET, C#) there is the Markdig library. It supports basic markdown, nearly all markdown extensions I've ever heard off, and a few other. Using it requires a few lines of code. I even managed to write a code plugin in a few hours to correct an issue with my content. It simply works, and is widely used in other C#/.NET environments.

Of the missing parts the generation of the web pages was the easiest to code. It is basically templating functionality: a template for a page contains most of the HTML, and a few entries that are replaced by the converted HTML, the title of the page and some navigational links to other pages. It is not worth the effort to spend a lot of time looking for a library or a markdown-based tool to replace that.

The remainder was most affected by my requirements: which pages are linked via navigation, how to order list of pages, and some auto-generated content. Not difficult, highly specific, it will always be custom code.

What I've learned

The quest for a tool, now for my personal project and a few years ago for a professional project, has made me realize that an all-in-one tools is perfect for websites generated from unmodified content. That is: if there is no automated fiddling required between the creation of the content and the publication of the website. If the all-in-one tool does not allow for a particular requirement by modifying its configuration of templates, don't use the tool. You end up writing more and more code to work around the limitations of the tool. Go for a library that does the core of the markdown-to-html conversion, and build the rest yourself.