Resources
Authoring Markdown Tools
-
VSCode:
-
Offline Editors
- Typora
- Mark Text
- Also see my list of favorite programs
-
CLI
-
-
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
)
- Don't use
- 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
- You can force it to be used, with
- 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:
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
- Github strips out
- 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#
- HTML recommendation is one
- 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! ===
- You can cheat and use
-
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
- You can always use
-
Subsection (aka anchor) linking:
-
Really good summary from "TomOnTime" that summarize how GitHub handles it:
- It downcases the string
- remove anything that is not a letter, number, space or hyphen (see the source for how Unicode is handled)
- changes any space to a hyphen.
- 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)
-
- They tend to not get parsed correctly if you don't precede them with either an empty line, or a 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
(oropen="true"
) attribute to control the default open vs closed state