A week and a half ago we deployed our new website at https://www.fastmail.com, and it’s using Zola. (The /help pages are not currently in Zola, but will be at some point not too distant.)
I personally only set the Zola project up at the start and did a few bits of content here and there towards the end like the signup page, but I observed a regular annoyance: Markdown only works well for pages that are predominantly prose with no special formatting; on pages that need to be almost entirely exclusively fancy formatting, Markdown is really annoying, because it loves to mangle the arbitrary HTML that you’re writing. Most specifically, you must eschew either the conventional indentation of your HTML, or blank lines; because if you use both, then your indented HTML following a blank line will be treated as a code block instead. (Our old site also suffered from this nuisance, as content was all fed through Markdown.pl, which handles this situation a little differently—and I just now found our DPA page ruined by this incompatibility between Markdown.pl and CommonMark, which I’ll deploy a fix for on Monday.)
It seems to me that, at the user level, there is a simple and obvious solution for this pain: allow pages and sections to use the extension
.html instead of
.md, and disable Markdown
mangling processing in that case.
A couple of alternatives available to users are: making a template for each such page, and having the pages be empty stubs; or having the HTML sit beside the page Markdown file and use
load_data. Either way, you now have two files to care about, possibly in different places, and it’s just not neat. They’re both clearly workarounds rather than solutions. (I am also assuming
in_search_index = false on these pages, because that’s our case; think through the implications of not this yourself.)
I have not looked at the implementation ramifications of such a change. I imagine that there should be no substantial problem; for pages, there are already multiple candidates,
foo/index.md, and this is essentially just adding two more; sections I cannot speak for.
A variant that would probably be easier to implement, but which I don’t much like, would be allowing
markdown = false in the frontmatter to disable Markdown interpretation, yielding a .md file that is actually HTML rather than Markdown.