Markdown syntax
Sean Colsen
TL;DR:
- The Markdown rendering behavior in MkDocs differs slightly from other tools we use (e.g. GitHub, HackMD, Matrix).
- Please try to follow this new Markdown Style Guide that I’ve written in order to keep your Markdown portable.
- Most importantly:
- Indent with four spaces everywhere.
- Use blank lines between paragraphs, lists, and headings.
- If you have any concerns with the Markdown Style Guide, please reply to this list and we can adjust them as needed.
~ ~ ~
In an email last week, Kriti gave some critique of a wiki page, saying:
It looks like the migration to MkDocs messed up the formatting of the timeline table and the status paragraph.
Though I fixed the formatting on that specific page, I want to clarify what’s happening so that everyone is in the loop and understands how to avoid problems like this going forward. This is not an issue with the migration process — rather, it’s an issue with inconsistent behavior between different Markdown rendering engines. During the migration to MkDocs, I took a rough stab at using some crude regexes to fix content that I knew would not render correctly (example, example) but there is still a lot of other problems I didn't address.
In particular, we still have lots of problems with list
indentation. When I looked at it, I realized it was not such a
straightforward problem. Some of our content is really a mess in
this regard, with a mix of spaces and tabs on the same line. I
got the sense that properly fixing the indentation to render the
way the author intended would requires some contextual
understanding of the content itself. Being that most the content
in the wiki is not terribly important to us, I chose not to
spend too much time on this issue. It’s something I’d like to
fix going forward by requesting that everyone take
care to indent all Markdown with four spaces. Even though your
meeting notes may look fine with two-space indentation in
HackMD, please use four spaces because those meeting notes will
eventually find their way into the MkDocs wiki.
I'd like to eventually set up a Markdown code formatter. In theory, such a tool would help us avoid problems like the list indentation issues. I took a stab at this today but ran into some road blocks. I captured my progress in this ticket: Configure code formatting for Markdown within docs and wiki sites. We can pick that up at some point in the future if needed.
