Help for MkDocs & Material

For full documentation visit mkdocs.org.

Commands

mkdocs new [dir-name] - Create a new project.
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs -h - Print help message and exit.

Project Layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Load Environment

source /usr/local/miniconda2/bin/activate mkdocs20
mkdocs -V

Basics

Extensions

Table of Contents - permalink

markdown_extensions:
  - toc:
      permalink: true

Creates Elements - admonition

markdown_extensions:
  - admonition

Notes

test

PyMdown Extensions

Emphasis - betterem

*All will * be italic*

All will * be italic

**All will * be bold**

All will * be bold

Marker - mark

==mark me==

mark me

Code highlighting - highlight & SuperFences

# Listing
ls -alxh

import foo.bar

Line numbers:

1	`import foo.bar`

Highlighting lines:

grep ">" seq.fa
grep ">" -c seq.fa
grep ">" -v seq.fa

Mermaid for Diagrams (colliding with highlights)

https://github.com/fralau/mkdocs-mermaid2-plugin

#```mermaid
#graph TD
#     A[Hard] -->|Text| B(Round)
#     B --> C{Decision}
#     C -->|One| D[Result 1]
#     C -->|Two| E[Result 2]
#```

Creates Collapsible Elements - details

markdown_extensions:
  - pymdownx.details

Summary

Some content.

Open styled details

Nested details!

And more content again.

Superscript - caret

markdown_extensions:
  - pymdownx.caret

H^2O ➜ H²O

test^a^ ➜ text^a

Tilde extension - tilde

~~Delete me~~

~~Delete me~~

CH~3~CH~2~OH

CH₃CH₂OH

Emoji extension - emoji

:smile: :heart: :thumbsup:

Creating Special Characters - smartsymbols

(tm) (c) +/- 1/2

™ © ± ½

Tasklist

- [X] item 1
    * [X] item A
    * [ ] item B
        more text
        + [x] item a
        + [ ] item b
        + [x] item c
    * [X] item C
- [ ] item 2
- [ ] item 3

Tasklist-Test:

<ul class="task-list">
    <li class="task-list-item">
        <label class="task-list-control">
            <input type="checkbox" checked="">
            <span class="task-list-indicator"></span>
        </label>
        item 1
    </li>
</ul>

item 1