Resources

• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Authoring Markdown Tools

• VSCode:

  • Markdown All in One
  • Code Spell Checker

• Offline Editors

  • Typora
  • Mark Text
  • Also see my list of favorite programs

• 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

• JavaScript Conversion

  • For HTML to Markdown: turndown

  • For Markdown to HTML:

    • Marked JS
    • Showdown
    • Markdown It

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
    •   for literal non-breaking space
    • © for copyright symbol (©)

  • Note that many converters will strip out certain tags.

    • Github strips out <script>,<iframe>, among others
  • 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

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  
  • 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

      • You could change entire table to be HTML, or just the individual cell, by adding empty lines around the HTML code.
    • Use | instead of | (SO)

• 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>

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