mkdocs-material¶

Advices¶

avoid use the file-names: system.md, api.md ...

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.

create¶

with command
```
 mkdocs new .

 mkdocs serve
```

with docker

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

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

docker¶

Start development server on http://localhost:8000

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

Build documentation

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

Deploy documentation to GitHub Pages

docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy

Sample¶

an example

site_name: Dean's Docs
site_url: http://139.198.172.85:8000/

nav:
    - Home: index.md
    - Tools:
      - Google-Help: Tools/google-help.md
    - About: about.md
    - License: license.md

theme:
  name: material
  favicon: img/icon.png
  logo: img/fi.jpg
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - content.code.annotate
    - content.tabs.link
    # - navigation.instant
    - navigation.tracking
    # - navigation.tabs
    # - navigation.tabs.sticky
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - search.highlight
    - search.share
    - search.suggest
    # - toc.integrate
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: red
      accent: red
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

markdown_extensions:
  - toc:
      permalink: true
      toc_depth: 3

  - pymdownx.highlight:
      linenums: true
      linenums_style: pymdownx-inline
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.snippets
  - pymdownx.superfences
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.tabbed

extra:
  palette:
    primary: 'Blue Grey'
    accent: 'Pink'