Markdown Extensions

You can extend the functionality of your MkDocs site.

MkDocs offers a generic guide to extending a MkDocs site.

Configuration

Minimal

Users of this theme should at least enable these extensions:

markdown_extensions:
  - toc:
      permalink: "" # i.e. `true` but without "¶"
      permalink_class: headerlink fa fa-link
      permalink_title: Link to Heading

Typical

Typical users of this theme will both enable all these extensions —

markdown_extensions:
    - extra
    - admonition
    - toc:
        permalink: "" # i.e. `true` but without "¶"
        permalink_class: headerlink fa fa-link
        permalink_title: Link to Heading
    # PyMdown Extensions
    - pymdownx.blocks.admonition
    - pymdownx.blocks.details
    - pymdownx.blocks.html
    - pymdownx.blocks.tab
    - pymdownx.superfences
    - pymdownx.inlinehilite
    - pymdownx.saneheaders

— and install PyMdown Extensions via optional dependency, e.g.

pip install "mkdocs-tacc[pymdown-extensions]"

Demos

The TACC MkDocs Theme enhances the UI of these extensions:

from Python-Markdown Reference
Abbreviations extra: abbr
HTML Attributes extra: attr_list
Definition Lists extra: def_list
Code Blocks extra: fenced_code
Footnotes extra: footnotes
Markdown in HTML extra: md_in_html
Tables extra: tables
Alerts & Notes admonition
Table of Contents toc
of PyMdown Extensions Reference
Alerts & Notes blocks.admonition
Collapsible Content blocks.details
HTML (via Blocks) blocks.html
Tabs (via Blocks) blocks.tab
Tabbed Content ⚠️ tabbed

from Python-Markdown

Abbreviation

Syntax

The HTML and CSS specifications are maintained by the W3C.

*[HTML]: Hypertext Markup Language
*[CSS]: Cascading Style Sheets
*[W3C]: World Wide Web Consortium

Result

The HTML and CSS specifications are maintained by the W3C.

Attribute Lists

Syntax

This is a paragraph with custom class and ID. (Inspect element to see.)
{: .class-name #custom-id }

Result

This is a paragraph with custom class and ID. (Inspect element to see.)

Definition Lists

Syntax

Term
: Definition of the term
: Another definition

HTML
: Hypertext Markup Language
: The standard markup language for web pages

Result

Term
Definition of the term
Another definition
HTML
Hypertext Markup Language
The standard markup language for web pages

Fenced Code Blocks

Syntax

```shell
echo "Hello, World!" > /tmp/output.txt
```

Result

echo "Hello, World!" > /tmp/output.txt

Footnotes

Syntax

A sentence with a footnote.[^1]

[^1]: The footnote content.

Result

A sentence with a footnote.1

Markdown in HTML

Syntax

<div markdown="block">

I am in a `<div>` with markdown enabled.

</div>

Result

I am in a <div> with markdown enabled.

Tables

Syntax

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Result

Header 1 Header 2
Cell 1 Cell 2
Cell 3 Cell 4

Admonitions

Syntax

!!! note "Custom Title"
    This is a note with a custom title.

!!! warning
    You can include blocks in admonitions, e.g.

    ```shell
    echo "Hello from an admonition!"
    ```

Result

Custom Title

This is a note with a custom title.

Tip

You can include blocks in admonitions, e.g.

echo "Hello from an admonition!"

Table of Contents

Syntax

[TOC]

Result

(on this page) (truncated)

of PyMdown Extensions

Admonition

Syntax

Simple Syntax 
/// note | Custom Title
This is a message with a custom title.
///
/// tip
You can include blocks in admonitions, e.g.

````shell
echo "Hello from an admonition!"
````
///
Explicit Syntax 
/// admonition | Custom Title
    type: note

This is a message with a custom title.
///
/// admonition
    type: tip

You can include blocks in admonitions, e.g.

````shell
echo "Hello from an admonition!"
````
///

Result

Custom Title

This is a note with a custom title.

Tip

You can include blocks in admonitions, e.g.

echo "Hello from an admonition!"

Details/Summary

Syntax

??? "Click to expand"
    This content is collapsible.

Result

??? "Click to expand" This content is collapsible.

HTML

Syntax

/// html | div
I am in a `<div>` with markdown enabled.
///

Result

I am in a <div> with markdown enabled.

Tab

Syntax

/// tab | Tab 1
Content for first tab
///

/// tab | Tab 2
Content for second tab
///

Result

Content for first tab

Content for second tab

Tabbed

Deprecated

This extension is deprecated. Try the blocks.tab extension instead.

Syntax

=== "Tab 1"
    Content for first tab

=== "Tab 2"
    Content for second tab

Result

(if supported)

Content for first tab

Content for second tab

Result

(if disabled)

=== "Tab 1" Content for first tab

=== "Tab 2" Content for second tab

  1. The footnote content. ↩