Skip to content

Afridyne Systems™

© Afridyne Systems™ ➠ MkDocs ➻ MaterialX

For full Documentation visit: mkdocs.org.

Advanced Configuration⚓︎

  • MaterialX for MkDocs comes with many configuration options.

  • The setup section explains in great detail how to configure and customize colors, fonts, icons and much more:

  • Changing the Colors
    View Guide

    Customise primary and accent colors to match your brand identity.

  • Changing the Fonts
    View Guide

    Configure Google Fonts or custom web fonts for typography.

  • Changing the Language
    View Guide

    Localize your site interface and search into 50+ languages.

  • Changing the Logo
    View Guide

    Set a custom logo and choose from thousands of integrated icons.

  • Data Privacy
    View Guide

    Enable GDPR-compliant features and cookie consent management.

  • Site Navigation
    View Guide

    Define your site structure, tabs, and table of contents behavior.

  • Site Search
    View Guide

    Configure the built-in search engine with highlighting and indexing.

  • Site Analytics
    View Guide

    Integrate Google Analytics or other privacy-focused tracking tools.

  • The Header
    View Guide

    Customize the sticky header, search bar, and repository links.

  • The Footer
    View Guide

    Manage "Previous/Next" buttons and the copyright notice area.

  • Social Cards
    View Guide

    Generate automatic preview images for Twitter and LinkedIn shares.

  • Setting up a Blog
    View Guide

    Transform your documentation into a fully-featured technical blog.

  • Setting up Tags
    View Guide

    Organize content with categories and tags for easier discovery.

  • Versioning
    View Guide

    Host multiple versions of your documentation simultaneously.

  • Git Repository
    View Guide

    Link your source code to enable "Edit this page" functionality.

  • Comment System
    View Guide

    Integrate Giscus or Disqus to build community engagement.

  • Optimization
    View Guide

    Minify CSS/JS and optimize images for lightning-fast loading.

  • Offline Usage
    View Guide

    Package your documentation for use without an internet connection.

Supported Markdown Extensions

Furthermore, see the list of supported Markdown extensions that are natively integrated with Material for MkDocs.

Commands⚓︎

The Basic 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⚓︎

Project Layout

docs/
  index.md # The documentation homepage.
  ... # Other markdown pages.
mkdocs.yml # The configuration file.

mkdocs.yml    # (1)
docs/
    index.md  # (2)
    ...       # (3)
  1. Configuration: Where you enable all those cool extensions.
  2. Homepage: The main entry point for your site.
  3. Other Pages: Any additional markdown files.

Getting Started⚓︎

MaterialX for MkDocs is a powerful documentation framework on top of MkDocs, a static site generator for project documentation.1 If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.

Installation⚓︎

With pip recommended.⚓︎

MaterialX for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install Material for MkDocs with:

Installation

pip install mkdocs-materialx

pip install mkdocs-materialx=="10.2.0"

pip install --upgrade mkdocs-materialx

This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. MaterialX always strives to support the latest versions, so there's no need to install those packages separately.

How to set up Material for MkDocs by @james-willett – 27m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

If you don't have prior experience with Python, we recommend reading Using Python's pip to Manage Your Projects' Dependencies, which is a really good introduction on the mechanics of Python package management and helps you troubleshoot if you run into errors.

With Docker⚓︎

With Docker

The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Open up a terminal and pull the image with:

docker pull jaywhj/mkdocs-materialx

docker pull jaywhj/mkdocs-materialx:10.1.8
Selected Plugins
MaterialX for MkDocs only bundles selected plugins in order to keep the size of the official
image small. If the plugin you want to use is not included, you can add them easily. Create
a `Dockerfile` and extend the official image:
Dockerfile
FROM jaywhj/mkdocs-materialx
RUN pip install mkdocs-glightbox

Build the Image⚓︎

Build the Image

docker build -t materialx .

Run the Container⚓︎

Run the Container

docker run -p 8000:8000 -v ${PWD}:/docs materialx

With Git⚓︎

With Git

MaterialX for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:

You can clone the source code from a GitHub repo via git clone and install it locally:

git clone https://github.com/jaywhj/mkdocs-materialx.git

Next, install it with the following command

pip install -e mkdocs-materialx

The following plugins are bundled with the Docker image:

Docker Container is Intended for Local Previewing Purposes Only!

The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

How to add plugins to the Docker image?

Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily. Create a Dockerfile and extend the official image:

Dockerfile
FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

Next, build the image with the following command:

docker build -t squidfunk/mkdocs-material .

The new image will have additional packages installed and can be used exactly like the official image.

Python Markdown Extensions⚓︎

The Python Markdown Extensions package is an excellent collection of additional extensions perfectly suited for advanced technical writing. Material for MkDocs lists this package as an explicit dependency, so it's automatically installed with a supported version.

Supported Extensions⚓︎

In general, all extensions that are part of Python Markdown Extensions should work with Material for MkDocs. The following list includes all extensions that are natively supported, meaning they work without any further adjustments.

Arithmatex⚓︎

Arithmatex

The Arithmatex extension allows for rendering of block and inline block equations and integrates seamlessly with MathJax2 – a library for mathematical typesetting. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

Besides enabling the extension in mkdocs.yml, a MathJax configuration and the JavaScript runtime need to be included, which can be done with a few lines of additional JavaScript:

Arithmatex

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"], ["$", "$"]],
    displayMath: [["\\[", "\\]"], ["$$", "$$"]],
    processEscapes: true,
    processEnvironments: true,
    packages: {'[+]': ['color']}
  },
  loader: {
    load: ['[tex]/color']
  },
  options: {
    ignoreHtmlClass: ".*",
    processHtmlClass: "arithmatex",
    menuOptions: {
      settings: {
        zoom: 'Click',
        zscale: '200%'
      }
    }
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})
  1. This integrates MathJax with instant loading
extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.

See reference for usage:

  • Installation Guide
    View Guide

    Step-by-step instructions to get MkDocs up and running.

  • Configuration (docs_dir)
    View Config

    Learn how to set up your source directory structure.

  • Deploying Your Docs
    View Guide

    How to publish your documentation to the web.

  • Documentation Layout
    View Layout

    Configure the navigation and global site structure.

  • GitHub Discussions
    Join Discussions

    Ask questions and engage with the community.

  • GitHub Issues
    View Issues

    Report bugs or request new features.

  • Site Name
    View Settings

    Define the title of your project and browser tab.

  • Theme
    View Theme

    Customise the look and feel of your documentation.

  • User Guide
    Open Guide

    The complete manual for all MkDocs features.

  1. In 2016, MaterialX for MkDocs started out as a simple theme for MkDocs, but over the course of several years, it's now much more than that – with the many built-in plugins, settings, and countless customization abilities, Material for MkDocs is now one of the simplest and most powerful frameworks for creating documentation for your project. ↩

  2. Other libraries like KaTeX are also supported and can be integrated with some additional effort. See the Arithmatex documentation on KaTeX for further guidance, as this is beyond the scope of Material for MkDocs. ↩