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)
    • Use -o OUTFILE to specify output file and file type.
      • Example: pandoc myfile.md -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 my_markdown.md
• 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
  • Pandoc "Try Me" Online
    • This is also a quick way to try out different "flavors" of Markdown
• 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

Unique or Extended Syntax

https://www.markdownguide.org/extended-syntax/

GitHub Flavored Markdown (GFM)

GFM - Callout Notes

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Reusing Links / Reference Style Links

https://www.markdownguide.org/basic-syntax/#reference-style-links

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

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