Some Markdown links on phrasing more difficult markdown for correct rendering
Posted by jpluimers on 2019/08/20
After blogging on Markdown notes in 2014, Markdown support has come a long way. It also means that the documents written in Markdown has become more complex, and that more tools can render it.
Given the vague aspects of many Markdown dialects, rendering can be troublesome (see my post Babelmark 2 online Markdown checker), so below are some links on some aspects I had trouble with getting right.
- [WayBack] How to nest code within a list using Markdown – Meta Stack Exchange: indent the code with at least 4 more spaces than the minus signs in the unordered list.
- Tables inside unordered lists: example at [Archive.is] Babelmark 2 – Compare markdown implementations: tables within unordered lists which shows you need to have
- blank lines above/below the table so more Markdown tools render them as table.
- two spaces after each table line, so Markdown tools not rendering them as table rows, will render them as separate lines.
- Be sure to run your Markdown through [WayBack] markdownlint demo for syntax checking
Demo for markdownlint, a Node.js style checker and lint tool for Markdown/CommonMark files.
Note that there are two markdown linters:
- Ruby based [WayBack] GitHub – markdownlint/markdownlint: Markdown lint tool
- JavaScript based [WayBack] GitHub – markdownlint/markdownlint: Markdown lint tool (which follows the ruby based one, see for instance [WayBack] MD046 – Code block style (Ruby implementation) · Issue #131 · DavidAnson/markdownlint · GitHub and [WayBack] Issues · DavidAnson/markdownlint · GitHub: ruby)
Sometimes, issues are present in one, but not in the other; see:
- [WayBack] MD025 in quoted sections · Issue #235 · markdownlint/markdownlint · GitHub
- [WayBack] MD023 in quoted sections that are part of a list · Issue #236 · markdownlint/markdownlint · GitHub
The command line interface to the Ruby version is easier to install than the JavaScript version as everything is in one gem: mdl, unlike the npm, where the cli is in markdown-cli and the library in markdownlint.
–jeroen
Related:
https://gist.github.com/jpluimers/49c5af700ae75458d65061201554d5e1
Leave a Comment