-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
MkDocs Recipes
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.