Configuration

Guide to all available configuration settings.

Introduction

Project settings are always configured by using a YAML configuration file in the project directory named mkdocs.yml.

As a minimum this configuration file must contain the site_name setting. All other settings are optional.

Project information

site_name

This is a required setting, and should be a string that is used as the main title for the project documentation. For example:

site_name: Marshmallow Generator

When rendering the theme this setting will be passed as the site_name context variable.

site_url

Set the canonical URL of the site. This will add a link tag with the canonical URL to the generated HTML header.

default: null

repo_url

When set, provides a link to your GitHub or Bitbucket repository on each page.

repo_url: https://github.com/example/repository/

default: null

repo_name

When set, provides a link to your GitHub or Bitbucket repository on each page.

default: 'GitHub' or 'Bitbucket' if the repo_url matches those domains, otherwise null

site_description

Set the site description. This will add a meta tag to the generated HTML header. default: null

site_author

Set the name of the author. This will add a meta tag to the generated HTML header.

default: null

site_favicon

Set the favicon to use. Putting a favicon.ico into the docs/ directory, the config would look as follows:

site_favicon: favicon.ico

default: null

copyright

Set the copyright information to be included in the documentation by the theme.

default: null

google_analytics

Set the Google analytics tracking configuration.

google_analytics: ['UA-36723568-3', 'mkdocs.org']

default: null

remote_branch

Set the remote branch to commit to when using gh-deploy to update Github Pages. This option can be overriden by a commandline option in gh-deploy.

default: gh-pages

Documentation layout

pages

This is setting is used to determine the set of pages that should be built for the documentation.

The setting should be a list. Each row in the list represents information about a single page as a list of strings. The first string represents the path of the documentation source file, and should be relative to the docs_dir setting. Remaining strings represent the title of the page in the site navigation.

Here's a simple example that would cause the build stage to create three pages:

pages:
- 'Introduction': 'index.md'
- 'User Guide': 'user-guide.md'
- 'Abut': 'about.md'

Assuming the docs_dir setting was left with the default value of docs, the source files for this site's build process would be docs/index.md, docs/user-guide.md and docs/about.md.

If you have a lot of project documentation you might choose to use headings to break up your site navigation by category. You can do so by including an extra string in the page configuration for any pages that require a navigation heading, like so:

pages:
- Introduction: 'index.md'
- User Guide:
    - 'Creating a new Marshmallow project': 'user-guide/creating.md'
    - 'Marshmallow API guide': 'user-guide/api.md'
    - 'Configuring Marshmallow': 'user-guide/configuration.md'
- About:
    - License: 'about/license.md'

See also the section on configuring pages and navigation for a more detailed breakdown.

Build directories

theme

Sets the theme of your documentation site, for a list of available themes visit styling your docs.

default: 'mkdocs'

theme_dir

Lets you set a directory to a custom theme. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path.

See styling your docs for an explanation of custom themes.

default: null

docs_dir

Lets you set the directory containing the documentation source markdown files. This can either be a relative directory, in which case it is resolved relative to the directory containing you configuration file, or it can be an absolute directory path.

default: 'docs'

site_dir

Lets you set the directory where the output HTML and other files are created. This can either be a relative directory, in which case it is resolved relative to the directory containing you configuration file, or it can be an absolute directory path.

default: 'site'

site/

extra_css

Set a list of CSS files to be included by the theme.

default: By default extra_css will contain a list of all the CSS files found within the docs_dir, if none are found it will be [] (an empty list).

extra_javascript

Set a list of JavaScript files to be included by the theme.

default: By default extra_javascript will contain a list of all the JavaScript files found within the docs_dir, if none are found it will be [] (an empty list).

extra

A set of key value pairs, where the values can be any valid YAML construct, that will be passed to the template. This allows for great flexibility when creating custom themes.

default: By default extra will be an empty key value mapping.

Preview controls

use_directory_urls

This setting controls the style used for linking to pages within the documentation.

The following table demonstrates how the URLs used on the site differ when setting use_directory_urls to true or false.

The default style of use_directory_urls=true creates more user friendly URLs, and is usually what you'll want to use.

The alternate style can occasionally be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it create links that point directly to the target file rather than the target directory.

default: true

strict

Determines if a broken link to a page within the documentation is considered a warning or an error (link to a page not listed in the pages setting). Set to true to halt processing when a broken link is found, false prints a warning.

default: false

dev_addr

Determines the address used when running mkdocs serve. Setting this allows you to use another port, or allows you to make the service accessible over your local network by using the 0.0.0.0 address.

As with all settings, you can set this from the command line, which can be useful, for example:

mkdocs serve --dev-addr=0.0.0.0:80  # Run on port 80, accessible over the local network.

default: '127.0.0.1:8000'

Formatting options

markdown_extensions

MkDocs uses the Python Markdown library to translate Markdown files into HTML. Python Markdown supports a variety of extensions that customize how pages are formatted. This setting lets you enable a list of extensions beyond the ones that MkDocs uses by default (meta, toc, tables, and fenced_code).

For example, to enable the SmartyPants typography extension, use:

markdown_extensions:
    - smarty

Some extensions provide configuration options of their own. If you would like to set any configuration options, then you can nest a key/value mapping (option_name: option value) of any options that a given extension supports. See the documentation for the extension you are using to determine what options they support.

For example, to enable permalinks in the (included) toc extension, use:

markdown_extensions:
    - toc:
        permalink: True

Note that a colon (:) must follow the extension name (toc) and then on a new line the option name and value must be indented and seperated by a colon. If you would like to define multipe options for a single extension, each option must be defined on a seperate line:

markdown_extensions:
    - toc:
        permalink: True
        separator: "_"

Add an additional item to the list for each extension. If you have no configuration options to set for a specific extension, then simply omit options for that extension:

markdown_extensions:
    - smarty
    - toc:
        permalink: True
    - sane_lists

default: []