Markdown (Im)practicalities for Static Site Generation

Yes, I know this is not exactly related to game development, but I have to talk/rant about this. Markdown is a really nice tool! It makes writing texts for web pages a lot easier. Yet, if you are using it as part of static site generation chain, like this entire site, then it becomes impractical, unless you have very simple requirements.

That’s not the case for this site. As an example, I created the “card” system to layout the tutorials, news and blog entries. Those cards require quite a bit of nested <div></div> contents. After searching a bit about this specific case, people suggested to directly use the tags within the markdown file. Well, honestly that already defeats the purpose of the format. But, there is another problem. Nesting tags like that will somewhat “force” indentation in order to make the source readable. Well, depending on the markdown interpreter, it will trigger the <code>...</code> tag, forcing to remove the readability of the text.

Later on I spent a good a mount of time to expand the markdown interpreter that I’m using, creating an extension that works like this:

%%% classname
contents
%%%

Which is rendered as:

<div class='classname'>
contents
</div>

Then, how about adding a CSS class to certain elements, like images, which also should be links to the full sized image? Something like this:

<a href='full_size_image'><img src='source_image' class='thumbnail' /></a>

No, there is no way with “pure” markdown and the solution is to directly use the image tag. That’s somewhat what I ended up doing. At least in this case the scope is not potentially multi-line like in the case of the div containers.

How about some advanced tables to display complex data? No, there is no way to do that with markdown, you must directly use the html tags.

I could go on and on but I think you already got the point.

From all of this you might think that I hate markdown. I don’t! It’s just not practical for my use case! It’s extremely useful in cases where “arbitrary” content do have imposed restrictions, as wiki-like sites and such. On those cases, we have to comply with the rules given by the service, which builds on top of the markdown interpreter in use. And then, you check, GitHub did expand their markdown.

Do I have a solution? Unfortunately not. At least, not for the moment. IF I ever come with one, I will bring a new post to continue on this.


April 11 2019