A collection of user submitted snippets to customize your MkDocs site in various ways. Please add your own.

Submitted by @yPhil.

• Add a custom css
• Then in this CSS, add

li.toctree-l2 > a:link,
li.toctree-l2 > a:visited {
  font-weight: bold;
  color: #404040;
  margin-left: -6px;
}

Then, all the H2/level two "## Chapter title" entries will be more clearly identified as actual chapters of your text.

Submitted by @grbd in #821.

First create a css file to remove the border and make the background transparent for code blocks, this is needed for dark themes.

docs\css\highlight-fix.css

pre {
  background-color: transparent;
  border: none;
}

code {
  background-color: transparent;
}

Next edit mkdocs.yml to add a section to tweak the css

extra_css:
    - css/highlight-fix.css

To use custom highting themes grab the css of one you like from https://highlightjs.org/static/demo/ (for example Atelier Cave Dark for a dark theme) paste it into a file such as highlight-custom.css

Then also add this to the extra_css section

extra_css:
    - css/highlight-fix.css
    - css/highlight-custom.css

See #1019. TODO: Flesh this out...

As suggest in #748

Install the Pymdown Tasklist Extension

pip install --upgrade pymdown-extensions

Enable the extension in your mkdown.yml config file:

markdown_extensions:
    - pymdownx.tasklist

Add some CSS to style your task lists by creating a css/custom.css file:

.task-list-item {
  list-style-type: none;
}

.task-list-item input {
  margin: 0 4px 0.25em -20px;
  vertical-align: middle;
}

And add that file to your mkdocs.yml config file:

extra_css:
    - css/custom.css

Add an extra js to enable: when click the "git" button, go to the github page corresponding with current page. It is like a wiki page -- when you want to modify something, go to do it.

add extra.js in your docs dir like below:

$(document).ready(function(){
    var git = 'http://github.com/<your github account>/<your repo name>/edit/master/docs'
    var t1 = window.location.pathname
    var url = null
    if (t1=='/'){
        url = git + '/index.md'
    }else{
        url = git+t1.substr(0, t1.length-1)+'.md'
    }   
    a_git = $('[href="https://github.com/<your github account>/<your repo name>"]')
    a_git.attr('href', url).attr('target', '_blank')
})

modify mkdocs.yml to enable:

extra_javascript: [extra.js]

Note: This only works on version 0.16 or later.

Adjacent to your mkdocs.yml config file and the docs directory, add a new directory custom_theme (or whatever name you choose). Then edit the mkdocs.yml file to point to it:

theme: mkdocs
theme_dir : custom_theme

With the release of version 1.0, the syntax has changed (see: https://www.mkdocs.org/about/release-notes/#theme_dir-configuration-option-fully-deprecated):

theme:
    name: mkdocs
    custom_dir: custom_theme

Note that we need to explicitly name the parent theme (via theme: mkdocs) or MkDocs will assume a complete theme is contained in the theme_dir. Instead we will only be overriding a small part of the parent theme.

Finally, create a new file custom_theme/main.html and add the following to it:

{% extends "base.html" %}

{% block content %}
    <div class="col-md-12" role="main">{% include "content.html" %}</div>
{% endblock %}

That's it. The new content block will replace the content block defined in the mkdocs theme with one which does not insert the TOC. Note that if you are using a different theme than the mkdocs theme, the above may need to be adapted to work with your theme.

Note: You can use mkdocs and mkdocs-bootswatch, but some themes may not.

Overwrite the theme in the same way as above.

mkdocs.yml:

theme:
    name: mkdocs
    custom_dir: custom_theme

custom_theme/main.html:

{% extends "base.html" %}

{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.title and not page.is_homepage %}
    {% set title = page.title ~ " - " ~ config.site_name | striptags %}
  {% endif %}
  {% set description = config.site_description %}
  {% if page and page.meta.description %}
    {% set description = page.meta.description %}
  {% endif %}
  {% set image = config.site_url ~ 'ogp.png' %}
  {% if page and page.meta.image %}
    {% set image = config.site_url ~ page.meta.image %}
  {% endif %}
<meta property="og:type" content="website">
<meta property="og:title" content="{{ title }}">
<meta property="og:description" content="{{ description }}">
<meta property="og:url" content="{{ page.canonical_url }}">
<meta property="og:image" content="{{ image }}">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{{ title }}">
<meta name="twitter:description" content="{{ description }}">
<meta name="twitter:image" content="{{ image }}">
{% endblock %}

The default image is (docs/) ogp.png. It can be changed page by page using the image of front matter.

Note: You can use mkdocs and mkdocs-bootswatch, but some themes may not.

Overwrite the theme in the same way as above.

mkdocs.yml:

theme:
    name: mkdocs
    custom_dir: custom_theme

custom_theme/main.html:

{% extends "base.html" %}

{% block extrahead %}
 <link rel="apple-touch-icon" sizes="256x256" href="/img/apple-touch-icon.png">
{% endblock %}

Place it in (docs)/img/apple-touch-icon.png. (It's the same place as favicon.ico. Does not consider the project page!)
This size is 256x256 pixels. Please change if necessary.

See the example repo for a complete working example. Details are provided in the README.

This hook reads the file /includes/abbreviations.yaml into a dictionary and then inserts it into the MkDocs configuration for abbr's glossary option. You can change the file path (abbr_path) to fit your needs.

abbr_import.py:

"""
Import a glossary to the abbreviations plugin by reading a YAML file
and passing it to the `glossary` option for `abbr`.

This option is added in Python Markdown 3.7.
"""

import yaml
from mkdocs.config import Config
from pathlib import Path
from packaging.version import parse as parse_version
import markdown
import logging

log = logging.getLogger(f"mkdocs.plugins.{__name__}")

abbr_path = '/includes/abbreviations.yaml'


def on_config(config: Config, **kwargs):
    """Run when MkDocs parses the 'mkdocs.yml' file

    :param config: The MkDocs configuration object
    :type config: Config
    :return: The MkDocs configuration object
    :rtype: Config
    """
    try:
        if ('abbr' in config['markdown_extensions'] and
                parse_version(markdown.__version__) >= parse_version("3.7")):
            definitions_file = Path('..' + abbr_path)

            doc_folder = Path(config.data.get("docs_dir"))
            definitions_file = doc_folder.joinpath(definitions_file).resolve()

            # Load definitions from file
            with open(definitions_file, 'r', encoding='utf-8') as f:
                # importing the YAML file as a dictionary
                abbr_plugin = yaml.safe_load(f)
                if 'abbr' not in config['mdx_configs']:
                    config['mdx_configs']['abbr'] = {}

                # Because extensions are loaded again by Python Markdown
                # altering the MkDocs configuration for the extension
                # allows the glossary to be consistently applied.
                config['mdx_configs']['abbr']['glossary'] = abbr_plugin

                log.info('Loaded: ' + abbr_path)
    except FileNotFoundError:
        log.warning("Could not find " + abbr_path)

    return config

mkdocs.yaml:

hooks:
  - abbr_import.py