MkDocs Recipes

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

Bold H2 titles in the menu

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.

Dark Theme Syntax Highlighting

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

Replace JavaScript code highlighting with Pygments

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

Add Support for Checkbox Lists

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

Associate github page with current mkdoc page

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]

Remove the "Table of Contents" sidebar from the mkdocs theme.

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.

Add Open graph and Twitter Card

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.

Add *apple-touch-icon.png`

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.

Lightbox Add-on using theme_dir

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