Cinder Theme for MkDocs

About¶

Cinder is a clean, responsive theme for static documentation sites that are generated with MkDocs. It's built on the Bootstrap 3 framework and includes pre-packaged:

highlight.js v9.18.0 syntax highlighting with support for 185 languages (over 30 by default) and over 90 styles
FontAwesome v5.12.0 icon support
smashingly legible type scheme to get your message out to your users

You are viewing the theme in action and can see a selection of the theme elements on the Specimen page.

Install¶

Required: Python 3.4+

Install MkDocs & Create a New Project¶

If you haven't installed MkDocs yet, use the following command to install it:

$ pip install mkdocs

Next, navigate to a clean directory and create a new MkDocs project with the following command:

$ mkdocs new [projectname]

Replace [projectname] with the name of your project (without the brackets).

Then navigate to the root of your project directory:

$ cd [projectname]

Install the Cinder Theme¶

Download the Cinder theme archive by clicking the button below.

Download Cinder

Unpack the contents of the archive into a directory named cinder at the top level of your MkDocs project directory.

Your project directory should now look like this:

.
├── mkdocs.yml
├── cinder
│     ├── css
│     ├── img
│     ├── js
│     ├── base.html
│     ├── content.html
│     ├── 404.html
│     ├── nav-sub.html
│     ├── nav.html
│     └── toc.html
└── docs
      └── index.md

MkDocs projects use a YAML settings file called mkdocs.yml. This is located in the root of your project directory after you use the mkdocs new command. Open the file in a text editor and modify it to include the theme settings as follows:

site_name: [YOURPROJECT]
theme:
  name: null
  custom_dir: 'cinder'
nav:
  - Home: index.md

See the MkDocs documentation for additional details.

Test with a Local Site Server¶

Use the following command to establish a local server for your site:

$ mkdocs serve

Then open your site in any browser at the URL http://localhost:8000.

Create Your Site¶

Add Content with Markdown Syntax¶

Get to work on your site home page by opening the docs/index.md file and editing it in Markdown syntax. The HTML automatically updates in the browser when you save the Markdown file if you use the MkDocs server (see command above).

Add New Pages¶

Add new pages to your site by creating a new Markdown file in your docs directory, then linking to the new page in the mkdocs.yml file. This uses a Page Name : Markdown file syntax.

For example, to add an About page using a Markdown file that is located on the path docs/about.md, you would format the mkdocs.yml file as follows:

site_name: [YOURPROJECT]
theme:
  name: null
  custom_dir: 'cinder'
nav:
  - Home: index.md
  - About: about.md

Add additional pages to your site by repeating the above series of steps.

Build Your Site¶

Build your site files with the command:

$ mkdocs build

Your site files are built in the site directory and are ready to use. Deploy the contents of the site directory to your web server.

Important Configuration Issues¶

1. Set the site_url configuration field¶

