#mkdocs#python#template#tools

Mkdocs for quick static website generator

Published on
•
3 mins read
•
––– views

MkDocs

Project documentation with Markdown.

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Features

  • Great themes available

There's a stack of good looking themes available for MkDocs. Choose between the built in themes: mkdocs and readthedocs, select one of the third-party themes listed on the MkDocs Themes wiki page, or build your own.

  • Easy to customize

Get your project documentation looking just the way you want it by customizing your theme and/or installing some plugins. Modify Markdown's behavior with Markdown extensions. Many configuration options are available.

  • Preview your site as you work

The built-in dev-server allows you to preview your documentation as you're writing it. It will even auto-reload and refresh your browser whenever you save your changes.

  • Host anywhere

MkDocs builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose.

Best example repo for refering Mkdocs is in

Docker - https://github.com/docker/getting-started
git clone https://github.com/docker/getting-started.git

requirements.txt

mkdocs==1.3.0
mkdocs-material==4.6.3
mkdocs-minify-plugin==0.2.3
pygments==2.7.4
pymdown-extensions==7.0

mkdocs.yaml

site_name: Getting Started
site_description: Getting Started with Docker
site_author: Docker
# site_url: https://squidfunk.github.io/mkdocs-material/


# Repository
repo_name: docker/getting-started
repo_url: https://github.com/docker/getting-started
edit_uri: ""


# Copyright
copyright: 'Copyright © 2020-2022 Docker'


# Configuration
theme:
  name: material
  language: en
  palette:
    primary: blue
    accent: blue
  font:
    text: Roboto
    code: Roboto Mono
  favicon: assets/images/favicon.png
  logo: 'images/docker-labs-logo.svg'


extra_css:
  - css/styles.css
  - css/dark-mode.css


# Plugins
plugins:
  - search
  - minify:
      minify_html: true


# Customization
extra:
  social:
    - type: github-alt
      link: https://github.com/docker/getting-started


# Extensions
markdown_extensions:
  - meta
  - markdown.extensions.admonition
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.footnotes
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.inlinehilite
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: dockersamples
      repo: 101-tutorial
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  - attr_list


# Page tree
nav:
  - Getting Started: tutorial/index.md
  - Our Application: tutorial/our-application/index.md
  - Updating our App: tutorial/updating-our-app/index.md
  - Sharing our App: tutorial/sharing-our-app/index.md
  - Persisting our DB: tutorial/persisting-our-data/index.md
  - Using Bind Mounts: tutorial/using-bind-mounts/index.md
  - Multi-Container Apps: tutorial/multi-container-apps/index.md
  - Using Docker Compose: tutorial/using-docker-compose/index.md
  - Image Building Best Practices: tutorial/image-building-best-practices/index.md
  - What Next?: tutorial/what-next/index.md

#mythoughts

Discuss on Twitter • View on GitHub