Joshua's Docs - Markdown (MD) tips, notes, and gotchas


Authoring Markdown Tools

  • VSCode:
  • Offline Editors
  • CLI
    • Pandoc
      • Converting to HTML and putting in clipboard is as easy as: pandoc | clip on Windows.
        • Don't use clip if using Unicode and standard Win code page; it will mangle it. Instead, send directly to file (pandoc > out.html)
      • Use -o OUTFILE to specify output file and file type.
        • Example: pandoc -o render.pdf
      • Tip: Use --no-highlight to keep <pre> blocks plain
      • Tip: Remember that Pandoc (at the time of writing this) does not use CommonMark as the default MD input format
        • You can force it to be used, with -f commonmark
      • Tip: Checkout Pandoc Tricks document for advanced tips
    • markdown-pdf
      • Example: npx markdown-pdf -o render.pdf
  • Online converters / tools
  • JavaScript Conversion


  • Some basic HTML is permissable directly in Markdown, which you can use to get around some "gotchas"
    • Some handy ones to remember:
      • <br> for line break
      • &nbsp; for literal non-breaking space
      • &copy; for copyright symbol (©)
    • Note that many converters will strip out certain tags.
    • Of course, if you find yourself writing mostly HTML, it might be time to consider leaving Markdown for your specific file...
  • Try to use only one top level heading (#, not ##...) if your markdown is going to be converted to HTML
    • HTML recommendation is one <h1>, which is the usual conversion of #
  • Getting word count: see my blog post
  • Always specify the language when creating a code block
    • Many platforms have built-in support for many different languages, including some interesting uses, like diff:
    + Added
    - Removed
    • If you are converting your Markdown to HTML and then hosting somewhere, I recommend Prism.js as the syntax highlighter for code blocks

Unique or Extended Syntax


  • Line-breaks are often not permissable within certain blocks (like within table row).
    • You can cheat and use <br>, which most MD parsers should echo out as line break.
    • Here is one now:

      === Hey! ===

  • For lists, most implementation of Markdown require a line break before the list start in order to recognize it as a list
    • In places where you don't see this as the case, they are probably using CommonMark, which is the most common exception
    • For accomplishing this in blockquote, just use an empty blockquote before (S/O)
  • Multiple spaces are truncated, and you can't use spaces for indenting
    • You can always use &nbsp;
    • Bulleted lists are also a good way to inject indenting
  • Subsection (aka anchor) linking:
    • Really good summary from "TomOnTime" that summarize how GitHub handles it:
      1. It downcases the string
      2. remove anything that is not a letter, number, space or hyphen (see the source for how Unicode is handled)
      3. changes any space to a hyphen.
      4. If that is not unique, add "-1", "-2", "-3",... to make it unique
    • Someone made a super easy to use TOC generator based on the above thread; just paste into this webpage.
  • Tables
    • They tend to not get parsed correctly if you don't precede them with either an empty line, or a heading (# My Heading)
    • To escape the pipe character |, you can:
      • Escape with \:
        Header A | Header B
        --- | ---
        `1 \| 2` | `3 \| 4`
      • Use HTML instead of markdown
      • Use &#124; instead of | (SO)
  • You cannot escape backticks in inline code or fenced code blocks; you must change the outer delimiter instead
    • For example: ``here is a backtick: "`"`` (notice double backticks on the edges instead of single)
    • For best compatibility with all markdown parsers, use triple backticks
    • If you are trying to escape triple backticks inside of a code block, you might be better off using ~ instead of backticks as your outer delimiter. This is permissible in many Markdown flavors.

Collapsible Sections / block


	<!-- EMPTY LINE -->

The inner block content doesn't necessarily have to be indented. In fact, it might break syntax highlighting / parsing for code blocks if indented.


	<summary>Click to expand section!</summary>

	This text can be hidden or shown, by clicking the text above!
Click to expand section!
This text can be hidden or shown, by clicking the text above!

This is not unique to Markdown; <details> is a standard HTML element - MDN Docs

You can use the open (or open="true") attribute to control the default open vs closed state

Markdown Source Last Updated:
Mon Feb 06 2023 01:03:48 GMT+0000 (Coordinated Universal Time)
Markdown Source Created:
Mon Aug 19 2019 17:06:24 GMT+0000 (Coordinated Universal Time)
© 2024 Joshua Tzucker, Built with Gatsby