Markdown¶

The LTSP project uses GitHub Flavored Markdown, with a few differences noted below.

Inline elements¶

Markdown uses two trailing spaces at the end of a line to indicate a <br />.

Text formatting¶

Element	HTML	When to use
`asterisk1`	em	Emphasis
`asterisk2`	strong	Strong importance
`*asterisk3*`	em>strong¹	*For* ▸ *menus* and *GUI labels*
`backtick`	code	`commands, filenames, terminal stuff`
`a1>b`	em>code	`Smart roles`²
`a2>b`	strong>code	Keystrokes: `Ctrl`+`Alt`+`Del`

Notes¶

Pymarkdown renders *** as strong>em, while markdown-it as em>strong. We cover both cases in our CSS.
Smart roles are not implemented nor used yet. For example, page could automatically link to page.md and show a tooltip with its title.
In vscode-markdown-extended, underscore is rendered as u (underline) instead of em. Also some other parsers have issues with underscores. Avoid them, e.g. don't use _text_ for emphasis.

Images¶

A normal image is ![alt](image.png) and a link is [text](url).

For right-aligned, shrinked, clickable images, use this syntax: [![](image.png)](image.png)

Block elements¶

Code blocks¶

Use fenced code blocks for multiline shell code:

```shell
code
```

Blank lines are not necessary. Do not use four spaces to indicate code blocks as some markdown implementations get confused e.g. in list > code, then code.

Lists¶

In the original markdown and in pymarkdown, indentation is always four spaces. This is necessary when we need to nest lists, admonitions etc, so we may use it always. Typing Tab after the dash is usually enough.

For numbered lists, 1.␣␣actual numbers with two spaces
- For bulleted lists, -␣␣␣dashes with three spaces

Admonitions¶

For now the pymarkdown-extras syntax is used, which is also supported by vscode-markdown-extended:

Optional tip title

Let's hope pymarkdown gets support for general purpose blocks similar to pandoc's fenced divs!

Markdown research notes¶

Classes¶

It's possible to add classes to any inline element by appending {.class} to its right, while in block elements it goes underneath. Kramdown uses {:.class} instead, and it's supported by pymarkdown, but not by vscode-markdown-extended.

Admonitions¶

[!NOTE]
Blockquotes are used for admonitions by the Microsoft Docs Authoring Pack

📝 NOTE
The same thing could be achieved by standard markdown and classes. Unfortunately, pymarkdown can only add the class to either the first or the last blockquote line, not to all of it.