Joshua's Cheatsheets - Markdown (MD) tips, notes, and gotchas
Light
help

Resources

Authoring Markdown Tools

  • VSCode:

  • Offline Editors

  • CLI

    • Pandoc

      • Converting to HTML and putting in clipboard is as easy as: pandoc myfile.md | 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 myfile.md > out.html)
      • 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
  • Online converters / tools

    • Website Table to Markdown: Convert a website table (e.g. copied from Google Sheets) to Markdown - extracts the HTML from your clipboard

Pro-tips:

  • 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

Gotchas:

  • 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)
  • You cannot escape backticks in 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

Collapsible Sections / block

Syntax:

<details>
	<summary>clickable_toggle_text</summary>
	<!-- EMPTY LINE -->
	block_content_that_collapses
</details>

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

Example:

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

	This text can be hidden or shown, by clicking the text above!
</details>
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:
Sun Sep 27 2020 05:14:19 GMT+0000 (Coordinated Universal Time)
Markdown Source Created:
Mon Aug 19 2019 17:06:24 GMT+0000 (Coordinated Universal Time)
© 2020 Joshua Tzucker, Built with Gatsby