You must set the site_url field in your mkdocs.yml file to the appropriate production URL in order to generate a valid sitemap.xml file (issue #80).

Here is an example from the Cinder project mkdocs.yml file:

site_name: Cinder
site_url: https://sourcefoundry.org/cinder/
site_author: Christopher Simpkins
site_description: "A clean, responsive theme for static documentation websites that are generated with MkDocs"
repo_url: "https://github.com/chrissimpkins/cinder"
copyright: "Cinder is licensed under the <a href='https://github.com/chrissimpkins/cinder/blob/master/LICENSE.md'>MIT license</a>"

theme:
  name: null
  custom_dir: cinder
  colorscheme: github
  highlightjs: true
  hljs_languages:
    - yaml

nav:
  - Home: index.md
  - Specimen: specimen.md

markdown_extensions:
  - admonition

The sitemap.xml file will be located at [SITE_URL]/sitemap.xml when you push your site into the production environment. During development the sitemap.xml file can be found at http://127.0.0.1:8000/sitemap.xml.

Site Customization¶

The following are a few common customizations that you might be interested in. For much more detail about the configuration of your site, check out the MkDocs Configuration documentation.

Syntax Highlighting Color Scheme¶

Cinder supports the 90+ highlightjs color schemes. The github color scheme that you see on this page is the default and will be used if you do not specify otherwise.

To change to a different scheme, include the colorscheme field under the theme field in your mkdocs.yml file and enter the color scheme name. For example, to switch to the Dracula theme, enter the following:

theme:
  name: null
  custom_dir: cinder
  colorscheme: dracula

and then rebuild your site.

The color scheme name should match the base name of the highlightjs CSS file. See the src/styles directory of the highlightjs repository for a complete list of these CSS paths.

Syntax Highlighting Language Support¶

By default, Cinder supports the ~30 syntaxes listed under common in the documentation. You can broaden support to any of the over 130 highlightjs languages using definitions in your mkdocs.yml file.

To add a new language, create a list of additional languages as a hljs_languages sub-field under the theme field in the mkdocs.yml file. The definitions are formatted as a newline-delimited list with - characters.

For example, to add support for the Julia and Perl languages, format your configuration file like this:

theme:
  name: null
  custom_dir: cinder
  hljs_languages:
      - julia
      - perl

Use the base file name of the JavaScript files located in the CDN for your syntax definitions.

Site Favicon¶

Create an img subdirectory in your docs directory and add a custom favicon.ico file. See the MkDocs documentation for additional details.

Add Your Own CSS Stylesheets¶

Create a css directory inside your docs directory and add your CSS files. You can overwrite any of the Cinder styles in your CSS files. Then include your CSS files in the mkdocs.yml file with the extra_css field:

site_name: [YOURPROJECT]
theme: cinder
extra_css:
  - "css/mystyle.css"
  - "css/myotherstyle.css"
nav:
  - Home: index.md
  - About: about.md

Your CSS styles fall at the end of the cascade and will override all styles included in the theme (including Bootstrap and default Cinder styles). You can find the Cinder and Bootstrap CSS files on the paths cinder/css/cinder.css and cinder/css/bootstrap.min.css, respectively.

Add Your Own JavaScript¶

Create a js directory inside your docs directory and add your JS files. Then include your JS files in the mkdocs.yml file with the extra_javascript field:

site_name: [YOURPROJECT]
theme: cinder
extra_javascript:
  - "js/myscript.js"
  - "js/myotherscript.js"
nav:
  - Home: index.md
  - About: about.md

Keyboard shortcuts¶

Place the following in your mkdocs.yml file to enable keyboard shortcuts:

shortcuts:
    help: 191    # ?
    next: 39     # right arrow
    previous: 37 # left arrow
    search: 83   # s

The numbers correspond to the key that you would like to use for that shortcut. You can use https://keycode.info/ to find the keycode you want.

Extending Cinder¶

Create a new directory within your project (e.g., cinder-theme-ext/) and create main.html. Add the following line at the top of the HTML file.

{% extends "base.html" %}

Instead of using theme_dir: cinder in mkdocs.yml, use:

theme:
    name: cinder
    custom_dir: [custom dir]

Refer to MkDocs Documentation - Using the theme custom_dir for more information.

Use the following examples as reference. You can put your own Jinja2 within the blocks. More information can be found in MkDocs Documentation - Overriding Template Blocks.

Adding extra HTML to the head tag¶

Append to main.html:

{% block extrahead %}
      <meta name="author" content="{{ page.meta.author }}">
{% endblock %}

Replacing footer¶

Append to main.html:

{% block footer %}
<hr>
<p>{% if config.copyright %}
      <small>{{ config.copyright }}<br></small>
{% endif %}
<small>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</small>
{% if page.meta.revision_date %}
      <small><br><i>Updated {{ page.meta.revision_date }}</i></small>
{% endif %}
</p>
{% endblock %}

page.meta.revision_date can be set by using meta-data (front-matter) at the beginning of your Markdown document or using mkdocs-git-revision-date-plugin.

Github or Bitbucket Repository Link¶

Include the repo_url field and define it with your repository URL:

site_name: [YOURPROJECT]
theme: cinder
repo_url: "https://github.com/chrissimpkins/cinder"
nav:
  - Home: index.md
  - About: about.md

The link appears at the upper right hand corner of your site.

License Declaration and Link¶

The Cinder theme displays your license declaration in the footer if you include a copyright field and define it with the text (and optionally the HTML link) that you would like to display:

site_name: [YOURPROJECT]
theme: cinder
copyright: "Cinder is licensed under the <a href='https://github.com/chrissimpkins/cinder/blob/master/LICENSE.md'>MIT license"
nav:
  - Home: index.md
  - About: about.md

Disabling Theme Features¶

The Cinder theme can turn off some theme features entirely in mkdocs.yml, for situations where you don't need these features. If this is all the customization required, it saves overriding theme files. For example:

theme:
  name: cinder
  # Turn off Previous/Next navigation links in the navbar
  disable_nav_previous_next: true
  # Turn off Search in the navbar
  disable_nav_search: true
  # Turn off the site_name link in the navbar
  disable_nav_site_name: true
  # Turn off the footer entirely
  disable_footer: true
  # Turn off the default footer message, but display the page revision date if it's available
  disable_footer_except_revision: true

Issues¶

If you have any issues with the theme, please report them on the Cinder repository:

Report Issue Active Issues

License¶

Cinder is licensed under the MIT license.