Skip to content

Latest commit

 

History

History
505 lines (349 loc) · 9.09 KB

extensions.md

File metadata and controls

505 lines (349 loc) · 9.09 KB

Markdown Extensions

You can extend the functionality of your MkDocs site.

_MkDocs offers a generic guide to extending a MkDocs site{target="blank"}.

[TOC]

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:

<style id="demo-toc-css"> /* to prevent column header from wrapping ONLY in this table */ .demo-toc th { white-space: nowrap; } /* to prevent tables from stretching to fill row height */ .demo-toc { align-items: start; } /* to prevent tables from overlapping each other */ .demo-toc.grid > table { width: fit-content; } </style> <style id="usage-examples-css"> /* to make grid use rows on narrow screens */ .grid { grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); } /* to reduce space between blocks in grid */ .grid { gap: 20px; } .grid > :is( pre, .admonition, .tabbed-set ) { margin-block: 0; } </style>

Abbreviations

/// note | Syntax

The HTML and CSS specifications are maintained by the W3C.

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

/// /// hint | Result

The HTML and CSS specifications are maintained by the W3C.

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

///

HTML Attributes i.e. Attribute Lists { #html-attributes }

/// note | Syntax

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

/// /// hint | Result

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

///

Definition Lists

/// note | Syntax

Term
: Definition of the term
: Another definition

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

/// /// hint | Result

Term : Definition of the term : Another definition

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

///

Fenced Code Blocks

/// note | Syntax

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

/// /// hint | Result

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

///

Footnotes

/// note | Syntax

A sentence with a footnote.[^1]

[^1]: The footnote content.

/// /// hint | Result

A sentence with a footnote.1

///

Markdown in HTML

//// note | Syntax

<div markdown="block">

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

</div>

//// //// hint | Result

I am in a <div> with markdown enabled.

////

Tables

/// note | Syntax

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

/// /// hint | Result

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

///

Admonitions

/// note | Syntax

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

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

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

/// /// hint | Result

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

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

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

///

Table of Contents { #toc }

/// html | div.grid

//// note | Syntax

[TOC]

//// //// hint | Result (on this page) (truncated)

<style id="toc-css"> /* to hide deeply nested TOC items */ .toc ul ul ul ul { display: none; } </style>

[TOC]

////

///

Admonition { #pymdownx-admonition }

/// note | Syntax

//// details | Simple Syntax open: true ///// html | div.grid

/// 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!"

///


/////
////
//// details | Explicit Syntax
///// html | div.grid

```markdown
/// 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!"

///


/////
////

///
/// hint | Result

<div class="grid" markdown="block">

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

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

/////

///

Details/Summary { #pymdownx-details }

/// note | Syntax

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

/// /// hint | Result

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

///

HTML { #pymdownx-html }

/// note | Syntax

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

/// /// hint | Result

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

///

Tab { #pymdownx-tab }

/// note | Syntax

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

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

/// /// hint | Result

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

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

///

Tabbed { #pymdownx-tabbed }

/// warning | Deprecated attrs: { id: pymdownx-tabbed-warning } This extension is deprecated. Try the blocks.tab extension instead. ///

/// note | Syntax

=== "Tab 1"
    Content for first tab

=== "Tab 2"
    Content for second tab

///

/// hint | Result (if supported)

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

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

/// /// error | Result (if disabled)

=== "Tab 1" Content for first tab

=== "Tab 2" Content for second tab

///

Footnotes

  1. The footnote content. ↩