Skip to content

MkDocs#

Material for MkDocs#

Material for MkDocs is a theme for MkDocs that adds many features to build beautiful documentation on the web.

Documentation of example project built with Material for MkDocs

Actually, this documentation happens to be built with Material for MkDocs too, so yours will likely look similar.

Configuration#

MkDocs is configured in the mkdocs.yml file in the root of your project.

mkdocs.yml 
site_name: Sample Project

repo_url: https://github.com/mkj/sample-project
repo_name: sample-project
site_url: https://mkj.github.io/sample-project
edit_uri: -/edit/main/docs/

theme:
  name: material

plugins:
  - search
  - git-revision-date-localized: # https://timvink.github.io/mkdocs-git-revision-date-localized-plugin
      type: timeago
      fallback_to_build_date: true
  - mkdocstrings: # see https://mkdocstrings.github.io/
      default_handler: python
      enable_inventory: true
      handlers:
        python:
          paths: [src]
          options:
            show_root_heading: true
            show_category_heading: false
            show_submodules: true
          import:
            - https://numpy.org/doc/stable/objects.inv
  - macros: # see https://mkdocs-macros-plugin.readthedocs.io/
      include_dir: .
      module_name: docs/macros

Extensions#

mkdocstrings#

Repository Documentation

mkdocs-macros#

Repository Documentation

Use Jinja template expressions in your markdown documentation.

mkdocs-macros-includex#

Repository Documentation

Include content from any file in your repository for documentation purposes.