Markdown extras

This page describes extra syntax available for controlling markdown page formastting and display. (It also serves as a quick test that thos are working.) Most of the items described here come from the Markdig markdown engine used by DocFX. This doesn't apply to core manual, which uses a different markdown engine. It might not continue to work in Hexadocs, which also uses a different markdown engine, or might require editing before it works.

Mathematics

Status: fully functional

Adds support for MathJax math formula rendering.

Refer to Math for examples.

Emphasis Extras

Status: Only strikethrough supported by DocFX 2.70, which we currently use

Adds additional emphasis characters:

  • ~~txt~~ : strikethrough (note double tilde delimiters)
  • ~txt~ : ~sub~script (note single tilde delimiters)
  • ^txt^ : ^super^script
  • ++txt++ : ++inserted++
  • ==txt== : ==marked==

Super and sub script are the most useful additions. The others might make sense in limited contexts.

Refer to Additional emphasis for examples.

Attributes

Status: fully functional

Adds support for assigning attribute values to the generated HTML elements created from markdown:

  • {attribute=value} or {attribute="value"} : adds the attribute of the specified name and value to the elements attributes
  • {#id-value} : shortcut for assigning an id -- adds the attribute id="id-value"
  • {.class-name} : shortcut for assigning a class -- adds class-name to the class list, adding a class attribute if needed

The assignment can be placed on the line before or inside a block-level element, like a paragraph, or immediately after an inline element (with no space).

This provides an easy syntax for assigning ids to headings to be used as anchors: ## Heading {#heading-anchor}

Tip

This heading anchor syntax differs slightly from that available in the core docs, which just uses square brackets (and no # character): ## Core Manual Heading [anchor-in-core-docs-markdown].

Refer to Assign attribute values for examples.

List Extras

Status: fully functional

Adds additional numbered bullets: a, A, i, I

  1. One
  2. Two
  3. Three
  4. Four
  1. One
  2. Two
  3. Three
  4. Four
  1. One
  2. Two
  3. Three
  4. Four
  1. One
  2. Two
  3. Three
  4. Four

Just use the desired character sequence in place of a number in the markdown list.

Refer to More list bullets for examples.

Grid Tables

Status: fully functional

Grid tables let you:

  • include line breaks in cells
  • specify relative column widths
  • span rows and columns (note spanning cells is frowned upon for accessibility reasons)

The following shows a simple grid table:

+---------+---------+
| Header  | Header  |
| Column1 | Column2 |
+=========+=========+
| 1. ab   | > This is a quote
| 2. cde  | > For the second column 
| 3. f    |
+---------+---------+
| Second row spanning
| on two columns
+---------+---------+
| Back    |         |
| to      |         |
| one     |         |
| column  |         |

which is rendered as:

Header Column1 Header Column2
  1. ab
  2. cde
  3. f

This is a quote For the second column
Second row spanning on two columns
Back to one column

Refer to Grid table format for more detailed rules and examples.

Media links

Status: fully functional

Refer to Ways to make links to common media sites for examples.