Skip to content

Markdown

Markdown🔗

Resource Links
Cheatsheets MarkdownHere
www.markdownguide.org
Cheatsheet jonschlinkert
Linting & Style markdownlint, Obsidian Linter
Related =(join(this.related, ", "))
My stuff Cheat Markdown cheatsheet (local)
References markdownguide.org

Tools & Software🔗

1
2
3
4
5
6
TABLE WITHOUT ID
  file.link AS "Name",
  desc-short AS "Description",
  (join(category)) AS "Category"
WHERE type = "software" AND (contains(category,"markdown") OR contains(tags,"markdown"))
SORT title

Features🔗

There’s a great number of cheatsheets and similar references for standard features, see the table at the beginning. The following only contains some additions and examples.

Type Description
stand-alone URLs https://... should be inside <...> to be processed properly by some Markdown parsers
regular inline links [link text](url "alt text") alt text is optional, some viewers render it as a tooltip, to handle special characters that would require escaping, such as spaces, some parsers allow URLs in <...> again
Wiki-links [[url\|link text]] helpful extension in some parsers and can be used like [[url\|link text]]
HTML <a href="url" title="alt text">link text</a> helpful when using HTML as mixing with Markdown is not a good idea

^8eab7a

Lists🔗

Description lists are non-standard in Markdown and require HTML

1
2
3
4
<dl>
<dt>Item</dt>
<dd>Description</dd>
</dl>

Tables🔗

1
2
3
4
| Item | Price | # In stock |
|--------------|:-----:|-----------:|
| Juicy Apples | 1.99 | 739 |
| Bananas | 1.89 | 6 |
| Item | Price | # In stock | |--------------|:-----:|-----------:| | Juicy Apples | 1.99 | 739 | | Bananas | 1.89 | 6 |
  • use | for columns (and vertical lines), - for rows and horizontal lines
  • leading and closing | can be omitted (in some Markdown implementations?)
  • use : for alignment

Code blocks🔗

List of Markdown code block languages

Fenced code blocks syntax with triple backticks recommended: code language (highlighting), clear and conventional syntax. Style guides suggest empty lines before and after. Use quadrupel backticks to display tripel backticks, e.g. to display Markdown code.

1
2
3
```sh
echo "Hello World"
```

Columns🔗

Columns can be achieved with HTML, rendering is dependent on the reader/parser used though.

Two fixed-width columns

Column 1
Column 2

Custom CSS🔗

Many Markdown viewers/parsers allow the inclusion of custom [[CSS]] code for styling. This can for example be used to set up classes with certain styles, to facilitate applying visual effects.

(YAML) Front Matter🔗

Many parsers support a block of metadata at the beginning of a Markdown file, usually written in [[dev/YAML|YAML]], sometimes in [[TOML]]. What keys are accepted/used by the parsers varies, but a lot of useful things can be achieved with this.

Example

1
2
3
4
---
title: My Document
date: 2024-01-01
---

Parsers

  • gray-matter
  • yq: YAML parser that can be used to extract and process YAML front matter

Mermaid Graphs🔗

See notes on Mermaid.

Specifications, Implementations and Parsers🔗

Parsers/processors

References

Discussion

CommonMark🔗

Website | Specification | Forum | Tutorial

Pandoc developer John MacFarlane is one of the founders and maintainers. Used by obsidian.

Linting and Style🔗

⚠ Linting Markdown satisfyingly, including the front matter, is a pile of wank. Tons of packages and giant mess.

Front matter

Package Description Language
mdformat-frontmatter “mdformat plugin to ensure frontmatter is respected”
remark-lint-frontmatter-schema from JavaScript and VSCode ecosystems 🤮 Didn’t get it to run, some shit about pnpm failing to install crap after moving tons of npm-installed packages to the void without confirmation ✨ (different dir) JavaScript
yaml-fm-lint “A NodeJS script, which extracts yaml front matter from markdown files and lints the extracted data”
❗insists on removing quotes from front matter, only parses one path at a time, removes comments, fails on path/file.md
spatie/yaml-front-matter “A to the point yaml front matter parser”
❕installed using PHP pckg. mgr. composer 🤷‍♂		 PHP
YAML linters YAML only (extract and pass front matter manually)
yamllint (no fixing) ignores body, treating everything between --- as YAML (including code blocks with ---!)

All of these seem to fail on ill-formatted YAML block scalars. If the content is under-indented they just die on a missing colon 🤦‍♂

Presentations🔗

reveal.js🔗

See notes on Pandoc and reveal.js.

References🔗