Using and Installing Mkdocs

Source: Using MKDocs to create your documentation

Install mkdocs

Create a python virtual environment

python -m venv venv --prompt="mkdocs"

source venv/bin/activate

pip install mkdocs-material

Create mkdocs in a container

Help

mkdocs -h

mkdocs in a container:

docker pull squidfunk/mkdocs-material

Using mkdocs

In Virtual Environment

Starting & building mkdocs

Start mkdocs:

mkdocs new .

Build mkdocs:

mkdocs build

Test mkdocs:

mkdocs serve

Using Containers

create/initialize:

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

build documentation:

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

previsualize it on http://127.0.0.1:8000

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Configuring mkdocs

file mkdocs.yaml:

site_name: dingoo documentation

theme:
  name: material
  language: en # language of the site
  features:
    - navigation.tabs # To have tabs instead of links
    - navigation.tabs.sticky # So have the tabs always present at the top of the page, event when you scroll down
    - navigation.tracking # the url evolves with the scrolling
    - toc.integrate # to have a toc on the left
    - navigation.top # to have a shorcut to go back on top of the page when we scroll down
    - content.code.copy # to have copy button with code blocks
    - content.code.annotate # to be able to annotate in code blocks


nav:
    - 'home': 'index.md'
    - 'mkdocs basics': 'README.md'


plugins:
  - search
  - offline

markdown_extensions:
  # Required for multiple other extensions
  - attr_list   # required for annotations, icons and emoji
  - md_in_html  # required for icons and emoji
  - pymdownx.superfences    # required for admonitions and code blocks
  # For admonitions
  - admonition
  - pymdownx.details
  - pymdownx.superfences:   # Required for admonitions, diagrams and code blocks
      # For using mermaid for inline diagrams
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  # For using a large database of icons and emojis
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  # For code blocks
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  # For tables
  - tables

extra_javascript:
  # For sortable tables
  # You need to have some javascript code in docs/javascripts/tablesort.js
  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
  - javascripts/tablesort.js

Plugins and extensions

Material plugin and extensions

Material for Mkdocs offer several plugins and extensions.

The documentation of Material for MkDoc

Offline Plugin

By default, if no plugins are configured, the search plugin is activated. However, if you start adding new plugins, you will have to explicitly add the search plugin. Thus we have to add it explicitly with the offline plugin.

Some plugins are not compatible with other plugins and some plugins are available only if you are a sponsor of the project. In each case this is specified in the documentation.

plugins:
  - search
  - offline

Some Extensions:

emojis

admonitions

code blocks

tables

Diagrams