[mkdocs] My favorite dockerfile config for mkdocs with lots of cool plugins #mkdocs #markdown

config.yml

site_name: MyDocSite
repo_url: https://github.com/org/repo
use_directory_urls: true
edit_uri: edit/master/docs
site_description: markdown to mkdocs site
docs_dir: docs
site_dir: _site
google_analytics:


markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
      linenums: true
  - pymdownx.inlinehilite
  - pymdownx.extra
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.keys
  - pymdownx.snippets
  - pymdownx.tasklist:
      custom_checkbox: true
  - toc:
      permalink: true
      separator: "-"
      baselevel: 2
  - attr_list
  - footnotes
  - abbr
  - meta
  - markdown_include.include:
      base_path: docs
      inheritHeadingDepth: true

plugins:
  - search
  - codeinclude
  - macros
  - autolinks
  - git-committers
  - tags:
      tags_folder: docs
      tags_template: assets/template/tags.md
  - mkdocs-new-features-notifier
  - git-revision-date-localized:
      fallback_to_build_date: true
  - exclude: #https://pypi.org/project/mkdocs-exclude/
      glob:
        - '_Sidebar.md'
        - 'home.md'
        #- '*.ps1'
        - '*.psd1'
        - '*.tf'
        - '*.tfstate'
        - '.tfstate'
        - '*.yml'
        - '*.json'
        - '*.xml'
        - '_Footer.md'
        - 'versions.txt'
  - nbconvert:
        input_dir: docs
        recursive: true
        output_dir: notebooks

theme:
  name: material
  custom_dir: overrides
  palette:
    scheme: slate
    primary: indigo
    accent: light blue


  features:
      - navigation.expand
      - instant
      - tabs
      - toc.autohide
      - search.highlight
  font:
    text: Raleway
    code: JetBrainsMono
  extra:
    disqus: foobar
  icon:
    repo: fontawesome/brands/github

  # markdown_extensions:
  extra_javascript:
    - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
    #- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
    - javascripts/tables.js
    - javascripts/committers.js
    - javascripts/config.js
    - javascripts/highlight.pack.js
  extra_css:
    - stylesheets/extra.css
    - stylesheets/gruvbox-dark.css
#    - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/gruvbox-dark.min.css

module_name: main

Dockerfile

# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.141.0/containers/python-3/.devcontainer/base.Dockerfile
# [Choice] Python version: 3, 3.8, 3.7, 3.6
ARG VARIANT="3.8"
FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}

# [Option] Install Node.js
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "${INSTALL_NODE}" = 'true' ]; Then su vscode -c "source /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi

RUN apt update && apt-get -qqy install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info

RUN pip3 install --upgrade -q pip
RUN pip3 install mkdocs --progress-bar pretty -q
RUN pip3 install --progress-bar pretty -q mkdocs-monorepo-plugin \
    install mkdocs-simple-plugin \
    mkdocs-new-features-notifier \
    mkdocs-plugin-progress \
    mkdocs-exclude \
    mkdocs-awesome-pages-plugin \
    mkdocs-nav-enhancements \
    mkdocs-toc-sidebar-plugin \
    mkdocs-git-committers-plugin-2 \
    mkdocs-print-site-plugin \
    git+https://github.com/jldiaz/mkdocs-plugin-tags\
    git+https://github.com/andyoakley/mkdocs-jinja2 \
    mkdocs-autolinks-plugin \
    mkdocs-nbconvert \
    mkdocs-jupyter \
    mknotebooks \
    markdown-include \
    mkdocs-minify-plugin \
    mkpdfs-mkdocs \
    git+https://github.com/andyoakley/mkdocs-nbconvert/ \
    mkdocs-user-defined-values \
    git+https://github.com/rnorth/mkdocs-codeinclude-plugin \
    git+https://github.com/effigies/mkdocs-branchcustomization-plugin \
    mkdocs-git-revision-date-localized-plugin \
    mkdocs-git-authors-plugin \
    mkdocs-table-reader-plugin \
    mkdocs-mermaid2-plugin \
    mkdocs-build-plantuml-plugin \
    mkdocs-macros-plugin

# Stuff I don't use
# https://github.com/cmacmackin/markdown-include
# git+https://github.com/pauloue/mkdocs-autoreflinks-plugin \
# git+https://github.com/rkoe/mkdocs-emailprotect \
# mkdocs-tooltipster-links-plugin \
# git+https://github.com/cmitu/mkdocs-altlink-plugin/ \
# mkdocs-bootstrap-tables-plugin \
# mkdocs-snippet-plugin \

RUN pip3 install --progress-bar pretty -q mkdocs-material
WORKDIR /docs

#ENTRYPOINT [ "mkdocs" ]
# CMD ["serve", "--dev-addr=0.0.0.0:8000"]

markdown.code-snippets

{
    // Place your snippets for markdown here. Each snippet is defined under a snippet name and has a prefix, body and
    // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
    // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the
    // same ids are connected.
    // Example:
    // "Print to console": {
    // 	"prefix": "log",
    // 	"body": [
    // 		"console.log('$1');",
    // 		"$2"
    // 	],
    // 	"description": "Log output to console"
    // }
    "mkdocs-codeinclude": {
        "prefix": "mkdocs-codeinclude",
        "description": "Include the contents of a code file in a markdown document using the plugin: https://github.com/rnorth/mkdocs-codeinclude-plugin",
        "body": [
            "<!--codeinclude-->",
            "[${1:HumanReadableTitle}](./${2:relative_path_to_example_code})",
            "<!--/codeinclude-->"
        ]
    },
    "reveal-md-fragment": {
        "scope": "markdown",
        "prefix": "fragment",
        "body": "{.fragment ${1|.fade-out,.fade-in-then-out,.fade-in-then-semi-out,.current-visible,.fade-down,.fade-right,.fade-left,.grow,.shrink,.highlight-red,.highlight-blue,.highlight-green|}}",
        "description": "Makes the current element a fragment"
    },
    "reveal-md-focus-on-code": {
        "scope": "markdown",
        "prefix": "reveal-md-focus-on-code",
        "body": "{.fragment .current-only data-code-focus=${LinesToFocusOn}",
        "description": "Makes the current element a fragment with focus on specific code lines from prior code block"
    }
}