Markdown extensions

Markdown extensions or "tags" allow content authors to create rich, interactive web pages. This is a list of all tags and their configuration options.

Tag usage

Tags are easy to read and write. They always start on a new line, with a square bracket, followed by a tag name and options, followed by a closing square bracket. Let’s say we want to add a video, we would write something like this:

[video /videos/explainer.mp4]

Supplying options

Tag options can be supplied in several ways:

// named options
[image src="hello.png" caption="Hello, World" alt="Hello image"]

// nested options
[image]
   caption: Hello, World!
   large: hello-big.png
   small: hello.png
   alt: Hello Image

// plain value without the attribute name
[image hello.png]

// handy syntax for id and class attributes
[image#hero-image.heroic hero.webp]

Nested content

Most tags like images, buttons, tabs and grids accept nested content:

[image explainer.png]
  This nested content is the caption for the image.
  You can add Markdown here like *emphasis* and `inline code`

Tag reference

Image

Image tag renders an image with an optional caption. For example:

[image hello.webp]
  This content here is the caption. Markdown *formatting* is supported

Shortcut alias (!) is supported:

[! hello.webp]

Images can link to URL's with href attribute:

[image book.svg href="/docs/" caption="View documentation"]

Art direction is supported:

[image small="ui-tall.png" large="ui-wide.png" ]

Responsive images are supported

[image.heroic]
  srcset: planet.png 450w, planet-big.png 900w
  sizes: (max-width: 600px) 450px, 900px
  alt: This is the alt text
  loading: eager

Button

Renders a button:

// with all options
[button label="Learn more" href="/docs/"]

// label option can be given as a plain value
[button "Learn more" href="/docs/"]

// with class name and a nested body
[button.secondary href="/docs/"]
  Learn more

Table

Renders an HTML table from the nested data:

[table "Name; Email; Work title"]
  - Alice Johnson   |  alice.johnson@demo.ai   |  Marketing Manager
  - John Smith      |  john.smith@demo.ai      |  Software Engineer
  - Emily Davis     |  emily.davis@demo.ai     |  Human Resources Lead
  - Michael Chen    |  michael.chen@demo.ai    |  Sales Representative
  - Sarah Thompson  |  sarah.thompson@demo.ai  |  Graphic Designer
  - David Rodriguez |  david.rodriguez@demo.ai |  Financial Analyst
  - Jessica Lee     |  jessica.lee@demo.ai     |  Project Manager

Another example with explicitly defined head and items attributes:

[table]
  head:
    - Name
    - Email
    - Work title

  items:
    - Alice Johnson   |  alice.johnson@demo.ai   |  Marketing Manager
    - John Smith      |  john.smith@demo.ai      |  Software Engineer
    - Jessica Lee     |  jessica.lee@demo.ai     |  Project Manager

Video

Renders a video:

[video hello.mp4]

Shortcut alias (!) is supported:

[! world.mp4 ]

All standard HTML5 video attributes are supported:

[image intro.mp4 autoplay controls muted loop ]

Options given as YAML:

[video.heroic]
  sources: [ hello.webm, hello.mp4 ]
  poster: hello.png
  width: 1000

Grid

Renders a grid of items separated by a triple-dash.

[grid]
  # First item
  [image first.png]

  ---
  # Second item
  [image second.png]

  ---
  # Third item
  [image third.png]

Tabs

Render a tabbed layout for organizing the content into multiple panes where users can see one pane at a time:

[tabs "First tab | Second tab | Third tab"]

  ## First pane
  Pane contents

  ---
  ## Second pane
  [image hello.png]

  ---
  ## Third pane
  [image world.mp4]

Code

Displays a syntax highlighted code block with support for line numbers, captions, and wrapper elements:

[code.heroic numbered caption="Some JavaScript"]

  function something() {
    // do the thing
  }

Special characters

You can use a set of special characters in the code to highlight content:

// This is a styled code block

Highlight lines by prefixing them with ">", "+", or "-"

Here's a highlighted region

export default { bring out errors }

// enable line numbers with `numbered` property
const html = glow(code, { numbered: true })

Use bullet character (•) to highlight text regions within a line. The following sentence:

These •two words• are highlighted and ••these words•• are erroneous

is rendered as:

These two words are highlighted and these words are erroneous

Codeblocks

Renders a single multi-code element where the blocks are separated with a triple-dash:

[codeblocks]

  <!-- first code block -->
  <p>Hello</p>

  ---

  <!-- second code block -->
  <p>World</p>

Codetabs

Render a tabbed layout to organize the code into multiple blocks where users can see one block at a time:

[codetabs "First | Second | Third" languages="js | html | css"]

  // First pane
  const foo = 'bar'
  ---

  <!-- Second pane -->
  <p>Hello, World</p>

  ---
  /* Third pane */
  p {
    background-color: yellow
  }