From c6173e13a60933d9b4e2a90bf03430bb2f6830f6 Mon Sep 17 00:00:00 2001
From: Oleh Prypin <oleh@pryp.in>
Date: Tue, 12 Oct 2021 23:56:23 +0200
Subject: [PATCH] Deployed ca651fbe0 with MkDocs version: 1.2.3

---
 about/contributing/index.html               |   8 ++--
 about/release-notes/index.html              |  40 ++++++++++++++++++++
 dev-guide/plugins/index.html                |   6 +--
 dev-guide/themes/index.html                 |  11 +++---
 index.html                                  |   7 ++--
 js/a.js                                     |   1 -
 js/base.js                                  |   2 +-
 search/search_index.json                    |   2 +-
 sitemap.xml                                 |  34 ++++++++---------
 sitemap.xml.gz                              | Bin 347 -> 346 bytes
 user-guide/choosing-your-theme/index.html   |   6 +++
 user-guide/configuration/index.html         |   9 +++--
 user-guide/installation/index.html          |   2 +-
 user-guide/localizing-your-theme/index.html |   2 +-
 14 files changed, 90 insertions(+), 40 deletions(-)
 delete mode 100644 js/a.js

diff --git a/about/contributing/index.html b/about/contributing/index.html
index 97d6a413..f8d06540 100644
--- a/about/contributing/index.html
+++ b/about/contributing/index.html
@@ -245,18 +245,20 @@ Then the test suite can be run for MkDocs by running the command <code>tox</code
 root of your MkDocs repository.</p>
 <p>It will attempt to run the tests against all of the Python versions we
 support. So don't be concerned if you are missing some and they fail. The rest
-will be verified by <a href="https://travis-ci.org/repositories">Travis</a> when you submit a pull request.</p>
+will be verified by <a href="https://docs.github.com/actions">Github Actions</a> when you submit a pull request.</p>
 <h2 id="translating-themes">Translating themes<a class="headerlink" href="#translating-themes" title="Permanent link"></a></h2>
 <p>To localize a theme to your favorite language, follow the guide on <a href="../../dev-guide/translations/">Translating
 Themes</a>. We welcome translation Pull Requests!</p>
 <h2 id="submitting-pull-requests">Submitting Pull Requests<a class="headerlink" href="#submitting-pull-requests" title="Permanent link"></a></h2>
-<p>Once you are happy with your changes or you are ready for some feedback, push
+<p>If you're considering a large code contribution to MkDocs, please prefer to
+open an issue first to get early feedback on the idea.</p>
+<p>Once you think the code is ready to be reviewed, push
 it to your fork and send a pull request. For a change to be accepted it will
 most likely need to have tests and documentation if it is a new feature.</p>
 <h3 id="submitting-changes-to-the-builtin-themes">Submitting changes to the builtin themes<a class="headerlink" href="#submitting-changes-to-the-builtin-themes" title="Permanent link"></a></h3>
 <p>When installed with <code>i18n</code> support (<code>pip install mkdocs[i18n]</code>), MkDocs allows
 themes to support being translated into various languages (referred to as
-locales) if they respect <a href="https://jinja.palletsprojects.com/en/master/extensions/#i18n-extension">Jinja's i18n extension</a> by wrapping text placeholders
+locales) if they respect <a href="https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension">Jinja's i18n extension</a> by wrapping text placeholders
 with <code>{% trans %}</code> and <code>{% endtrans %}</code> tags.</p>
 <p>Each time a translatable text placeholder is added, removed or changed in a
 theme template, the theme's Portable Object Template (<code>pot</code>) file needs to be
diff --git a/about/release-notes/index.html b/about/release-notes/index.html
index 4bd40f49..850c1fa3 100644
--- a/about/release-notes/index.html
+++ b/about/release-notes/index.html
@@ -174,6 +174,10 @@
               <ul class="nav flex-column">
               </ul>
             </li>
+            <li class="nav-item" data-level="2"><a href="#version-123-2021-10-12" class="nav-link">Version 1.2.3 (2021-10-12)</a>
+              <ul class="nav flex-column">
+              </ul>
+            </li>
             <li class="nav-item" data-level="2"><a href="#version-122-2021-07-18" class="nav-link">Version 1.2.2 (2021-07-18)</a>
               <ul class="nav flex-column">
               </ul>
@@ -342,6 +346,42 @@ mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6)
 <li><a href="https://github.com/d0ugal/">@d0ugal</a></li>
 <li><a href="https://github.com/waylan/">@waylan</a></li>
 </ul>
+<h2 id="version-123-2021-10-12">Version 1.2.3 (2021-10-12)<a class="headerlink" href="#version-123-2021-10-12" title="Permanent link"></a></h2>
+<ul>
+<li>
+<p>Built-in themes now also support these languages:</p>
+<ul>
+<li>Simplified Chinese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2497" title="GitHub Issue mkdocs/mkdocs #2497">#2497</a>)</li>
+<li>Japanese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2525" title="GitHub Issue mkdocs/mkdocs #2525">#2525</a>)</li>
+<li>Brazilian Portuguese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2535" title="GitHub Issue mkdocs/mkdocs #2535">#2535</a>)</li>
+<li>Spanish (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2545" title="GitHub Issue mkdocs/mkdocs #2545">#2545</a>, previously <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2396" title="GitHub Issue mkdocs/mkdocs #2396">#2396</a>)</li>
+</ul>
+</li>
+<li>
+<p>Third-party plugins will take precedence over built-in plugins with the same
+  name (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2591" title="GitHub Issue mkdocs/mkdocs #2591">#2591</a>)</p>
+</li>
+<li>
+<p>Bugfix: Fix ability to load translations for some languages:
+  core support (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2565" title="GitHub Issue mkdocs/mkdocs #2565">#2565</a>) and search plugin support with fallbacks (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2602" title="GitHub Issue mkdocs/mkdocs #2602">#2602</a>)</p>
+</li>
+<li>
+<p>Bugfix (regression in 1.2): Prevent directory traversal in the dev server
+  (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2604" title="GitHub Issue mkdocs/mkdocs #2604">#2604</a>)</p>
+</li>
+<li>
+<p>Bugfix (regression in 1.2): Prevent webserver warnings from being treated as
+  a build failure in strict mode (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2607" title="GitHub Issue mkdocs/mkdocs #2607">#2607</a>)</p>
+</li>
+<li>
+<p>Bugfix: Correctly print colorful messages in the terminal on Windows (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2606" title="GitHub Issue mkdocs/mkdocs #2606">#2606</a>)</p>
+</li>
+<li>
+<p>Bugfix: Python version 3.10 was displayed incorrectly in <code>--version</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2618" title="GitHub Issue mkdocs/mkdocs #2618">#2618</a>)</p>
+</li>
+</ul>
+<p>Other small improvements; see
+<a href="https://github.com/mkdocs/mkdocs/compare/1.2.2...1.2.3">commit log</a>.</p>
 <h2 id="version-122-2021-07-18">Version 1.2.2 (2021-07-18)<a class="headerlink" href="#version-122-2021-07-18" title="Permanent link"></a></h2>
 <ul>
 <li>
diff --git a/dev-guide/plugins/index.html b/dev-guide/plugins/index.html
index db279688..4296ba55 100644
--- a/dev-guide/plugins/index.html
+++ b/dev-guide/plugins/index.html
@@ -384,7 +384,7 @@ be used to alter the site navigation.</p>
 <dl>
 <dd>
 <p>The <code>env</code> event is called after the Jinja template environment is created
-and can be used to alter the <a href="https://jinja.palletsprojects.com/en/master/api/#jinja2.Environment">Jinja environment</a>.</p>
+and can be used to alter the <a href="https://jinja.palletsprojects.com/en/latest/api/#jinja2.Environment">Jinja environment</a>.</p>
 <dl>
 <dt>Parameters:</dt>
 <dd><strong>env:</strong> global Jinja environment</dd>
@@ -626,7 +626,7 @@ class MyPlugin(BasePlugin):
 </code></pre>
 <h3 id="entry-point">Entry Point<a class="headerlink" href="#entry-point" title="Permanent link"></a></h3>
 <p>Plugins need to be packaged as Python libraries (distributed on PyPI separate
-from MkDocs) and each must register as a Plugin via a setuptools entry_point.
+from MkDocs) and each must register as a Plugin via a setuptools <code>entry_points</code>.
 Add the following to your <code>setup.py</code> script:</p>
 <pre><code class="language-python">entry_points={
     'mkdocs.plugins': [
@@ -639,7 +639,7 @@ Add the following to your <code>setup.py</code> script:</p>
 (<code>from path.to.some_plugin import SomePluginClass</code>) where <code>SomePluginClass</code> is a
 subclass of <a href="#baseplugin">BasePlugin</a> which defines the plugin behavior. Naturally, multiple
 Plugin classes could exist in the same module. Simply define each as a separate
-entry_point.</p>
+entry point.</p>
 <pre><code class="language-python">entry_points={
     'mkdocs.plugins': [
         'featureA = path.to.my_plugins:PluginA',
diff --git a/dev-guide/themes/index.html b/dev-guide/themes/index.html
index e84a63b8..45aae104 100644
--- a/dev-guide/themes/index.html
+++ b/dev-guide/themes/index.html
@@ -595,7 +595,7 @@ following <code>extra</code> configuration:</p>
 {% endif %}
 </code></pre>
 <h2 id="template-filters">Template Filters<a class="headerlink" href="#template-filters" title="Permanent link"></a></h2>
-<p>In addition to Jinja's default filters, the following custom filters are
+<p>In addition to <a href="https://jinja.palletsprojects.com/en/latest/templates/#builtin-filters">Jinja's default filters</a>, the following custom filters are
 available to use in MkDocs templates:</p>
 <h3 id="url">url<a class="headerlink" href="#url" title="Permanent link"></a></h3>
 <p>Normalizes a URL. Absolute URLs are passed through unaltered. If the URL is
@@ -749,9 +749,9 @@ setup(
 )
 </code></pre>
 <p>Fill in the URL, license, description, author and author email address.</p>
-<p>The name should follow the convention <code>mkdocs-themename</code> (like <code>mkdocs-
-bootstrap</code> and <code>mkdocs-bootswatch</code>), starting with MkDocs, using hyphens to
-separate words and including the name of your theme.</p>
+<p>The name should follow the convention <code>mkdocs-themename</code> (like
+<code>mkdocs-bootstrap</code> and <code>mkdocs-bootswatch</code>), starting with MkDocs, using
+hyphens to separate words and including the name of your theme.</p>
 <p>Most of the rest of the file can be left unedited. The last section we need to
 change is the entry_points. This is how MkDocs finds the theme(s) you are
 including in the package. The name on the left is the one that users will use
@@ -822,7 +822,8 @@ templates to this list, the user cannot remove templates included in the
 theme's config.</p>
 <h4 id="extends">extends<a class="headerlink" href="#extends" title="Permanent link"></a></h4>
 <p>Defines a parent theme that this theme inherits from. The value should be
-the string name of the parent theme. Normal Jinja inheritance rules apply.</p>
+the string name of the parent theme. Normal <a href="https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance">Jinja inheritance rules</a>
+apply.</p>
 </div>
 <p>Plugins may also define some options which allow the theme to inform a plugin
 about which set of plugin options it expects. See the documentation for any
diff --git a/index.html b/index.html
index 67acf221..9086d3d3 100644
--- a/index.html
+++ b/index.html
@@ -201,7 +201,8 @@ configuration file. Start by reading the <a href="getting-started/">introductory
             href="user-guide/choosing-your-theme/#mkdocs">mkdocs</a> and <a
             href="user-guide/choosing-your-theme/#readthedocs">readthedocs</a>,
             select one of the third-party themes listed on the <a
-            href="">MkDocs Themes</a> wiki page, or <a href="">build your
+            href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">MkDocs
+            Themes</a> wiki page, or <a href="dev-guide/themes/">build your
             own</a>.
         </p>
       </div>
@@ -335,6 +336,6 @@ configuration file. Start by reading the <a href="getting-started/">introductory
 </html>
 
 <!--
-MkDocs version : 1.2.2
-Build Date UTC : 2021-07-18 19:23:32.181346+00:00
+MkDocs version : 1.2.3
+Build Date UTC : 2021-10-12 21:56:23.699016+00:00
 -->
diff --git a/js/a.js b/js/a.js
deleted file mode 100644
index 8d1c8b69..00000000
--- a/js/a.js
+++ /dev/null
@@ -1 +0,0 @@
- 
diff --git a/js/base.js b/js/base.js
index 8ba6faa1..b0f4726b 100644
--- a/js/base.js
+++ b/js/base.js
@@ -30,7 +30,7 @@ $(document).ready(function() {
         $search_modal.modal();
     }
 
-    // make sure search input gets autofocus everytime modal opens.
+    // make sure search input gets autofocus every time modal opens.
     $search_modal.on('shown.bs.modal', function() {
         $search_modal.find('#mkdocs-search-query').focus();
     });
diff --git a/search/search_index.json b/search/search_index.json
index 1f669a83..c0d66083 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"MkDocs \uf0c1 Project documentation with Markdown. MkDocs is a fast , simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial , then check the User Guide for more information. Getting Started User Guide Features Great themes available There's a stack of good looking themes available for MkDocs. Choose between the built in themes: mkdocs and readthedocs , select one of the third-party themes listed on the MkDocs Themes wiki page, or build your own . Easy to customize Get your project documentation looking just the way you want it by customizing your theme and/or installing some plugins . Modify Markdown's behavior with Markdown extensions . Many configuration options are available. Preview your site as you work The built-in dev-server allows you to preview your documentation as you're writing it. It will even auto-reload and refresh your browser whenever you save your changes. Host anywhere MkDocs builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose.","title":"Home"},{"location":"#mkdocs","text":"Project documentation with Markdown. MkDocs is a fast , simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial , then check the User Guide for more information. Getting Started User Guide","title":"MkDocs"},{"location":"getting-started/","text":"Getting Started with MkDocs \uf0c1 An introductory tutorial! Installation \uf0c1 To install MkDocs, run the following command from the command line: pip install mkdocs For more details, see the Installation Guide . Creating a new project \uf0c1 Getting started is super easy. To create a new project, run the following command from the command line: mkdocs new my-project cd my-project Take a moment to review the initial project that has been created for you. There's a single configuration file named mkdocs.yml , and a folder named docs that will contain your documentation source files ( docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command: $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes. Open the docs/index.md document in your text editor of choice, change the initial heading to MkLorum , and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum site_url: https://example.com/ Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name and site_url configuration options are the only two required options in your configuration file. When you create a new project, the site_url option is assigned the placeholder value: https://example.com . If the final location is known, you can change the setting now to point to it. Or you may choose to leave it alone for now. Just be sure to edit it before you deploy your site to a production server. Adding pages \uf0c1 Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a nav setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md Save your changes and you'll now see a navigation bar with Home and About items on the left as well as Search , Previous , and Next items on the right. Try the menu items and navigate back and forth between pages. Then click on Search . A search dialog will appear, allowing you to search for any text on any page. Notice that the search results include every occurrence of the search term on the site and links directly to the section of the page in which the search term appears. You get all of that with no effort or configuration on your part! Theming our documentation \uf0c1 Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md theme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used. Changing the Favicon Icon \uf0c1 By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create an img subdirectory in the docs directory and copy your custom favicon.ico file to that directory. MkDocs will automatically detect and use that file as your favicon icon. Building the site \uf0c1 That's looking good. You're ready to deploy the first pass of your MkLorum documentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the directory: $ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml Notice that your source documentation has been output as two HTML files named index.html and about/index.html . You also have various other media that's been copied into the site directory as part of the documentation theme. You even have a sitemap.xml file and mkdocs/search_index.json . If you're using source code control such as git you probably don't want to check your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo \"site/\" >> .gitignore If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories. Other Commands and Options \uf0c1 There are various other commands and options available. For a complete list of commands, use the --help flag: mkdocs --help To view a list of options available on a given command, use the --help flag with that command. For example, to get a list of all options available for the build command run the following: mkdocs build --help Deploying \uf0c1 The documentation site that you just built only uses static files so you'll be able to host it from pretty much anywhere. Simply upload the contents of the entire site directory to wherever you're hosting your website from and you're done. For specific instructions on a number of common hosts, see the Deploying your Docs page. Getting help \uf0c1 See the User Guide for more complete documentation of all of MkDocs' features. To get help with MkDocs, please use the GitHub discussions or GitHub issues .","title":"Getting Started"},{"location":"getting-started/#getting-started-with-mkdocs","text":"An introductory tutorial!","title":"Getting Started with MkDocs"},{"location":"getting-started/#installation","text":"To install MkDocs, run the following command from the command line: pip install mkdocs For more details, see the Installation Guide .","title":"Installation"},{"location":"getting-started/#creating-a-new-project","text":"Getting started is super easy. To create a new project, run the following command from the command line: mkdocs new my-project cd my-project Take a moment to review the initial project that has been created for you. There's a single configuration file named mkdocs.yml , and a folder named docs that will contain your documentation source files ( docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command: $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes. Open the docs/index.md document in your text editor of choice, change the initial heading to MkLorum , and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum site_url: https://example.com/ Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name and site_url configuration options are the only two required options in your configuration file. When you create a new project, the site_url option is assigned the placeholder value: https://example.com . If the final location is known, you can change the setting now to point to it. Or you may choose to leave it alone for now. Just be sure to edit it before you deploy your site to a production server.","title":"Creating a new project"},{"location":"getting-started/#adding-pages","text":"Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a nav setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md Save your changes and you'll now see a navigation bar with Home and About items on the left as well as Search , Previous , and Next items on the right. Try the menu items and navigate back and forth between pages. Then click on Search . A search dialog will appear, allowing you to search for any text on any page. Notice that the search results include every occurrence of the search term on the site and links directly to the section of the page in which the search term appears. You get all of that with no effort or configuration on your part!","title":"Adding pages"},{"location":"getting-started/#theming-our-documentation","text":"Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md theme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used.","title":"Theming our documentation"},{"location":"getting-started/#changing-the-favicon-icon","text":"By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create an img subdirectory in the docs directory and copy your custom favicon.ico file to that directory. MkDocs will automatically detect and use that file as your favicon icon.","title":"Changing the Favicon Icon"},{"location":"getting-started/#building-the-site","text":"That's looking good. You're ready to deploy the first pass of your MkLorum documentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the directory: $ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml Notice that your source documentation has been output as two HTML files named index.html and about/index.html . You also have various other media that's been copied into the site directory as part of the documentation theme. You even have a sitemap.xml file and mkdocs/search_index.json . If you're using source code control such as git you probably don't want to check your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo \"site/\" >> .gitignore If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories.","title":"Building the site"},{"location":"getting-started/#other-commands-and-options","text":"There are various other commands and options available. For a complete list of commands, use the --help flag: mkdocs --help To view a list of options available on a given command, use the --help flag with that command. For example, to get a list of all options available for the build command run the following: mkdocs build --help","title":"Other Commands and Options"},{"location":"getting-started/#deploying","text":"The documentation site that you just built only uses static files so you'll be able to host it from pretty much anywhere. Simply upload the contents of the entire site directory to wherever you're hosting your website from and you're done. For specific instructions on a number of common hosts, see the Deploying your Docs page.","title":"Deploying"},{"location":"getting-started/#getting-help","text":"See the User Guide for more complete documentation of all of MkDocs' features. To get help with MkDocs, please use the GitHub discussions or GitHub issues .","title":"Getting help"},{"location":"about/contributing/","text":"Contributing to MkDocs \uf0c1 An introduction to contributing to the MkDocs project. The MkDocs project welcomes, and depends, on contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: Code patches via pull requests Documentation improvements Bug reports and patch reviews For information about available communication channels please refer to the README file in our GitHub repository. Code of Conduct \uf0c1 Everyone interacting in the MkDocs project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct . Reporting an Issue \uf0c1 Please include as much detail as you can. Let us know your platform and MkDocs version. If the problem is visual (for example a theme or design issue) please add a screenshot and if you get an error please include the full error and traceback. Testing the Development Version \uf0c1 If you want to just install and try out the latest development version of MkDocs you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is strongly recommended that you do this within a virtualenv . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz Installing for Development \uf0c1 First you'll need to fork and clone the repository. Once you have a local copy, run the following command. It is strongly recommended that you do this within a virtualenv . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command to the git repository. Running the tests \uf0c1 To run the tests, it is recommended that you use tox . Install Tox using pip by running the command pip install tox . Then the test suite can be run for MkDocs by running the command tox in the root of your MkDocs repository. It will attempt to run the tests against all of the Python versions we support. So don't be concerned if you are missing some and they fail. The rest will be verified by Travis when you submit a pull request. Translating themes \uf0c1 To localize a theme to your favorite language, follow the guide on Translating Themes . We welcome translation Pull Requests! Submitting Pull Requests \uf0c1 Once you are happy with your changes or you are ready for some feedback, push it to your fork and send a pull request. For a change to be accepted it will most likely need to have tests and documentation if it is a new feature. Submitting changes to the builtin themes \uf0c1 When installed with i18n support ( pip install mkdocs[i18n] ), MkDocs allows themes to support being translated into various languages (referred to as locales) if they respect Jinja's i18n extension by wrapping text placeholders with {% trans %} and {% endtrans %} tags. Each time a translatable text placeholder is added, removed or changed in a theme template, the theme's Portable Object Template ( pot ) file needs to be updated by running the extract_messages command. For example, to update the pot file of the mkdocs theme, run the following command: python setup.py extract_messages -t mkdocs The updated pot file should be included in a PR with the updated template. The updated pot file will allow translation contributors to propose the translations needed for their preferred language. See the guide on Translating Themes for details. Note Contributors are not expected to provide translations with their changes to a theme's templates. However, they are expected to include an updated pot file so that everything is ready for translators to do their job.","title":"Contributing"},{"location":"about/contributing/#contributing-to-mkdocs","text":"An introduction to contributing to the MkDocs project. The MkDocs project welcomes, and depends, on contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: Code patches via pull requests Documentation improvements Bug reports and patch reviews For information about available communication channels please refer to the README file in our GitHub repository.","title":"Contributing to MkDocs"},{"location":"about/contributing/#code-of-conduct","text":"Everyone interacting in the MkDocs project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct .","title":"Code of Conduct"},{"location":"about/contributing/#reporting-an-issue","text":"Please include as much detail as you can. Let us know your platform and MkDocs version. If the problem is visual (for example a theme or design issue) please add a screenshot and if you get an error please include the full error and traceback.","title":"Reporting an Issue"},{"location":"about/contributing/#testing-the-development-version","text":"If you want to just install and try out the latest development version of MkDocs you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is strongly recommended that you do this within a virtualenv . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz","title":"Testing the Development Version"},{"location":"about/contributing/#installing-for-development","text":"First you'll need to fork and clone the repository. Once you have a local copy, run the following command. It is strongly recommended that you do this within a virtualenv . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command to the git repository.","title":"Installing for Development"},{"location":"about/contributing/#running-the-tests","text":"To run the tests, it is recommended that you use tox . Install Tox using pip by running the command pip install tox . Then the test suite can be run for MkDocs by running the command tox in the root of your MkDocs repository. It will attempt to run the tests against all of the Python versions we support. So don't be concerned if you are missing some and they fail. The rest will be verified by Travis when you submit a pull request.","title":"Running the tests"},{"location":"about/contributing/#translating-themes","text":"To localize a theme to your favorite language, follow the guide on Translating Themes . We welcome translation Pull Requests!","title":"Translating themes"},{"location":"about/contributing/#submitting-pull-requests","text":"Once you are happy with your changes or you are ready for some feedback, push it to your fork and send a pull request. For a change to be accepted it will most likely need to have tests and documentation if it is a new feature.","title":"Submitting Pull Requests"},{"location":"about/contributing/#submitting-changes-to-the-builtin-themes","text":"When installed with i18n support ( pip install mkdocs[i18n] ), MkDocs allows themes to support being translated into various languages (referred to as locales) if they respect Jinja's i18n extension by wrapping text placeholders with {% trans %} and {% endtrans %} tags. Each time a translatable text placeholder is added, removed or changed in a theme template, the theme's Portable Object Template ( pot ) file needs to be updated by running the extract_messages command. For example, to update the pot file of the mkdocs theme, run the following command: python setup.py extract_messages -t mkdocs The updated pot file should be included in a PR with the updated template. The updated pot file will allow translation contributors to propose the translations needed for their preferred language. See the guide on Translating Themes for details. Note Contributors are not expected to provide translations with their changes to a theme's templates. However, they are expected to include an updated pot file so that everything is ready for translators to do their job.","title":"Submitting changes to the builtin themes"},{"location":"about/license/","text":"License \uf0c1 The legal stuff. Included projects \uf0c1 Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects. MkDocs License (BSD) \uf0c1 Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"License"},{"location":"about/license/#license","text":"The legal stuff.","title":"License"},{"location":"about/license/#included-projects","text":"Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects.","title":"Included projects"},{"location":"about/license/#mkdocs-license-bsd","text":"Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"MkDocs License (BSD)"},{"location":"about/release-notes/","text":"Release Notes \uf0c1 Upgrading \uf0c1 To upgrade MkDocs to the latest version, use pip: pip install -U mkdocs You can determine your currently installed version using mkdocs --version : $ mkdocs --version mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6) Maintenance team \uf0c1 The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan Version 1.2.2 (2021-07-18) \uf0c1 Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters ( #2464 ) Bugfix (regression in 1.2): Revert livereload file watching to use polling observer ( #2477 ) This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts. This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage. Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls ( #2490 ) Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server ( #2507 ) Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before. Bugfix: Fix gh_deploy with config-file in the current directory ( #2481 ) Bugfix: Fix reversed breadcrumbs in \"readthedocs\" theme ( #2179 ) Allow \"mkdocs.yaml\" as the file name when '--config' is not passed ( #2478 ) Stop treating \";\" as a special character in URLs: urlparse -> urlsplit ( #2502 ) Improve build performance for sites with many pages (partly already done in 1.2) ( #2407 ) Version 1.2.1 (2021-06-09) \uf0c1 Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes. Version 1.2 (2021-06-04) \uf0c1 Major Additions to Version 1.2 \uf0c1 Support added for Theme Localization ( #2299 ) \uf0c1 The mkdocs and readthedocs themes now support language localization using the theme.locale parameter, which defaults to en (English). The only other supported languages in this release are fr (French) and es (Spanish). For details on using the provided translations, see the user guide . Note that translation will not happen by default. Users must first install the necessary dependencies with the following command: pip install mkdocs[i18n] Translation contributions are welcome and detailed in the Translation Guide . Developers of third party themes may want to review the relevant section of the Theme Development Guide . Contributors who are updating the templates to the built-in themes should review the Contributing Guide . The lang setting of the search plugin now defaults to the language specified in theme.locale . Support added for Environment Variables in the configuration file ( #1954 ) \uf0c1 Environments variables may now be specified in the configuration file with the !ENV tag. The value of the variable will be parsed by the YAML parser and converted to the appropriate type. somekey: !ENV VAR_NAME otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value'] See Environment Variables in the Configuration documentation for details. Support added for Configuration Inheritance ( #2218 ) \uf0c1 A configuration file may now inherit from a parent configuration file. In the primary file set the INHERIT key to the relative path of the parent file. INHERIT: path/to/base.yml The two files will then be deep merged. See Configuration Inheritance for details. Update gh-deploy command ( #2170 ) \uf0c1 The vendored (and modified) copy of ghp_import has been replaced with a dependency on the upstream library. As of version 1.0.0, ghp-import includes a Python API which makes it possible to call directly. MkDocs can now benefit from recent bug fixes and new features, including the following: A .nojekyll file is automatically included when deploying to GitHub Pages. The --shell flag is now available, which reportedly works better on Windows. Git author and committer environment variables should be respected ( #1383 ). Rework auto-reload and HTTP server for mkdocs serve ( #2385 ) \uf0c1 mkdocs serve now uses a new underlying server + file watcher implementation, based on http.server from standard library and watchdog . It provides similar functionality to the previously used livereload library (which is now dropped from dependencies, along with tornado ). This makes reloads more responsive and consistent in terms of timing. Multiple rapid file changes no longer cause the site to repeatedly rebuild (issue #2061 ). Almost every aspect of the server is slightly different, but actual visible changes are minor. The logging outputs are only similar to the old ones. Degradations in behavior are not expected, and should be reported if found. Offset the local site root according to the sub-path of the site_url ( #2424 ) \uf0c1 When using mkdocs serve and having the site_url specified as e.g. http://example.org/sub/path/ , now the root of the locally served site becomes http://127.0.0.1:8000/sub/path/ and all document paths are offset accordingly. A build_error event was added ( #2103 ) \uf0c1 Plugin developers can now use the on_build_error hook to execute code when an exception is raised while building the site. See on_build_error in the Plugins documentation for details. Three new exceptions: BuildError PluginError and Abort ( #2103 ) \uf0c1 MkDocs now has tree new exceptions defined in mkdocs.exceptions : BuildError , PluginError , and Abort : PluginError can be raised from a plugin to stop the build and log an error message without traceback . BuildError should not be used by third-party plugins developers and is reserved for internal use only. Abort is used internally to abort the build and display an error without a traceback. See Handling errors in the Plugins documentation for details. Search Indexing Strategy configuration \uf0c1 Users can now specify which strategy they wish to use when indexing their site for search. A user can select between the following options: full : Adds page title, section headings, and full page text to the search index. sections : Adds page titles and section headings only to the search index. titles : Adds only the page titles to the search index. See Search Indexing in the configuration documentation for details. Backward Incompatible Changes in 1.2 \uf0c1 The site_url configuration option is now required . If it is not set, a warning will be issued. In a future release an error will be raised ( #2189 ). The use_directory_urls configuration option will be forced to false if site_url is set to an empty string. In that case, if use_directory_urls is not explicitly set to false , a warning will be issued ( #2189 ). Note This was reverted in release 1.2.2 The google_analytics configuration option is deprecated as Google appears to be fazing it out in favor of its new Google Analytics 4 property. See the documentation for your theme for alternatives which can be configured as part of your theme configuration. For example, the mkdocs and readthedocs themes have each added a new theme.analytics.gtag configuration option which uses the new Google Analytics 4 property. See Google's documentation on how to Upgrade to a Google Analytics 4 property . Then set theme.analytics.gtag to the \"G-\" ID and delete the google_analytics configuration option which contains a \"UA-\" ID. So long as the old \"UA-\" ID and new \"G-\" ID are properly linked in your Google account, and you are using the \"G-\" ID, the data will be made available in both the old and new formats by Google Analytics. See #2252 . A theme's files are now excluded from the list of watched files by default when using the --livereload server. This new default behavior is what most users need and provides better performance when editing site content. Theme developers can enable the old behavior with the --watch-theme option. ( #2092 ). The mkdocs theme now removes the sidebar when printing a page. This frees up horizontal space for better rendering of content like tables ( #2193 ). The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema() , which ensures that each instance of the configuration is unique ( #2289 ). The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e.: mkdocs.plugins.pluginname ). The on_serve event (which receives the server object and the builder function) is affected by the server rewrite. server is now a mkdocs.livereload.LiveReloadServer instead of livereload.server.Server . The typical action that plugins can do with these is to call server.watch(some_dir, builder) , which basically adds that directory to watched directories, causing the site to be rebuilt on file changes. That still works, but passing any other function to watch is deprecated and shows a warning. This 2nd parameter is already optional, and will accept only this exact builder function just for compatibility. The python method of the plugins.search.prebuild_index configuration option is pending deprecation as of version 1.2. It is expected that in version 1.3 it will raise a warning if used and in version 1.4 it will raise an error. Users are encouraged to use an alternate method to generate a prebuilt index for search. The lunr and lunr[languages] dependencies are no longer installed by default. The dependencies are only needed for the rare user who pre-builds the search index and uses the python option, which is now pending deprecation. If you use this feature, then you will need to manually install lunr and lunr[languages] . A warning is issued if the dependencies are needed but not installed. Other Changes and Additions to Version 1.2 \uf0c1 Bugfix: Properly process navigation child items in _get_by_type when filtering for sections ( #2203 ). Official support for Python 3.9 has been added and support for Python 3.5 has been dropped. Bugfix: Fixes an issue that would result in a partially cut-off navigation item in the ReadTheDocs theme ( #2297 ). Structure Files object now has a remove method to help plugin developers manipulate the Files tree. The corresponding src_paths has become a property to accommodate this possible dynamic behavior. See #2305 . Updated highlight.js to 10.5.0. See #2313 . Bugfix: Search plugin now works with Japanese language. See #2178 . Documentation has been refactored ( #1629 ). Restore styling of tables in the readthedocs theme ( #2028 ). Ensure site_url ends with a slash ( #1785 ). Correct documentation of pages template context variable ( #1736 ). The lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding 2.3.9 version ( #2306 ). Color is now used in log messages to identify errors, warnings and debug messages. Bugfix: Identify homepage when use_directory_urls is False ( #2362 ). Version 1.1.2 (2020-05-14) \uf0c1 Bugfix: Normalize IP addresses and change unsupported address error to a warning ( #2108 ). Version 1.1.1 (2020-05-12) \uf0c1 Bugfix: Allow compressed sitemap to be deterministic by supporting the SOURCE_DATE_EPOCH environment variable ( #2100 ). Bugfix: Use README.md as index.html even if use_directory_urls is false ( #2081 ). Bugfix: Ignore links which start with a backslash ( #1680 ). Bugfix: Pass builder to the on_serve event so that it can be passed to server.watch by plugins ( #1952 ). Bugfix: Use lunr[languages]==0.5.8 to avoid nltk incompatibilities ( #2062 ). Bugfix: Ensure wheel is Python 3 only ( #2021 ). Bugfix: Clean up dev_addr validation and disallow 0.0.0.0 ( #2022 ). Add support for min_search_length parameter for search plugin ( #2014 ). Bugfix: readthedocs theme code colors ( #2027 ). Version 1.1 (2020-02-22) \uf0c1 Major Additions to Version 1.1 \uf0c1 Support for Lunr.py as prebuild_index engine \uf0c1 Mkdocs now supports pre-building indices using Lunr.py , a pure Python implementation of Lunr.js, allowing the user to avoid installing a NodeJS environment if so desired. For more information please read the prebuild_index documentation . readthedocs theme updated with upstream ( #588 and #1374 ) \uf0c1 The readthedocs theme now more closely matches the upstream Sphinx theme (version 0.4.1). A number of new theme configuration settings were added which mirror the upstream configuration options. See the theme documentation for details. Update mkdocs theme to Bootswatch 4.1.3 ( #1563 ) \uf0c1 The mkdocs theme now supports all the features of Bootswatch 4.1 . Additionally, 2 filenames were changed in this update. If you are using a theme which inherits from the mkdocs theme, the theme developer may need to update these filenames as follows. css/bootstrap-custom.min.css => css/bootstrap.min.css js/bootstrap-3.0.3.min.js => js/bootstrap.min.js Improved configuration support on the command line ( #1401 ) \uf0c1 The build , serve , and gh-deploy subcommands now support flags to control whether directory URLs should be created: --use-directory-urls / --no-directory-urls . In addition, the gh-deploy subcommand now supports all the configuration options that build and serve do, adding --strict , --theme , --theme-dir , and --site-dir . Updated lunr-languages support ( #1729 ) \uf0c1 The lunr-languages plugin has been updated to 1.4.0, adding support for Arabic ( ar ) and Vietnamese ( vi ) languages. In addition, the Dutch and Japanese language codes have been changed to their standard values: nl and ja , respectively. The old language codes ( du and jp ) remain as aliases but may be removed in a future version of MkDocs. Other Changes and Additions to Version 1.1 \uf0c1 Bugfix: Ensure nested dot files in themes are ignored and document behavior ( #1981 ). Update minimum dependency to Markdown 3.2.1. Updated minimum dependency to Jinja 2.10.1 to address security concerns ( #1780 ). Update to lunr.js 2.3.8 ( #1989 ). Add support for Python 3.8. Drop support for Python 3.4. Drop support for Python 2.7. MkDocs is PY3 only now ( #1926 ). Bugfix: Select appropriate asyncio event loop on Windows for Python 3.8+ ( #1885 ). Bugfix: Ensure nested index pages do not get identified as the homepage ( #1919 ). Bugfix: Properly identify deployment version ( #1879 ). Bugfix: Properly build ValidationError message for custom_dir ( #1849 ). Bugfix: Exclude Markdown files and READMEs from theme ( #1766 ). Bugfix: Account for encoded URLs ( #1670 ). Bugfix: Ensure theme files do not override docs_dir files ( #1671 ). Bugfix: Do not normalize URL fragments ( #1655 ). Bugfix: Skip external URLs in sitemap.xml ( #1742 ). Bugfix: Ensure theme files do not override docs_dir files on Windows ( #1876 ) Add canonical tag to readthedocs theme ( #1669 ). Improved error message for when git is not available. Add support for nav_style theme option for the mkdocs theme ( #1930 ). Bugfix: Long/nested dropdowns now behave more consistently for the mkdocs theme ( #1234 ). Bugfix: Multi-row nav headers in the mkdocs theme no longer obscure the document content ( #716 ). Add support for navigation_depth theme option for the mkdocs theme ( #1970 ). level attribute in page.toc items is now 1-indexed to match the level in <hN> tags ( #1970 ). Version 1.0.4 (2018-09-07) \uf0c1 Bugfix: Ignore absolute links in Markdown ( #1621 ). Version 1.0.3 (2018-08-29) \uf0c1 Bugfix: Warn on relative paths in navigation ( #1604 ). Bugfix: Handle empty theme_config.yml files correctly ( #1602 ). Version 1.0.2 (2018-08-22) \uf0c1 Bugfix: Provide absolute base_url to error templates ( #1598 ). Version 1.0.1 (2018-08-13) \uf0c1 Bugfix: Prevent page reload when [Enter] is pressed in search box ( #1589 ). Bugfix: Avoid calling search until all assets are ready ( #1584 ). Bugfix: Exclude README.md if index.md is present ( #1580 ). Bugfix: Fix readthedocs theme navigation bug with homepage ( #1576 ). Version 1.0 (2018-08-03) \uf0c1 Major Additions to Version 1.0 \uf0c1 Internal Refactor of Pages, Files, and Navigation \uf0c1 Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below. Support for hidden pages. All Markdown pages are now included in the build regardless of whether they are included in the navigation configuration ( #699 ). The navigation can now include links to external sites ( #989 #1373 & #1406 ). Page data (including titles) is properly determined for all pages before any page is rendered ( #1347 ). Automatically populated navigation now sorts index pages to the top. In other words, The index page will be listed as the first child of a directory, while all other documents are sorted alphanumerically by file name after the index page ( #73 & #1042 ). A README.md file is now treated as an index file within a directory and will be rendered to index.html ( #608 ). The URLs for all files are computed once and stored in a files collection. This ensures all internal links are always computed correctly regardless of the configuration. This also allows all internal links to be validated, not just links to other Markdown pages. ( #842 & #872 ). A new url template filter smartly ensures all URLs are relative to the current page ( #1526 ). An on_files plugin event has been added, which could be used to include files not in the docs_dir , exclude files, redefine page URLs (i.e. implement extensionless URLs), or to manipulate files in various other ways. Backward Incompatible Changes \uf0c1 As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below. URLs have changed when use_directory_urls is False \uf0c1 Previously, all Markdown pages would be have their filenames altered to be index pages regardless of how the use_directory_urls setting was configured. However, the path munging is only needed when use_directory_urls is set to True (the default). The path mangling no longer happens when use_directory_urls is set to False , which will result in different URLs for all pages that were not already index files. As this behavior only effects a non-default configuration, and the most common user-case for setting the option to False is for local file system ( file:// ) browsing, its not likely to effect most users. However, if you have use_directory_urls set to False for a MkDocs site hosted on a web server, most of your URLs will now be broken. As you can see below, the new URLs are much more sensible. Markdown file Old URL New URL index.md index.html index.html foo.md foo/index.html foo.html foo/bar.md foo/bar/index.html foo/bar.html Note that there has been no change to URLs or file paths when use_directory_urls is set to True (the default), except that MkDocs more consistently includes an ending slash on all internally generated URLs. The pages configuration setting has been renamed to nav \uf0c1 The pages configuration setting is deprecated and will issue a warning if set in the configuration file. The setting has been renamed nav . To update your configuration, simply rename the setting to nav . In other words, if your configuration looked like this: pages: - Home: index.md - User Guide: user-guide.md Simply edit the configuration as follows: nav: - Home: index.md - User Guide: user-guide.md In the current release, any configuration which includes a pages setting, but no nav setting, the pages configuration will be copied to nav and a warning will be issued. However, in a future release, that may no longer happen. If both pages and nav are defined, the pages setting will be ignored. Template variables and base_url \uf0c1 In previous versions of MkDocs some URLs expected the base_url template variable to be prepended to the URL and others did not. That inconsistency has been removed in that no URLs are modified before being added to the template context. For example, a theme template might have previously included a link to the site_name as: <a href=\"{{ nav.homepage.url }}\">{{ config.site_name }}</a> And MkDocs would magically return a URL for the homepage which was relative to the current page. That \"magic\" has been removed and the url template filter should be used: <a href=\"{{ nav.homepage.url|url }}\">{{ config.site_name }}</a> This change applies to any navigation items and pages, as well as the page.next_page and page.previous_page attributes. For the time being, the extra_javascript and extra_css variables continue to work as previously (without the url template filter), but they have been deprecated and the corresponding configuration values ( config.extra_javascript and config.extra_css respectively) should be used with the filter instead. {% for path in config['extra_css'] %} <link href=\"{{ path|url }}\" rel=\"stylesheet\"> {% endfor %} Note that navigation can now include links to external sites. Obviously, the base_url should not be prepended to these items. However, the url template filter is smart enough to recognize the URL is absolute and does not alter it. Therefore, all navigation items can be passed to the filter and only those that need to will be altered. {% for nav_item in nav %} <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> {% endfor %} Path Based Settings are Relative to Configuration File ( #543 ) \uf0c1 Previously any relative paths in the various configuration options were resolved relative to the current working directory. They are now resolved relative to the configuration file. As the documentation has always encouraged running the various MkDocs commands from the directory that contains the configuration file (project root), this change will not affect most users. However, it will make it much easier to implement automated builds or otherwise run commands from a location other than the project root. Simply use the -f/--config-file option and point it at the configuration file: mkdocs build --config-file /path/to/my/config/file.yml As previously, if no file is specified, MkDocs looks for a file named mkdocs.yml in the current working directory. Added support for YAML Meta-Data ( #1542 ) \uf0c1 Previously, MkDocs only supported MultiMarkdown style meta-data, which does not recognize different data types and is rather limited. MkDocs now also supports YAML style meta-data in Markdown documents. MkDocs relies on the the presence or absence of the deliminators ( --- or ... ) to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. Previously MkDocs would recognize MultiMarkdown style meta-data between the deliminators. Now, if the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Therefore, MultiMarkdown's style meta-data must not include the deliminators. See the MultiMarkdown style meta-data documentation for details. Prior to version 0.17, MkDocs returned all meta-data values as a list of strings (even a single line would return a list of one string). In version 0.17, that behavior was changed to return each value as a single string (multiple lines were joined), which some users found limiting (see #1471 ). That behavior continues for MultiMarkdown style meta-data in the current version. However, YAML style meta-data supports the full range of \"safe\" YAML data types. Therefore, it is recommended that any complex meta-data make use of the YAML style (see the YAML style meta-data documentation for details). In fact, a future version of MkDocs may deprecate support for MultiMarkdown style meta-data. Refactor Search Plugin \uf0c1 The search plugin has been completely refactored to include support for the following features: Use a web worker in the browser with a fallback ( #1396 ). Optionally pre-build search index locally ( #859 & #1061 ). Upgrade to lunr.js 2.x ( #1319 ). Support search in languages other than English ( #826 ). Allow the user to define the word separators ( #867 ). Only run searches for queries of length > 2 ( #1127 ). Remove dependency on require.js ( #1218 ). Compress the search index ( #1128 ). Users can review the configuration options available and theme authors should review how search and themes interact. theme_dir Configuration Option fully Deprecated \uf0c1 As of version 0.17, the custom_dir option replaced the deprecated theme_dir option. If users had set the theme_dir option, MkDocs version 0.17 copied the value to the theme.custom_dir option and a warning was issued. As of version 1.0, the value is no longer copied and an error is raised. Other Changes and Additions to Version 1.0 \uf0c1 Keyboard shortcuts changed to not conflict with commonly used accessibility shortcuts ( #1502 .) User friendly YAML parse errors ( #1543 ). Officially support Python 3.7. A missing theme configuration file now raises an error. Empty extra_css and extra_javascript settings no longer raise a warning. Add highlight.js configuration settings to built-in themes ( #1284 ). Close search modal when result is selected ( #1527 ). Add a level attribute to AnchorLinks ( #1272 ). Add MkDocs version check to gh-deploy script ( #640 ). Improve Markdown extension error messages. ( #782 ). Drop official support for Python 3.3 and set tornado>=5.0 ( #1427 ). Add support for GitLab edit links ( #1435 ). Link to GitHub issues from release notes ( #644 ). Expand {sha} and {version} in gh-deploy commit message ( #1410 ). Compress sitemap.xml ( #1130 ). Defer loading JS scripts ( #1380 ). Add a title attribute to the search input ( #1379 ). Update RespondJS to latest version ( #1398 ). Always load Google Analytics over HTTPS ( #1397 ). Improve scrolling frame rate ( #1394 ). Provide more version info. ( #1393 ). Refactor writing-your-docs.md ( #1392 ). Workaround Safari bug when zooming to < 100% ( #1389 ). Remove addition of clicky class to body and animations. ( #1387 ). Prevent search plugin from re-injecting extra_javascript files ( #1388 ). Refactor copy_media_files util function for more flexibility ( #1370 ). Remove PyPI Deployment Docs ( #1360 ). Update links to Python-Markdown library ( #1360 ). Document how to generate manpages for MkDocs commands ( #686 ). Version 0.17.5 (2018-07-06) \uf0c1 Bugfix: Fix Python 3.7 and PEP 479 incompatibility ( #1518 ). Version 0.17.4 (2018-06-08) \uf0c1 Bugfix: Add multi-level nesting support to sitemap.xml ( #1482 ). Version 0.17.3 (2018-03-07) \uf0c1 Bugfix: Set dependency tornado>=4.1,<5.0 due to changes in 5.0 ( #1428 ). Version 0.17.2 (2017-11-15) \uf0c1 Bugfix: Correct extra_* config setting regressions ( #1335 & #1336 ). Version 0.17.1 (2017-10-30) \uf0c1 Bugfix: Support repo_url with missing ending slash. ( #1321 ). Bugfix: Add length support to mkdocs.toc.TableOfContext ( #1325 ). Bugfix: Add some theme specific settings to the search plugin for third party themes ( #1316 ). Bugfix: Override site_url with dev_addr on local server ( #1317 ). Version 0.17.0 (2017-10-19) \uf0c1 Major Additions to Version 0.17.0 \uf0c1 Plugin API. ( #206 ) \uf0c1 A new Plugin API has been added to MkDocs which allows users to define their own custom behaviors. See the included documentation for a full explanation of the API. The previously built-in search functionality has been removed and wrapped in a plugin (named \"search\") with no changes in behavior. When MkDocs builds, the search index is now written to search/search_index.json instead of mkdocs/search_index.json . If no plugins setting is defined in the config, then the search plugin will be included by default. See the configuration documentation for information on overriding the default. Theme Customization. ( #1164 ) \uf0c1 Support had been added to provide theme specific customizations. Theme authors can define default options as documented in Theme Configuration . A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. The theme configuration is defined in a configuration file named mkdocs_theme.yml which should be placed at the root of your template files. A warning will be raised if no configuration file is found and an error will be raised in a future release. Users can override those defaults under the theme configuration option of their mkdocs.yml configuration file, which now accepts nested options. One such nested option is the custom_dir option, which replaces the now deprecated theme_dir option. If users had previously set the theme_dir option, a warning will be issued, with an error expected in a future release. If a configuration previously defined a theme_dir like this: theme: mkdocs theme_dir: custom Then the configuration should be adjusted as follows: theme: name: mkdocs custom_dir: custom See the theme configuration option documentation for details. Previously deprecated Template variables removed. ( #1168 ) \uf0c1 Page Template \uf0c1 The primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html continued to work if no main.html template existed, but it raised a deprecation warning. In version 1.0, a build will fail if no main.html template exists. Context Variables \uf0c1 Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names issued a warning in version 0.16, but have been removed in version 1.0. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico Auto-Populated extra_css and extra_javascript Fully Deprecated. ( #986 ) \uf0c1 In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. On version 0.16 this behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and JavaScript files will not be included in the HTML templates, however, a warning will be issued. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward. Other Changes and Additions to Version 0.17.0 \uf0c1 Add \"edit Link\" support to MkDocs theme ( #1129 ) Open files with utf-8-sig to account for BOM ( #1186 ) Symbolic links are now followed consistently ( #1134 ) Support for keyboard navigation shortcuts added to included themes ( #1095 ) Some refactoring and improvements to config_options ( #1296 ) Officially added support for Python 3.6 ( #1296 ) 404 Error page added to readthedocs theme ( #1296 )) Internal refactor of Markdown processing ( #713 ) Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch themes ( #1168 ) The legacy pages config is no longer supported ( #1168 ) The deprecated json command has been removed ( #481 ) Support for Python 2.6 has been dropped ( #165 ) File permissions are no longer copied during build ( #1292 ) Support query and fragment strings in edit_uri ( #1224 & #1273 ) Version 0.16.3 (2017-04-04) \uf0c1 Fix error raised by autoscrolling in the readthedocs theme ( #1177 ) Fix a few documentation typos ( #1181 & #1185 ) Fix a regression to livereload server introduced in 0.16.2 ( #1174 ) Version 0.16.2 (2017-03-13) \uf0c1 System root ( / ) is not a valid path for site_dir or docs_dir ( #1161 ) Refactor readthedocs theme navigation ( #1155 & #1156 ) Add support to dev server to serve custom error pages ( #1040 ) Ensure nav.homepage.url is not blank on error pages ( #1131 ) Increase livereload dependency to 2.5.1 ( #1106 ) Version 0.16.1 (2016-12-22) \uf0c1 Ensure scrollspy behavior does not affect nav bar ( #1094 ) Only \"load\" a theme when it is explicitly requested by the user ( #1105 ) Version 0.16 (2016-11-04) \uf0c1 Major Additions to Version 0.16.0 \uf0c1 Template variables refactored. ( #874 ) \uf0c1 Page Context \uf0c1 Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Global Context \uf0c1 Additionally, a number of global variables have been altered and/or deprecated and user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if nav|length>1 %} instead. Previously, the global variable include_next_prev was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if page.next_page or page.previous_page %} instead. Previously the global variable page_description was altered programmatically based on whether the current page was the homepage. Now it simply maps to config['site_description'] . Use {% if page.is_homepage %} in the template to conditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is being deprecated. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use nav.homepage.url instead. The global variable favicon maps to the configuration setting site_favicon . Both the template variable and the configuration setting are being deprecated and will issue a warning but continue to work for version 0.16, and may be removed in a future version. Use {{ base_url }}/img/favicon.ico in your template instead. Users can simply save a copy of their custom favicon icon to img/favicon.ico in either their docs_dir or theme_dir . A number of variables map directly to similarly named variables in the config . Those variables are being deprecated and will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use config.var_name instead, where var_name is the name of one of the configuration variables. Below is a summary of all of the changes made to the global context: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico Increased Template Customization. ( #607 ) \uf0c1 The built-in themes have been updated by having each of their many parts wrapped in template blocks which allow each individual block to be easily overridden using the theme_dir config setting. Without any new settings, you can use a different analytics service, replace the default search function, or alter the behavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html will continue to work if no main.html template exists, but it is deprecated and will raise a warning. In version 1.0, a build will fail if no main.html template exists. Any custom and third party templates should be updated accordingly. The easiest way for a third party theme to be updated would be to simply add a main.html file which only contains the following line: {% extends \"base.html\" %} That way, the theme contains the main.html entry point, and also supports overriding blocks in the same manner as the built-in themes. Third party themes are encouraged to wrap the various pieces of their templates in blocks in order to support such customization. Auto-Populated extra_css and extra_javascript Deprecated. ( #986 ) \uf0c1 In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. This behavior is deprecated and a warning will be issued. In the next release, the auto-populate feature will stop working and any unlisted CSS and JavaScript files will not be included in the HTML templates. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward. Support for dirty builds. ( #990 ) \uf0c1 For large sites the build time required to create the pages can become problematic, thus a \"dirty\" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. This mode may be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages. Stricter Directory Validation \uf0c1 Previously, a warning was issued if the site_dir was a child directory of the docs_dir . This now raises an error. Additionally, an error is now raised if the docs_dir is set to the directory which contains your config file rather than a child directory. You will need to rearrange you directory structure to better conform with the documented layout . Other Changes and Additions to Version 0.16.0 \uf0c1 Bugfix: Support gh-deploy command on Windows with Python 3 ( #722 ) Bugfix: Include .woff2 font files in Python package build ( #894 ) Various updates and improvements to Documentation Home Page/Tutorial ( #870 ) Bugfix: Support livereload for config file changes ( #735 ) Bugfix: Non-media template files are no longer copied with media files ( #807 ) Add a flag (-e/--theme-dir) to specify theme directory with the commands mkdocs build and mkdocs serve ( #832 ) Fixed issues with Unicode file names under Windows and Python 2. ( #833 ) Improved the styling of in-line code in the MkDocs theme. ( #718 ) Bugfix: convert variables to JSON when being passed to JavaScript ( #850 ) Updated the ReadTheDocs theme to match the upstream font sizes and colors more closely. ( #857 ) Fixes an issue with permalink markers showing when the mouse was far above them ( #843 ) Bugfix: Handle periods in directory name when automatically creating the pages config. ( #728 ) Update searching to Lunr 0.7, which comes with some performance enhancements for larger documents ( #859 ) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\" builds ( #938 ) Follow links when copying media files ( #869 ). Change \"Edit on...\" links to point directly to the file in the source repository, rather than to the root of the repository ( #975 ), configurable via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI ( #738 ). Add a --force flag to the gh-deploy command to force the push to the repository ( #973 ). Improve alignment for current selected menu item in readthedocs theme ( #888 ). http://user.github.io/repo => https://user.github.io/repo/ ( #1029 ). Improve installation instructions ( #1028 ). Account for wide tables and consistently wrap inline code spans ( #834 ). Bugfix: Use absolute URLs in nav & media links from error templates ( #77 ). Version 0.15.3 (2016-02-18) \uf0c1 Improve the error message the given theme can't be found. Fix an issue with relative symlinks ( #639 ) Version 0.15.2 (2016-02-08) \uf0c1 Fix an incorrect warning that states external themes will be removed from MkDocs . Version 0.15.1 (2016-01-30) \uf0c1 Lower the minimum supported Click version to 3.3 for package maintainers. ( #763 ) Version 0.15.0 (2016-01-21) \uf0c1 Major Additions to Version 0.15.0 \uf0c1 Add support for installable themes \uf0c1 MkDocs now supports themes that are distributed via Python packages. With this addition, the Bootstrap and Bootswatch themes have been moved to external git repositories and python packages. See their individual documentation for more details about these specific themes. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that they will be installable with pip: pip install mkdocs-bootstrap and pip install mkdocs-bootswatch See the documentation for Customizing Your Theme for more information about using and customizing themes and Custom themes for creating and distributing new themes Other Changes and Additions to Version 0.15.0 \uf0c1 Fix issues when using absolute links to Markdown files. ( #628 ) Deprecate support of Python 2.6, pending removal in 1.0.0. ( #165 ) Add official support for Python version 3.5. Add support for site_description and site_author to the ReadTheDocs theme. ( #631 ) Update FontAwesome to 4.5.0. ( #789 ) Increase IE support with X-UA-Compatible. ( #785 ) Added support for Python's -m flag. ( #706 ) Bugfix: Ensure consistent ordering of auto-populated pages. ( #638 ) Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long for the page. ( #204 ) Bugfix: Add all ancestors to the page attribute ancestors rather than just the initial one. ( #693 ) Bugfix: Include HTML in the build output again. ( #691 ) Bugfix: Provide filename to Read the Docs. ( #721 and RTD #1480 ) Bugfix: Silence Click's unicode_literals warning. ( #708 ) Version 0.14.0 (2015-06-09) \uf0c1 Improve Unicode handling by ensuring that all config strings are loaded as Unicode. ( #592 ) Remove dependency on the six library. ( #583 ) Remove dependency on the ghp-import library. ( #547 ) Add --quiet and --verbose options to all sub-commands. ( #579 ) Add short options ( -a ) to most command line options. ( #579 ) Add copyright footer for readthedocs theme. ( #568 ) If the requested port in mkdocs serve is already in use, don't show the user a full stack trace. ( #596 ) Bugfix: Fix a JavaScript encoding problem when searching with spaces. ( #586 ) Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root. ( #578 ) Bugfix: Handle (pass-through instead of dropping) HTML entities while parsing TOC. ( #612 ) Bugfix: Default extra_templates to an empty list, don't automatically discover them. ( #616 ) Version 0.13.3 (2015-06-02) \uf0c1 Bugfix: Reduce validation error to a warning if the site_dir is within the docs_dir as this shouldn't cause any problems with building but will inconvenience users building multiple times. ( #580 ) Version 0.13.2 (2015-05-30) \uf0c1 Bugfix: Ensure all errors and warnings are logged before exiting. ( #536 ) Bugfix: Fix compatibility issues with ReadTheDocs. ( #554 ) Version 0.13.1 (2015-05-27) \uf0c1 Bugfix: Fix a problem with minimal configurations which only contain a list of paths in the pages config. ( #562 ) Version 0.13.0 (2015-05-26) \uf0c1 Deprecations to Version 0.13.0 \uf0c1 Deprecate the JSON command \uf0c1 In this release the mkdocs json command has been marked as deprecated and when used a deprecation warning will be shown. It will be removed in a future release of MkDocs, version 1.0 at the latest. The mkdocs json command provided a convenient way for users to output the documentation contents as JSON files but with the additions of search to MkDocs this functionality is duplicated. A new index with all the contents from a MkDocs build is created in the site_dir , so with the default value for the site_dir It can be found in site/mkdocs/search_index.json . This new file is created on every MkDocs build (with mkdocs build ) and no configuration is needed to enable it. Change the pages configuration \uf0c1 Provide a new way to define pages, and specifically nested pages , in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0. Warn users about the removal of builtin themes \uf0c1 All themes other than mkdocs and readthedocs will be moved into external packages in a future release of MkDocs. This will enable them to be more easily supported and updates outside MkDocs releases. Major Additions to Version 0.13.0 \uf0c1 Search \uf0c1 Support for search has now been added to MkDocs. This is based on the JavaScript library lunr.js . It has been added to both the mkdocs and readthedocs themes. See the custom theme documentation on supporting search for adding it to your own themes. New Command Line Interface \uf0c1 The command line interface for MkDocs has been re-written with the Python library Click . This means that MkDocs now has an easier to use interface with better help output. This change is partially backwards incompatible as while undocumented it was possible to pass any configuration option to the different commands. Now only a small subset of the configuration options can be passed to the commands. To see in full commands and available arguments use mkdocs --help and mkdocs build --help to have them displayed. Support Extra HTML and XML files \uf0c1 Like the extra_javascript and extra_css configuration options, a new option named extra_templates has been added. This will automatically be populated with any .html or .xml files in the project docs directory. Users can place static HTML and XML files and they will be copied over, or they can also use Jinja2 syntax and take advantage of the global variables . By default MkDocs will use this approach to create a sitemap for the documentation. Other Changes and Additions to Version 0.13.0 \uf0c1 Add support for Markdown extension configuration options . ( #435 ) MkDocs now ships Python wheels . ( #486 ) Only include the build date and MkDocs version on the homepage. ( #490 ) Generate sitemaps for documentation builds. ( #436 ) Add a clearer way to define nested pages in the configuration. ( #482 ) Add an extra config option for passing arbitrary variables to the template. ( #510 ) Add --no-livereload to mkdocs serve for a simpler development server. ( #511 ) Add copyright display support to all themes ( #549 ) Add support for custom commit messages in a mkdocs gh-deploy ( #516 ) Bugfix: Fix linking to media within the same directory as a markdown file called index.md ( #535 ) Bugfix: Fix errors with Unicode filenames ( #542 ). Version 0.12.2 (2015-04-22) \uf0c1 Bugfix: Fix a regression where there would be an error if some child titles were missing but others were provided in the pages config. ( #464 ) Version 0.12.1 (2015-04-14) \uf0c1 Bugfix: Fixed a CSS bug in the table of contents on some browsers where the bottom item was not clickable. Version 0.12.0 (2015-04-14) \uf0c1 Display the current MkDocs version in the CLI output. ( #258 ) Check for CNAME file when using gh-deploy. ( #285 ) Add the homepage back to the navigation on all themes. ( #271 ) Add a strict more for local link checking. ( #279 ) Add Google analytics support to all themes. ( #333 ) Add build date and MkDocs version to the ReadTheDocs and MkDocs theme outputs. ( #382 ) Standardize highlighting across all themes and add missing languages. ( #387 ) Add a verbose flag. (-v) to show more details about what the build. ( #147 ) Add the option to specify a remote branch when deploying to GitHub. This enables deploying to GitHub pages on personal and repo sites. ( #354 ) Add favicon support to the ReadTheDocs theme HTML. ( #422 ) Automatically refresh the browser when files are edited. ( #163 ) Bugfix: Never re-write URLs in code blocks. ( #240 ) Bugfix: Don't copy dotfiles when copying media from the docs_dir . ( #254 ) Bugfix: Fix the rendering of tables in the ReadTheDocs theme. ( #106 ) Bugfix: Add padding to the bottom of all bootstrap themes. ( #255 ) Bugfix: Fix issues with nested Markdown pages and the automatic pages configuration. ( #276 ) Bugfix: Fix a URL parsing error with GitHub enterprise. ( #284 ) Bugfix: Don't error if the mkdocs.yml is completely empty. ( #288 ) Bugfix: Fix a number of problems with relative URLs and Markdown files. ( #292 ) Bugfix: Don't stop the build if a page can't be found, continue with other pages. ( #150 ) Bugfix: Remove the site_name from the page title, this needs to be added manually. ( #299 ) Bugfix: Fix an issue with table of contents cutting off Markdown. ( #294 ) Bugfix: Fix hostname for BitBucket. ( #339 ) Bugfix: Ensure all links end with a slash. ( #344 ) Bugfix: Fix repo links in the readthedocs theme. ( #365 ) Bugfix: Include jQuery locally to avoid problems using MkDocs offline. ( #143 ) Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. ( #384 ) Bugfix: Remove inline CSS in the ReadTheDocs theme. ( #393 ) Bugfix: Fix problems with the child titles due to the order the pages config was processed. ( #395 ) Bugfix: Don't error during live reload when the theme doesn't exist. ( #373 ) Bugfix: Fix problems with the Meta extension when it may not exist. ( #398 ) Bugfix: Wrap long inline code otherwise they will run off the screen. ( #313 ) Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to fix problems with titles containing code. ( #367 ) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden under the navigation. ( #7 ) Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. ( #295 ) Bugfix: Fix an error when passing in a specific config file with mkdocs serve . ( #341 ) Bugfix: Don't overwrite index.md files with the mkdocs new command. ( #412 ) Bugfix: Remove bold and italic from code in the ReadTheDocs theme. ( #411 ) Bugfix: Display images inline in the MkDocs theme. ( #415 ) Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. ( #319 ) Bugfix: Don't delete hidden files when using mkdocs build --clean . ( #346 ) Bugfix: Don't block newer versions of Python-markdown on Python >= 2.7. ( #376 ) Bugfix: Fix encoding issues when opening files across platforms. ( #428 ) Version 0.11.1 (2014-11-20) \uf0c1 Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs theme. ( #233 ) Version 0.11.0 (2014-11-18) \uf0c1 Render 404.html files if they exist for the current theme. ( #194 ) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs and ReadTheDocs themes. ( #225 ) Bugfix: Fix an issue with the google_analytics code. ( #219 ) Bugfix: Remove __pycache__ from the package tar. ( #196 ) Bugfix: Fix markdown links that go to an anchor on the current page. ( #197 ) Bugfix: Don't add prettyprint well CSS classes to all HTML, only add it in the MkDocs theme. ( #183 ) Bugfix: Display section titles in the ReadTheDocs theme. ( #175 ) Bugfix: Use the polling observer in watchdog so rebuilding works on filesystems without inotify. ( #184 ) Bugfix: Improve error output for common configuration related errors. ( #176 ) Version 0.10.0 (2014-10-29) \uf0c1 Added support for Python 3.3 and 3.4. ( #103 ) Configurable Python-Markdown extensions with the config setting markdown_extensions . ( #74 ) Added mkdocs json command to output your rendered documentation as json files. ( #128 ) Added --clean switch to build , json and gh-deploy commands to remove stale files from the output directory. ( #157 ) Support multiple theme directories to allow replacement of individual templates rather than copying the full theme. ( #129 ) Bugfix: Fix <ul> rendering in readthedocs theme. ( #171 ) Bugfix: Improve the readthedocs theme on smaller displays. ( #168 ) Bugfix: Relaxed required python package versions to avoid clashes. ( #104 ) Bugfix: Fix issue rendering the table of contents with some configs. ( #146 ) Bugfix: Fix path for embedded images in sub pages. ( #138 ) Bugfix: Fix use_directory_urls config behavior. ( #63 ) Bugfix: Support extra_javascript and extra_css in all themes. ( #90 ) Bugfix: Fix path-handling under Windows. ( #121 ) Bugfix: Fix the menu generation in the readthedocs theme. ( #110 ) Bugfix: Fix the mkdocs command creation under Windows. ( #122 ) Bugfix: Correctly handle external extra_javascript and extra_css . ( #92 ) Bugfix: Fixed favicon support. ( #87 )","title":"Release Notes"},{"location":"about/release-notes/#release-notes","text":"","title":"Release Notes"},{"location":"about/release-notes/#upgrading","text":"To upgrade MkDocs to the latest version, use pip: pip install -U mkdocs You can determine your currently installed version using mkdocs --version : $ mkdocs --version mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6)","title":"Upgrading"},{"location":"about/release-notes/#maintenance-team","text":"The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan","title":"Maintenance team"},{"location":"about/release-notes/#version-122-2021-07-18","text":"Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters ( #2464 ) Bugfix (regression in 1.2): Revert livereload file watching to use polling observer ( #2477 ) This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts. This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage. Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls ( #2490 ) Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server ( #2507 ) Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before. Bugfix: Fix gh_deploy with config-file in the current directory ( #2481 ) Bugfix: Fix reversed breadcrumbs in \"readthedocs\" theme ( #2179 ) Allow \"mkdocs.yaml\" as the file name when '--config' is not passed ( #2478 ) Stop treating \";\" as a special character in URLs: urlparse -> urlsplit ( #2502 ) Improve build performance for sites with many pages (partly already done in 1.2) ( #2407 )","title":"Version 1.2.2 (2021-07-18)"},{"location":"about/release-notes/#version-121-2021-06-09","text":"Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes.","title":"Version 1.2.1 (2021-06-09)"},{"location":"about/release-notes/#version-12-2021-06-04","text":"","title":"Version 1.2 (2021-06-04)"},{"location":"about/release-notes/#major-additions-to-version-12","text":"","title":"Major Additions to Version 1.2"},{"location":"about/release-notes/#support-added-for-theme-localization-2299","text":"The mkdocs and readthedocs themes now support language localization using the theme.locale parameter, which defaults to en (English). The only other supported languages in this release are fr (French) and es (Spanish). For details on using the provided translations, see the user guide . Note that translation will not happen by default. Users must first install the necessary dependencies with the following command: pip install mkdocs[i18n] Translation contributions are welcome and detailed in the Translation Guide . Developers of third party themes may want to review the relevant section of the Theme Development Guide . Contributors who are updating the templates to the built-in themes should review the Contributing Guide . The lang setting of the search plugin now defaults to the language specified in theme.locale .","title":"Support added for Theme Localization (#2299)"},{"location":"about/release-notes/#support-added-for-environment-variables-in-the-configuration-file-1954","text":"Environments variables may now be specified in the configuration file with the !ENV tag. The value of the variable will be parsed by the YAML parser and converted to the appropriate type. somekey: !ENV VAR_NAME otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value'] See Environment Variables in the Configuration documentation for details.","title":"Support added for Environment Variables in the configuration file (#1954)"},{"location":"about/release-notes/#support-added-for-configuration-inheritance-2218","text":"A configuration file may now inherit from a parent configuration file. In the primary file set the INHERIT key to the relative path of the parent file. INHERIT: path/to/base.yml The two files will then be deep merged. See Configuration Inheritance for details.","title":"Support added for Configuration Inheritance (#2218)"},{"location":"about/release-notes/#update-gh-deploy-command-2170","text":"The vendored (and modified) copy of ghp_import has been replaced with a dependency on the upstream library. As of version 1.0.0, ghp-import includes a Python API which makes it possible to call directly. MkDocs can now benefit from recent bug fixes and new features, including the following: A .nojekyll file is automatically included when deploying to GitHub Pages. The --shell flag is now available, which reportedly works better on Windows. Git author and committer environment variables should be respected ( #1383 ).","title":"Update gh-deploy command (#2170)"},{"location":"about/release-notes/#rework-auto-reload-and-http-server-for-mkdocs-serve-2385","text":"mkdocs serve now uses a new underlying server + file watcher implementation, based on http.server from standard library and watchdog . It provides similar functionality to the previously used livereload library (which is now dropped from dependencies, along with tornado ). This makes reloads more responsive and consistent in terms of timing. Multiple rapid file changes no longer cause the site to repeatedly rebuild (issue #2061 ). Almost every aspect of the server is slightly different, but actual visible changes are minor. The logging outputs are only similar to the old ones. Degradations in behavior are not expected, and should be reported if found.","title":"Rework auto-reload and HTTP server for mkdocs serve (#2385)"},{"location":"about/release-notes/#offset-the-local-site-root-according-to-the-sub-path-of-the-site_url-2424","text":"When using mkdocs serve and having the site_url specified as e.g. http://example.org/sub/path/ , now the root of the locally served site becomes http://127.0.0.1:8000/sub/path/ and all document paths are offset accordingly.","title":"Offset the local site root according to the sub-path of the site_url (#2424)"},{"location":"about/release-notes/#a-build_error-event-was-added-2103","text":"Plugin developers can now use the on_build_error hook to execute code when an exception is raised while building the site. See on_build_error in the Plugins documentation for details.","title":"A build_error event was added (#2103)"},{"location":"about/release-notes/#three-new-exceptions-builderror-pluginerror-and-abort-2103","text":"MkDocs now has tree new exceptions defined in mkdocs.exceptions : BuildError , PluginError , and Abort : PluginError can be raised from a plugin to stop the build and log an error message without traceback . BuildError should not be used by third-party plugins developers and is reserved for internal use only. Abort is used internally to abort the build and display an error without a traceback. See Handling errors in the Plugins documentation for details.","title":"Three new exceptions: BuildError PluginError and Abort (#2103)"},{"location":"about/release-notes/#search-indexing-strategy-configuration","text":"Users can now specify which strategy they wish to use when indexing their site for search. A user can select between the following options: full : Adds page title, section headings, and full page text to the search index. sections : Adds page titles and section headings only to the search index. titles : Adds only the page titles to the search index. See Search Indexing in the configuration documentation for details.","title":"Search Indexing Strategy configuration"},{"location":"about/release-notes/#backward-incompatible-changes-in-12","text":"The site_url configuration option is now required . If it is not set, a warning will be issued. In a future release an error will be raised ( #2189 ). The use_directory_urls configuration option will be forced to false if site_url is set to an empty string. In that case, if use_directory_urls is not explicitly set to false , a warning will be issued ( #2189 ). Note This was reverted in release 1.2.2 The google_analytics configuration option is deprecated as Google appears to be fazing it out in favor of its new Google Analytics 4 property. See the documentation for your theme for alternatives which can be configured as part of your theme configuration. For example, the mkdocs and readthedocs themes have each added a new theme.analytics.gtag configuration option which uses the new Google Analytics 4 property. See Google's documentation on how to Upgrade to a Google Analytics 4 property . Then set theme.analytics.gtag to the \"G-\" ID and delete the google_analytics configuration option which contains a \"UA-\" ID. So long as the old \"UA-\" ID and new \"G-\" ID are properly linked in your Google account, and you are using the \"G-\" ID, the data will be made available in both the old and new formats by Google Analytics. See #2252 . A theme's files are now excluded from the list of watched files by default when using the --livereload server. This new default behavior is what most users need and provides better performance when editing site content. Theme developers can enable the old behavior with the --watch-theme option. ( #2092 ). The mkdocs theme now removes the sidebar when printing a page. This frees up horizontal space for better rendering of content like tables ( #2193 ). The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema() , which ensures that each instance of the configuration is unique ( #2289 ). The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e.: mkdocs.plugins.pluginname ). The on_serve event (which receives the server object and the builder function) is affected by the server rewrite. server is now a mkdocs.livereload.LiveReloadServer instead of livereload.server.Server . The typical action that plugins can do with these is to call server.watch(some_dir, builder) , which basically adds that directory to watched directories, causing the site to be rebuilt on file changes. That still works, but passing any other function to watch is deprecated and shows a warning. This 2nd parameter is already optional, and will accept only this exact builder function just for compatibility. The python method of the plugins.search.prebuild_index configuration option is pending deprecation as of version 1.2. It is expected that in version 1.3 it will raise a warning if used and in version 1.4 it will raise an error. Users are encouraged to use an alternate method to generate a prebuilt index for search. The lunr and lunr[languages] dependencies are no longer installed by default. The dependencies are only needed for the rare user who pre-builds the search index and uses the python option, which is now pending deprecation. If you use this feature, then you will need to manually install lunr and lunr[languages] . A warning is issued if the dependencies are needed but not installed.","title":"Backward Incompatible Changes in 1.2"},{"location":"about/release-notes/#other-changes-and-additions-to-version-12","text":"Bugfix: Properly process navigation child items in _get_by_type when filtering for sections ( #2203 ). Official support for Python 3.9 has been added and support for Python 3.5 has been dropped. Bugfix: Fixes an issue that would result in a partially cut-off navigation item in the ReadTheDocs theme ( #2297 ). Structure Files object now has a remove method to help plugin developers manipulate the Files tree. The corresponding src_paths has become a property to accommodate this possible dynamic behavior. See #2305 . Updated highlight.js to 10.5.0. See #2313 . Bugfix: Search plugin now works with Japanese language. See #2178 . Documentation has been refactored ( #1629 ). Restore styling of tables in the readthedocs theme ( #2028 ). Ensure site_url ends with a slash ( #1785 ). Correct documentation of pages template context variable ( #1736 ). The lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding 2.3.9 version ( #2306 ). Color is now used in log messages to identify errors, warnings and debug messages. Bugfix: Identify homepage when use_directory_urls is False ( #2362 ).","title":"Other Changes and Additions to Version 1.2"},{"location":"about/release-notes/#version-112-2020-05-14","text":"Bugfix: Normalize IP addresses and change unsupported address error to a warning ( #2108 ).","title":"Version 1.1.2 (2020-05-14)"},{"location":"about/release-notes/#version-111-2020-05-12","text":"Bugfix: Allow compressed sitemap to be deterministic by supporting the SOURCE_DATE_EPOCH environment variable ( #2100 ). Bugfix: Use README.md as index.html even if use_directory_urls is false ( #2081 ). Bugfix: Ignore links which start with a backslash ( #1680 ). Bugfix: Pass builder to the on_serve event so that it can be passed to server.watch by plugins ( #1952 ). Bugfix: Use lunr[languages]==0.5.8 to avoid nltk incompatibilities ( #2062 ). Bugfix: Ensure wheel is Python 3 only ( #2021 ). Bugfix: Clean up dev_addr validation and disallow 0.0.0.0 ( #2022 ). Add support for min_search_length parameter for search plugin ( #2014 ). Bugfix: readthedocs theme code colors ( #2027 ).","title":"Version 1.1.1 (2020-05-12)"},{"location":"about/release-notes/#version-11-2020-02-22","text":"","title":"Version 1.1 (2020-02-22)"},{"location":"about/release-notes/#major-additions-to-version-11","text":"","title":"Major Additions to Version 1.1"},{"location":"about/release-notes/#support-for-lunrpy-as-prebuild_index-engine","text":"Mkdocs now supports pre-building indices using Lunr.py , a pure Python implementation of Lunr.js, allowing the user to avoid installing a NodeJS environment if so desired. For more information please read the prebuild_index documentation .","title":"Support for Lunr.py as prebuild_index engine"},{"location":"about/release-notes/#readthedocs-theme-updated-with-upstream-588-and-1374","text":"The readthedocs theme now more closely matches the upstream Sphinx theme (version 0.4.1). A number of new theme configuration settings were added which mirror the upstream configuration options. See the theme documentation for details.","title":"readthedocs theme updated with upstream (#588 and #1374)"},{"location":"about/release-notes/#update-mkdocs-theme-to-bootswatch-413-1563","text":"The mkdocs theme now supports all the features of Bootswatch 4.1 . Additionally, 2 filenames were changed in this update. If you are using a theme which inherits from the mkdocs theme, the theme developer may need to update these filenames as follows. css/bootstrap-custom.min.css => css/bootstrap.min.css js/bootstrap-3.0.3.min.js => js/bootstrap.min.js","title":"Update mkdocs theme to Bootswatch 4.1.3 (#1563)"},{"location":"about/release-notes/#improved-configuration-support-on-the-command-line-1401","text":"The build , serve , and gh-deploy subcommands now support flags to control whether directory URLs should be created: --use-directory-urls / --no-directory-urls . In addition, the gh-deploy subcommand now supports all the configuration options that build and serve do, adding --strict , --theme , --theme-dir , and --site-dir .","title":"Improved configuration support on the command line (#1401)"},{"location":"about/release-notes/#updated-lunr-languages-support-1729","text":"The lunr-languages plugin has been updated to 1.4.0, adding support for Arabic ( ar ) and Vietnamese ( vi ) languages. In addition, the Dutch and Japanese language codes have been changed to their standard values: nl and ja , respectively. The old language codes ( du and jp ) remain as aliases but may be removed in a future version of MkDocs.","title":"Updated lunr-languages support (#1729)"},{"location":"about/release-notes/#other-changes-and-additions-to-version-11","text":"Bugfix: Ensure nested dot files in themes are ignored and document behavior ( #1981 ). Update minimum dependency to Markdown 3.2.1. Updated minimum dependency to Jinja 2.10.1 to address security concerns ( #1780 ). Update to lunr.js 2.3.8 ( #1989 ). Add support for Python 3.8. Drop support for Python 3.4. Drop support for Python 2.7. MkDocs is PY3 only now ( #1926 ). Bugfix: Select appropriate asyncio event loop on Windows for Python 3.8+ ( #1885 ). Bugfix: Ensure nested index pages do not get identified as the homepage ( #1919 ). Bugfix: Properly identify deployment version ( #1879 ). Bugfix: Properly build ValidationError message for custom_dir ( #1849 ). Bugfix: Exclude Markdown files and READMEs from theme ( #1766 ). Bugfix: Account for encoded URLs ( #1670 ). Bugfix: Ensure theme files do not override docs_dir files ( #1671 ). Bugfix: Do not normalize URL fragments ( #1655 ). Bugfix: Skip external URLs in sitemap.xml ( #1742 ). Bugfix: Ensure theme files do not override docs_dir files on Windows ( #1876 ) Add canonical tag to readthedocs theme ( #1669 ). Improved error message for when git is not available. Add support for nav_style theme option for the mkdocs theme ( #1930 ). Bugfix: Long/nested dropdowns now behave more consistently for the mkdocs theme ( #1234 ). Bugfix: Multi-row nav headers in the mkdocs theme no longer obscure the document content ( #716 ). Add support for navigation_depth theme option for the mkdocs theme ( #1970 ). level attribute in page.toc items is now 1-indexed to match the level in <hN> tags ( #1970 ).","title":"Other Changes and Additions to Version 1.1"},{"location":"about/release-notes/#version-104-2018-09-07","text":"Bugfix: Ignore absolute links in Markdown ( #1621 ).","title":"Version 1.0.4 (2018-09-07)"},{"location":"about/release-notes/#version-103-2018-08-29","text":"Bugfix: Warn on relative paths in navigation ( #1604 ). Bugfix: Handle empty theme_config.yml files correctly ( #1602 ).","title":"Version 1.0.3 (2018-08-29)"},{"location":"about/release-notes/#version-102-2018-08-22","text":"Bugfix: Provide absolute base_url to error templates ( #1598 ).","title":"Version 1.0.2 (2018-08-22)"},{"location":"about/release-notes/#version-101-2018-08-13","text":"Bugfix: Prevent page reload when [Enter] is pressed in search box ( #1589 ). Bugfix: Avoid calling search until all assets are ready ( #1584 ). Bugfix: Exclude README.md if index.md is present ( #1580 ). Bugfix: Fix readthedocs theme navigation bug with homepage ( #1576 ).","title":"Version 1.0.1 (2018-08-13)"},{"location":"about/release-notes/#version-10-2018-08-03","text":"","title":"Version 1.0 (2018-08-03)"},{"location":"about/release-notes/#major-additions-to-version-10","text":"","title":"Major Additions to Version 1.0"},{"location":"about/release-notes/#internal-refactor-of-pages-files-and-navigation","text":"Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below. Support for hidden pages. All Markdown pages are now included in the build regardless of whether they are included in the navigation configuration ( #699 ). The navigation can now include links to external sites ( #989 #1373 & #1406 ). Page data (including titles) is properly determined for all pages before any page is rendered ( #1347 ). Automatically populated navigation now sorts index pages to the top. In other words, The index page will be listed as the first child of a directory, while all other documents are sorted alphanumerically by file name after the index page ( #73 & #1042 ). A README.md file is now treated as an index file within a directory and will be rendered to index.html ( #608 ). The URLs for all files are computed once and stored in a files collection. This ensures all internal links are always computed correctly regardless of the configuration. This also allows all internal links to be validated, not just links to other Markdown pages. ( #842 & #872 ). A new url template filter smartly ensures all URLs are relative to the current page ( #1526 ). An on_files plugin event has been added, which could be used to include files not in the docs_dir , exclude files, redefine page URLs (i.e. implement extensionless URLs), or to manipulate files in various other ways.","title":"Internal Refactor of Pages, Files, and Navigation"},{"location":"about/release-notes/#backward-incompatible-changes","text":"As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below.","title":"Backward Incompatible Changes"},{"location":"about/release-notes/#urls-have-changed-when-use_directory_urls-is-false","text":"Previously, all Markdown pages would be have their filenames altered to be index pages regardless of how the use_directory_urls setting was configured. However, the path munging is only needed when use_directory_urls is set to True (the default). The path mangling no longer happens when use_directory_urls is set to False , which will result in different URLs for all pages that were not already index files. As this behavior only effects a non-default configuration, and the most common user-case for setting the option to False is for local file system ( file:// ) browsing, its not likely to effect most users. However, if you have use_directory_urls set to False for a MkDocs site hosted on a web server, most of your URLs will now be broken. As you can see below, the new URLs are much more sensible. Markdown file Old URL New URL index.md index.html index.html foo.md foo/index.html foo.html foo/bar.md foo/bar/index.html foo/bar.html Note that there has been no change to URLs or file paths when use_directory_urls is set to True (the default), except that MkDocs more consistently includes an ending slash on all internally generated URLs.","title":"URLs have changed when use_directory_urls is False"},{"location":"about/release-notes/#the-pages-configuration-setting-has-been-renamed-to-nav","text":"The pages configuration setting is deprecated and will issue a warning if set in the configuration file. The setting has been renamed nav . To update your configuration, simply rename the setting to nav . In other words, if your configuration looked like this: pages: - Home: index.md - User Guide: user-guide.md Simply edit the configuration as follows: nav: - Home: index.md - User Guide: user-guide.md In the current release, any configuration which includes a pages setting, but no nav setting, the pages configuration will be copied to nav and a warning will be issued. However, in a future release, that may no longer happen. If both pages and nav are defined, the pages setting will be ignored.","title":"The pages configuration setting has been renamed to nav"},{"location":"about/release-notes/#template-variables-and-base_url","text":"In previous versions of MkDocs some URLs expected the base_url template variable to be prepended to the URL and others did not. That inconsistency has been removed in that no URLs are modified before being added to the template context. For example, a theme template might have previously included a link to the site_name as: <a href=\"{{ nav.homepage.url }}\">{{ config.site_name }}</a> And MkDocs would magically return a URL for the homepage which was relative to the current page. That \"magic\" has been removed and the url template filter should be used: <a href=\"{{ nav.homepage.url|url }}\">{{ config.site_name }}</a> This change applies to any navigation items and pages, as well as the page.next_page and page.previous_page attributes. For the time being, the extra_javascript and extra_css variables continue to work as previously (without the url template filter), but they have been deprecated and the corresponding configuration values ( config.extra_javascript and config.extra_css respectively) should be used with the filter instead. {% for path in config['extra_css'] %} <link href=\"{{ path|url }}\" rel=\"stylesheet\"> {% endfor %} Note that navigation can now include links to external sites. Obviously, the base_url should not be prepended to these items. However, the url template filter is smart enough to recognize the URL is absolute and does not alter it. Therefore, all navigation items can be passed to the filter and only those that need to will be altered. {% for nav_item in nav %} <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> {% endfor %}","title":"Template variables and base_url"},{"location":"about/release-notes/#path-based-settings-are-relative-to-configuration-file-543","text":"Previously any relative paths in the various configuration options were resolved relative to the current working directory. They are now resolved relative to the configuration file. As the documentation has always encouraged running the various MkDocs commands from the directory that contains the configuration file (project root), this change will not affect most users. However, it will make it much easier to implement automated builds or otherwise run commands from a location other than the project root. Simply use the -f/--config-file option and point it at the configuration file: mkdocs build --config-file /path/to/my/config/file.yml As previously, if no file is specified, MkDocs looks for a file named mkdocs.yml in the current working directory.","title":"Path Based Settings are Relative to Configuration File (#543)"},{"location":"about/release-notes/#added-support-for-yaml-meta-data-1542","text":"Previously, MkDocs only supported MultiMarkdown style meta-data, which does not recognize different data types and is rather limited. MkDocs now also supports YAML style meta-data in Markdown documents. MkDocs relies on the the presence or absence of the deliminators ( --- or ... ) to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. Previously MkDocs would recognize MultiMarkdown style meta-data between the deliminators. Now, if the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Therefore, MultiMarkdown's style meta-data must not include the deliminators. See the MultiMarkdown style meta-data documentation for details. Prior to version 0.17, MkDocs returned all meta-data values as a list of strings (even a single line would return a list of one string). In version 0.17, that behavior was changed to return each value as a single string (multiple lines were joined), which some users found limiting (see #1471 ). That behavior continues for MultiMarkdown style meta-data in the current version. However, YAML style meta-data supports the full range of \"safe\" YAML data types. Therefore, it is recommended that any complex meta-data make use of the YAML style (see the YAML style meta-data documentation for details). In fact, a future version of MkDocs may deprecate support for MultiMarkdown style meta-data.","title":"Added support for YAML Meta-Data (#1542)"},{"location":"about/release-notes/#refactor-search-plugin","text":"The search plugin has been completely refactored to include support for the following features: Use a web worker in the browser with a fallback ( #1396 ). Optionally pre-build search index locally ( #859 & #1061 ). Upgrade to lunr.js 2.x ( #1319 ). Support search in languages other than English ( #826 ). Allow the user to define the word separators ( #867 ). Only run searches for queries of length > 2 ( #1127 ). Remove dependency on require.js ( #1218 ). Compress the search index ( #1128 ). Users can review the configuration options available and theme authors should review how search and themes interact.","title":"Refactor Search Plugin"},{"location":"about/release-notes/#theme_dir-configuration-option-fully-deprecated","text":"As of version 0.17, the custom_dir option replaced the deprecated theme_dir option. If users had set the theme_dir option, MkDocs version 0.17 copied the value to the theme.custom_dir option and a warning was issued. As of version 1.0, the value is no longer copied and an error is raised.","title":"theme_dir Configuration Option fully Deprecated"},{"location":"about/release-notes/#other-changes-and-additions-to-version-10","text":"Keyboard shortcuts changed to not conflict with commonly used accessibility shortcuts ( #1502 .) User friendly YAML parse errors ( #1543 ). Officially support Python 3.7. A missing theme configuration file now raises an error. Empty extra_css and extra_javascript settings no longer raise a warning. Add highlight.js configuration settings to built-in themes ( #1284 ). Close search modal when result is selected ( #1527 ). Add a level attribute to AnchorLinks ( #1272 ). Add MkDocs version check to gh-deploy script ( #640 ). Improve Markdown extension error messages. ( #782 ). Drop official support for Python 3.3 and set tornado>=5.0 ( #1427 ). Add support for GitLab edit links ( #1435 ). Link to GitHub issues from release notes ( #644 ). Expand {sha} and {version} in gh-deploy commit message ( #1410 ). Compress sitemap.xml ( #1130 ). Defer loading JS scripts ( #1380 ). Add a title attribute to the search input ( #1379 ). Update RespondJS to latest version ( #1398 ). Always load Google Analytics over HTTPS ( #1397 ). Improve scrolling frame rate ( #1394 ). Provide more version info. ( #1393 ). Refactor writing-your-docs.md ( #1392 ). Workaround Safari bug when zooming to < 100% ( #1389 ). Remove addition of clicky class to body and animations. ( #1387 ). Prevent search plugin from re-injecting extra_javascript files ( #1388 ). Refactor copy_media_files util function for more flexibility ( #1370 ). Remove PyPI Deployment Docs ( #1360 ). Update links to Python-Markdown library ( #1360 ). Document how to generate manpages for MkDocs commands ( #686 ).","title":"Other Changes and Additions to Version 1.0"},{"location":"about/release-notes/#version-0175-2018-07-06","text":"Bugfix: Fix Python 3.7 and PEP 479 incompatibility ( #1518 ).","title":"Version 0.17.5 (2018-07-06)"},{"location":"about/release-notes/#version-0174-2018-06-08","text":"Bugfix: Add multi-level nesting support to sitemap.xml ( #1482 ).","title":"Version 0.17.4 (2018-06-08)"},{"location":"about/release-notes/#version-0173-2018-03-07","text":"Bugfix: Set dependency tornado>=4.1,<5.0 due to changes in 5.0 ( #1428 ).","title":"Version 0.17.3 (2018-03-07)"},{"location":"about/release-notes/#version-0172-2017-11-15","text":"Bugfix: Correct extra_* config setting regressions ( #1335 & #1336 ).","title":"Version 0.17.2 (2017-11-15)"},{"location":"about/release-notes/#version-0171-2017-10-30","text":"Bugfix: Support repo_url with missing ending slash. ( #1321 ). Bugfix: Add length support to mkdocs.toc.TableOfContext ( #1325 ). Bugfix: Add some theme specific settings to the search plugin for third party themes ( #1316 ). Bugfix: Override site_url with dev_addr on local server ( #1317 ).","title":"Version 0.17.1 (2017-10-30)"},{"location":"about/release-notes/#version-0170-2017-10-19","text":"","title":"Version 0.17.0 (2017-10-19)"},{"location":"about/release-notes/#major-additions-to-version-0170","text":"","title":"Major Additions to Version 0.17.0"},{"location":"about/release-notes/#plugin-api-206","text":"A new Plugin API has been added to MkDocs which allows users to define their own custom behaviors. See the included documentation for a full explanation of the API. The previously built-in search functionality has been removed and wrapped in a plugin (named \"search\") with no changes in behavior. When MkDocs builds, the search index is now written to search/search_index.json instead of mkdocs/search_index.json . If no plugins setting is defined in the config, then the search plugin will be included by default. See the configuration documentation for information on overriding the default.","title":"Plugin API. (#206)"},{"location":"about/release-notes/#theme-customization-1164","text":"Support had been added to provide theme specific customizations. Theme authors can define default options as documented in Theme Configuration . A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. The theme configuration is defined in a configuration file named mkdocs_theme.yml which should be placed at the root of your template files. A warning will be raised if no configuration file is found and an error will be raised in a future release. Users can override those defaults under the theme configuration option of their mkdocs.yml configuration file, which now accepts nested options. One such nested option is the custom_dir option, which replaces the now deprecated theme_dir option. If users had previously set the theme_dir option, a warning will be issued, with an error expected in a future release. If a configuration previously defined a theme_dir like this: theme: mkdocs theme_dir: custom Then the configuration should be adjusted as follows: theme: name: mkdocs custom_dir: custom See the theme configuration option documentation for details.","title":"Theme Customization. (#1164)"},{"location":"about/release-notes/#previously-deprecated-template-variables-removed-1168","text":"","title":"Previously deprecated Template variables removed. (#1168)"},{"location":"about/release-notes/#page-template","text":"The primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html continued to work if no main.html template existed, but it raised a deprecation warning. In version 1.0, a build will fail if no main.html template exists.","title":"Page Template"},{"location":"about/release-notes/#context-variables","text":"Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names issued a warning in version 0.16, but have been removed in version 1.0. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico","title":"Context Variables"},{"location":"about/release-notes/#auto-populated-extra_css-and-extra_javascript-fully-deprecated-986","text":"In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. On version 0.16 this behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and JavaScript files will not be included in the HTML templates, however, a warning will be issued. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.","title":"Auto-Populated extra_css and extra_javascript Fully Deprecated. (#986)"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0170","text":"Add \"edit Link\" support to MkDocs theme ( #1129 ) Open files with utf-8-sig to account for BOM ( #1186 ) Symbolic links are now followed consistently ( #1134 ) Support for keyboard navigation shortcuts added to included themes ( #1095 ) Some refactoring and improvements to config_options ( #1296 ) Officially added support for Python 3.6 ( #1296 ) 404 Error page added to readthedocs theme ( #1296 )) Internal refactor of Markdown processing ( #713 ) Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch themes ( #1168 ) The legacy pages config is no longer supported ( #1168 ) The deprecated json command has been removed ( #481 ) Support for Python 2.6 has been dropped ( #165 ) File permissions are no longer copied during build ( #1292 ) Support query and fragment strings in edit_uri ( #1224 & #1273 )","title":"Other Changes and Additions to Version 0.17.0"},{"location":"about/release-notes/#version-0163-2017-04-04","text":"Fix error raised by autoscrolling in the readthedocs theme ( #1177 ) Fix a few documentation typos ( #1181 & #1185 ) Fix a regression to livereload server introduced in 0.16.2 ( #1174 )","title":"Version 0.16.3 (2017-04-04)"},{"location":"about/release-notes/#version-0162-2017-03-13","text":"System root ( / ) is not a valid path for site_dir or docs_dir ( #1161 ) Refactor readthedocs theme navigation ( #1155 & #1156 ) Add support to dev server to serve custom error pages ( #1040 ) Ensure nav.homepage.url is not blank on error pages ( #1131 ) Increase livereload dependency to 2.5.1 ( #1106 )","title":"Version 0.16.2 (2017-03-13)"},{"location":"about/release-notes/#version-0161-2016-12-22","text":"Ensure scrollspy behavior does not affect nav bar ( #1094 ) Only \"load\" a theme when it is explicitly requested by the user ( #1105 )","title":"Version 0.16.1 (2016-12-22)"},{"location":"about/release-notes/#version-016-2016-11-04","text":"","title":"Version 0.16 (2016-11-04)"},{"location":"about/release-notes/#major-additions-to-version-0160","text":"","title":"Major Additions to Version 0.16.0"},{"location":"about/release-notes/#template-variables-refactored-874","text":"","title":"Template variables refactored. (#874)"},{"location":"about/release-notes/#page-context","text":"Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page","title":"Page Context"},{"location":"about/release-notes/#global-context","text":"Additionally, a number of global variables have been altered and/or deprecated and user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if nav|length>1 %} instead. Previously, the global variable include_next_prev was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if page.next_page or page.previous_page %} instead. Previously the global variable page_description was altered programmatically based on whether the current page was the homepage. Now it simply maps to config['site_description'] . Use {% if page.is_homepage %} in the template to conditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is being deprecated. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use nav.homepage.url instead. The global variable favicon maps to the configuration setting site_favicon . Both the template variable and the configuration setting are being deprecated and will issue a warning but continue to work for version 0.16, and may be removed in a future version. Use {{ base_url }}/img/favicon.ico in your template instead. Users can simply save a copy of their custom favicon icon to img/favicon.ico in either their docs_dir or theme_dir . A number of variables map directly to similarly named variables in the config . Those variables are being deprecated and will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use config.var_name instead, where var_name is the name of one of the configuration variables. Below is a summary of all of the changes made to the global context: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico","title":"Global Context"},{"location":"about/release-notes/#increased-template-customization-607","text":"The built-in themes have been updated by having each of their many parts wrapped in template blocks which allow each individual block to be easily overridden using the theme_dir config setting. Without any new settings, you can use a different analytics service, replace the default search function, or alter the behavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html will continue to work if no main.html template exists, but it is deprecated and will raise a warning. In version 1.0, a build will fail if no main.html template exists. Any custom and third party templates should be updated accordingly. The easiest way for a third party theme to be updated would be to simply add a main.html file which only contains the following line: {% extends \"base.html\" %} That way, the theme contains the main.html entry point, and also supports overriding blocks in the same manner as the built-in themes. Third party themes are encouraged to wrap the various pieces of their templates in blocks in order to support such customization.","title":"Increased Template Customization. (#607)"},{"location":"about/release-notes/#auto-populated-extra_css-and-extra_javascript-deprecated-986","text":"In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. This behavior is deprecated and a warning will be issued. In the next release, the auto-populate feature will stop working and any unlisted CSS and JavaScript files will not be included in the HTML templates. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.","title":"Auto-Populated extra_css and extra_javascript Deprecated. (#986)"},{"location":"about/release-notes/#support-for-dirty-builds-990","text":"For large sites the build time required to create the pages can become problematic, thus a \"dirty\" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. This mode may be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages.","title":"Support for dirty builds. (#990)"},{"location":"about/release-notes/#stricter-directory-validation","text":"Previously, a warning was issued if the site_dir was a child directory of the docs_dir . This now raises an error. Additionally, an error is now raised if the docs_dir is set to the directory which contains your config file rather than a child directory. You will need to rearrange you directory structure to better conform with the documented layout .","title":"Stricter Directory Validation"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0160","text":"Bugfix: Support gh-deploy command on Windows with Python 3 ( #722 ) Bugfix: Include .woff2 font files in Python package build ( #894 ) Various updates and improvements to Documentation Home Page/Tutorial ( #870 ) Bugfix: Support livereload for config file changes ( #735 ) Bugfix: Non-media template files are no longer copied with media files ( #807 ) Add a flag (-e/--theme-dir) to specify theme directory with the commands mkdocs build and mkdocs serve ( #832 ) Fixed issues with Unicode file names under Windows and Python 2. ( #833 ) Improved the styling of in-line code in the MkDocs theme. ( #718 ) Bugfix: convert variables to JSON when being passed to JavaScript ( #850 ) Updated the ReadTheDocs theme to match the upstream font sizes and colors more closely. ( #857 ) Fixes an issue with permalink markers showing when the mouse was far above them ( #843 ) Bugfix: Handle periods in directory name when automatically creating the pages config. ( #728 ) Update searching to Lunr 0.7, which comes with some performance enhancements for larger documents ( #859 ) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\" builds ( #938 ) Follow links when copying media files ( #869 ). Change \"Edit on...\" links to point directly to the file in the source repository, rather than to the root of the repository ( #975 ), configurable via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI ( #738 ). Add a --force flag to the gh-deploy command to force the push to the repository ( #973 ). Improve alignment for current selected menu item in readthedocs theme ( #888 ). http://user.github.io/repo => https://user.github.io/repo/ ( #1029 ). Improve installation instructions ( #1028 ). Account for wide tables and consistently wrap inline code spans ( #834 ). Bugfix: Use absolute URLs in nav & media links from error templates ( #77 ).","title":"Other Changes and Additions to Version 0.16.0"},{"location":"about/release-notes/#version-0153-2016-02-18","text":"Improve the error message the given theme can't be found. Fix an issue with relative symlinks ( #639 )","title":"Version 0.15.3 (2016-02-18)"},{"location":"about/release-notes/#version-0152-2016-02-08","text":"Fix an incorrect warning that states external themes will be removed from MkDocs .","title":"Version 0.15.2 (2016-02-08)"},{"location":"about/release-notes/#version-0151-2016-01-30","text":"Lower the minimum supported Click version to 3.3 for package maintainers. ( #763 )","title":"Version 0.15.1 (2016-01-30)"},{"location":"about/release-notes/#version-0150-2016-01-21","text":"","title":"Version 0.15.0 (2016-01-21)"},{"location":"about/release-notes/#major-additions-to-version-0150","text":"","title":"Major Additions to Version 0.15.0"},{"location":"about/release-notes/#add-support-for-installable-themes","text":"MkDocs now supports themes that are distributed via Python packages. With this addition, the Bootstrap and Bootswatch themes have been moved to external git repositories and python packages. See their individual documentation for more details about these specific themes. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that they will be installable with pip: pip install mkdocs-bootstrap and pip install mkdocs-bootswatch See the documentation for Customizing Your Theme for more information about using and customizing themes and Custom themes for creating and distributing new themes","title":"Add support for installable themes"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0150","text":"Fix issues when using absolute links to Markdown files. ( #628 ) Deprecate support of Python 2.6, pending removal in 1.0.0. ( #165 ) Add official support for Python version 3.5. Add support for site_description and site_author to the ReadTheDocs theme. ( #631 ) Update FontAwesome to 4.5.0. ( #789 ) Increase IE support with X-UA-Compatible. ( #785 ) Added support for Python's -m flag. ( #706 ) Bugfix: Ensure consistent ordering of auto-populated pages. ( #638 ) Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long for the page. ( #204 ) Bugfix: Add all ancestors to the page attribute ancestors rather than just the initial one. ( #693 ) Bugfix: Include HTML in the build output again. ( #691 ) Bugfix: Provide filename to Read the Docs. ( #721 and RTD #1480 ) Bugfix: Silence Click's unicode_literals warning. ( #708 )","title":"Other Changes and Additions to Version 0.15.0"},{"location":"about/release-notes/#version-0140-2015-06-09","text":"Improve Unicode handling by ensuring that all config strings are loaded as Unicode. ( #592 ) Remove dependency on the six library. ( #583 ) Remove dependency on the ghp-import library. ( #547 ) Add --quiet and --verbose options to all sub-commands. ( #579 ) Add short options ( -a ) to most command line options. ( #579 ) Add copyright footer for readthedocs theme. ( #568 ) If the requested port in mkdocs serve is already in use, don't show the user a full stack trace. ( #596 ) Bugfix: Fix a JavaScript encoding problem when searching with spaces. ( #586 ) Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root. ( #578 ) Bugfix: Handle (pass-through instead of dropping) HTML entities while parsing TOC. ( #612 ) Bugfix: Default extra_templates to an empty list, don't automatically discover them. ( #616 )","title":"Version 0.14.0 (2015-06-09)"},{"location":"about/release-notes/#version-0133-2015-06-02","text":"Bugfix: Reduce validation error to a warning if the site_dir is within the docs_dir as this shouldn't cause any problems with building but will inconvenience users building multiple times. ( #580 )","title":"Version 0.13.3 (2015-06-02)"},{"location":"about/release-notes/#version-0132-2015-05-30","text":"Bugfix: Ensure all errors and warnings are logged before exiting. ( #536 ) Bugfix: Fix compatibility issues with ReadTheDocs. ( #554 )","title":"Version 0.13.2 (2015-05-30)"},{"location":"about/release-notes/#version-0131-2015-05-27","text":"Bugfix: Fix a problem with minimal configurations which only contain a list of paths in the pages config. ( #562 )","title":"Version 0.13.1 (2015-05-27)"},{"location":"about/release-notes/#version-0130-2015-05-26","text":"","title":"Version 0.13.0 (2015-05-26)"},{"location":"about/release-notes/#deprecations-to-version-0130","text":"","title":"Deprecations to Version 0.13.0"},{"location":"about/release-notes/#deprecate-the-json-command","text":"In this release the mkdocs json command has been marked as deprecated and when used a deprecation warning will be shown. It will be removed in a future release of MkDocs, version 1.0 at the latest. The mkdocs json command provided a convenient way for users to output the documentation contents as JSON files but with the additions of search to MkDocs this functionality is duplicated. A new index with all the contents from a MkDocs build is created in the site_dir , so with the default value for the site_dir It can be found in site/mkdocs/search_index.json . This new file is created on every MkDocs build (with mkdocs build ) and no configuration is needed to enable it.","title":"Deprecate the JSON command"},{"location":"about/release-notes/#change-the-pages-configuration","text":"Provide a new way to define pages, and specifically nested pages , in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0.","title":"Change the pages configuration"},{"location":"about/release-notes/#warn-users-about-the-removal-of-builtin-themes","text":"All themes other than mkdocs and readthedocs will be moved into external packages in a future release of MkDocs. This will enable them to be more easily supported and updates outside MkDocs releases.","title":"Warn users about the removal of builtin themes"},{"location":"about/release-notes/#major-additions-to-version-0130","text":"","title":"Major Additions to Version 0.13.0"},{"location":"about/release-notes/#search","text":"Support for search has now been added to MkDocs. This is based on the JavaScript library lunr.js . It has been added to both the mkdocs and readthedocs themes. See the custom theme documentation on supporting search for adding it to your own themes.","title":"Search"},{"location":"about/release-notes/#new-command-line-interface","text":"The command line interface for MkDocs has been re-written with the Python library Click . This means that MkDocs now has an easier to use interface with better help output. This change is partially backwards incompatible as while undocumented it was possible to pass any configuration option to the different commands. Now only a small subset of the configuration options can be passed to the commands. To see in full commands and available arguments use mkdocs --help and mkdocs build --help to have them displayed.","title":"New Command Line Interface"},{"location":"about/release-notes/#support-extra-html-and-xml-files","text":"Like the extra_javascript and extra_css configuration options, a new option named extra_templates has been added. This will automatically be populated with any .html or .xml files in the project docs directory. Users can place static HTML and XML files and they will be copied over, or they can also use Jinja2 syntax and take advantage of the global variables . By default MkDocs will use this approach to create a sitemap for the documentation.","title":"Support Extra HTML and XML files"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0130","text":"Add support for Markdown extension configuration options . ( #435 ) MkDocs now ships Python wheels . ( #486 ) Only include the build date and MkDocs version on the homepage. ( #490 ) Generate sitemaps for documentation builds. ( #436 ) Add a clearer way to define nested pages in the configuration. ( #482 ) Add an extra config option for passing arbitrary variables to the template. ( #510 ) Add --no-livereload to mkdocs serve for a simpler development server. ( #511 ) Add copyright display support to all themes ( #549 ) Add support for custom commit messages in a mkdocs gh-deploy ( #516 ) Bugfix: Fix linking to media within the same directory as a markdown file called index.md ( #535 ) Bugfix: Fix errors with Unicode filenames ( #542 ).","title":"Other Changes and Additions to Version 0.13.0"},{"location":"about/release-notes/#version-0122-2015-04-22","text":"Bugfix: Fix a regression where there would be an error if some child titles were missing but others were provided in the pages config. ( #464 )","title":"Version 0.12.2 (2015-04-22)"},{"location":"about/release-notes/#version-0121-2015-04-14","text":"Bugfix: Fixed a CSS bug in the table of contents on some browsers where the bottom item was not clickable.","title":"Version 0.12.1 (2015-04-14)"},{"location":"about/release-notes/#version-0120-2015-04-14","text":"Display the current MkDocs version in the CLI output. ( #258 ) Check for CNAME file when using gh-deploy. ( #285 ) Add the homepage back to the navigation on all themes. ( #271 ) Add a strict more for local link checking. ( #279 ) Add Google analytics support to all themes. ( #333 ) Add build date and MkDocs version to the ReadTheDocs and MkDocs theme outputs. ( #382 ) Standardize highlighting across all themes and add missing languages. ( #387 ) Add a verbose flag. (-v) to show more details about what the build. ( #147 ) Add the option to specify a remote branch when deploying to GitHub. This enables deploying to GitHub pages on personal and repo sites. ( #354 ) Add favicon support to the ReadTheDocs theme HTML. ( #422 ) Automatically refresh the browser when files are edited. ( #163 ) Bugfix: Never re-write URLs in code blocks. ( #240 ) Bugfix: Don't copy dotfiles when copying media from the docs_dir . ( #254 ) Bugfix: Fix the rendering of tables in the ReadTheDocs theme. ( #106 ) Bugfix: Add padding to the bottom of all bootstrap themes. ( #255 ) Bugfix: Fix issues with nested Markdown pages and the automatic pages configuration. ( #276 ) Bugfix: Fix a URL parsing error with GitHub enterprise. ( #284 ) Bugfix: Don't error if the mkdocs.yml is completely empty. ( #288 ) Bugfix: Fix a number of problems with relative URLs and Markdown files. ( #292 ) Bugfix: Don't stop the build if a page can't be found, continue with other pages. ( #150 ) Bugfix: Remove the site_name from the page title, this needs to be added manually. ( #299 ) Bugfix: Fix an issue with table of contents cutting off Markdown. ( #294 ) Bugfix: Fix hostname for BitBucket. ( #339 ) Bugfix: Ensure all links end with a slash. ( #344 ) Bugfix: Fix repo links in the readthedocs theme. ( #365 ) Bugfix: Include jQuery locally to avoid problems using MkDocs offline. ( #143 ) Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. ( #384 ) Bugfix: Remove inline CSS in the ReadTheDocs theme. ( #393 ) Bugfix: Fix problems with the child titles due to the order the pages config was processed. ( #395 ) Bugfix: Don't error during live reload when the theme doesn't exist. ( #373 ) Bugfix: Fix problems with the Meta extension when it may not exist. ( #398 ) Bugfix: Wrap long inline code otherwise they will run off the screen. ( #313 ) Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to fix problems with titles containing code. ( #367 ) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden under the navigation. ( #7 ) Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. ( #295 ) Bugfix: Fix an error when passing in a specific config file with mkdocs serve . ( #341 ) Bugfix: Don't overwrite index.md files with the mkdocs new command. ( #412 ) Bugfix: Remove bold and italic from code in the ReadTheDocs theme. ( #411 ) Bugfix: Display images inline in the MkDocs theme. ( #415 ) Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. ( #319 ) Bugfix: Don't delete hidden files when using mkdocs build --clean . ( #346 ) Bugfix: Don't block newer versions of Python-markdown on Python >= 2.7. ( #376 ) Bugfix: Fix encoding issues when opening files across platforms. ( #428 )","title":"Version 0.12.0 (2015-04-14)"},{"location":"about/release-notes/#version-0111-2014-11-20","text":"Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs theme. ( #233 )","title":"Version 0.11.1 (2014-11-20)"},{"location":"about/release-notes/#version-0110-2014-11-18","text":"Render 404.html files if they exist for the current theme. ( #194 ) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs and ReadTheDocs themes. ( #225 ) Bugfix: Fix an issue with the google_analytics code. ( #219 ) Bugfix: Remove __pycache__ from the package tar. ( #196 ) Bugfix: Fix markdown links that go to an anchor on the current page. ( #197 ) Bugfix: Don't add prettyprint well CSS classes to all HTML, only add it in the MkDocs theme. ( #183 ) Bugfix: Display section titles in the ReadTheDocs theme. ( #175 ) Bugfix: Use the polling observer in watchdog so rebuilding works on filesystems without inotify. ( #184 ) Bugfix: Improve error output for common configuration related errors. ( #176 )","title":"Version 0.11.0 (2014-11-18)"},{"location":"about/release-notes/#version-0100-2014-10-29","text":"Added support for Python 3.3 and 3.4. ( #103 ) Configurable Python-Markdown extensions with the config setting markdown_extensions . ( #74 ) Added mkdocs json command to output your rendered documentation as json files. ( #128 ) Added --clean switch to build , json and gh-deploy commands to remove stale files from the output directory. ( #157 ) Support multiple theme directories to allow replacement of individual templates rather than copying the full theme. ( #129 ) Bugfix: Fix <ul> rendering in readthedocs theme. ( #171 ) Bugfix: Improve the readthedocs theme on smaller displays. ( #168 ) Bugfix: Relaxed required python package versions to avoid clashes. ( #104 ) Bugfix: Fix issue rendering the table of contents with some configs. ( #146 ) Bugfix: Fix path for embedded images in sub pages. ( #138 ) Bugfix: Fix use_directory_urls config behavior. ( #63 ) Bugfix: Support extra_javascript and extra_css in all themes. ( #90 ) Bugfix: Fix path-handling under Windows. ( #121 ) Bugfix: Fix the menu generation in the readthedocs theme. ( #110 ) Bugfix: Fix the mkdocs command creation under Windows. ( #122 ) Bugfix: Correctly handle external extra_javascript and extra_css . ( #92 ) Bugfix: Fixed favicon support. ( #87 )","title":"Version 0.10.0 (2014-10-29)"},{"location":"dev-guide/","text":"Developer Guide \uf0c1 Extending MkDocs The MkDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the Contributing Guide for information on contributing to MkDocs itself. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Themes Plugins","title":"Overview"},{"location":"dev-guide/#developer-guide","text":"Extending MkDocs The MkDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the Contributing Guide for information on contributing to MkDocs itself. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Themes Plugins","title":"Developer Guide"},{"location":"dev-guide/plugins/","text":"MkDocs Plugins \uf0c1 A Guide to installing, using and creating MkDocs Plugins Installing Plugins \uf0c1 Before a plugin can be used, it must be installed on the system. If you are using a plugin which comes with MkDocs, then it was installed when you installed MkDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using pip : pip install mkdocs-foo-plugin Once a plugin has been successfully installed, it is ready to use. It just needs to be enabled in the configuration file. The MkDocs Plugins wiki page has a growing list of plugins that you can install and use. Using Plugins \uf0c1 The plugins configuration option should contain a list of plugins to use when building the site. Each \"plugin\" must be a string name assigned to the plugin (see the documentation for a given plugin to determine its \"name\"). A plugin listed here must already be installed . plugins: - search Some plugins may 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 plugin supports. Note that a colon ( : ) must follow the plugin name and then on a new line the option name and value must be indented and separated by a colon. If you would like to define multiple options for a single plugin, each option must be defined on a separate line. plugins: - search: lang: en foo: bar For information regarding the configuration options available for a given plugin, see that plugin's documentation. For a list of default plugins and how to override them, see the configuration documentation. Developing Plugins \uf0c1 Like MkDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is possible to define multiple plugins in the same module. At a minimum, a MkDocs Plugin must consist of a BasePlugin subclass and an entry point which points to it. BasePlugin \uf0c1 A subclass of mkdocs.plugins.BasePlugin should define the behavior of the plugin. The class generally consists of actions to perform on specific events in the build process as well as a configuration scheme for the plugin. All BasePlugin subclasses contain the following attributes: config_scheme \uf0c1 A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of mkdocs.config.config_options.BaseConfigOption or any of its subclasses. For example, the following config_scheme defines three configuration options: foo , which accepts a string; bar , which accepts an integer; and baz , which accepts a boolean value. class MyPlugin(mkdocs.plugins.BasePlugin): config_scheme = ( ('foo', mkdocs.config.config_options.Type(str, default='a default value')), ('bar', mkdocs.config.config_options.Type(int, default=0)), ('baz', mkdocs.config.config_options.Type(bool, default=True)) ) When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes provided in mkdocs.config.config_options or a third party subclass defined in the plugin. Any settings provided by the user which fail validation or are not defined in the config_scheme will raise a mkdocs.config.base.ValidationError . config \uf0c1 A dictionary of configuration options for the plugin, which is populated by the load_config method after configuration validation has completed. Use this attribute to access options provided by the user. def on_pre_build(self, config): if self.config['bool_option']: # implement \"bool_option\" functionality here... All BasePlugin subclasses contain the following method(s): load_config(options) \uf0c1 Loads configuration from a dictionary of options. Returns a tuple of (errors, warnings) . This method is called by MkDocs during configuration validation and should not need to be called by the plugin. on_<event_name>() \uf0c1 Optional methods which define the behavior for specific events . The plugin should define its behavior within these methods. Replace <event_name> with the actual name of the event. For example, the pre_build event would be defined in the on_pre_build method. Most events accept one positional argument and various keyword arguments. It is generally expected that the positional argument would be modified (or replaced) by the plugin and returned. If nothing is returned (the method returns None ), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as **kwargs . In the event that additional keywords are provided to an event in a future version of MkDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to the theme config: class MyPlugin(BasePlugin): def on_config(self, config, **kwargs): config['theme'].static_templates.add('my_template.html') return config Events \uf0c1 There are three kinds of events: Global Events , Page Events and Template Events . Global Events \uf0c1 Global events are called once per build at either the beginning or end of the build process. Any changes made in these events will have a global effect on the entire site. on_serve \uf0c1 The serve event is only called when the serve command is used during development. It is passed the Server instance which can be modified before it is activated. For example, additional files or directories could be added to the list of \"watched\" files for auto-reloading. Parameters: server: livereload.Server instance config: global configuration object builder: a callable which gets passed to each call to server.watch Returns: livereload.Server instance on_config \uf0c1 The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here. Parameters: config: global configuration object Returns: global configuration object on_pre_build \uf0c1 The pre_build event does not alter any variables. Use this event to call pre-build scripts. Parameters: config: global configuration object on_files \uf0c1 The files event is called after the files collection is populated from the docs_dir . Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data. Parameters: files: global files collection config: global configuration object Returns: global files collection on_nav \uf0c1 The nav event is called after the site navigation is created and can be used to alter the site navigation. Parameters: nav: global navigation object config: global configuration object files: global files collection Returns: global navigation object on_env \uf0c1 The env event is called after the Jinja template environment is created and can be used to alter the Jinja environment . Parameters: env: global Jinja environment config: global configuration object files: global files collection Returns: global Jinja Environment on_post_build \uf0c1 The post_build event does not alter any variables. Use this event to call post-build scripts. Parameters: config: global configuration object on_build_error \uf0c1 The build_error event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See Handling Errors for more details. Parameters: error: exception raised Template Events \uf0c1 Template events are called once for each non-page template. Each template event will be called for each template defined in the extra_templates config setting as well as any static_templates defined in the theme. All template events are called after the env event and before any page events . on_pre_template \uf0c1 The pre_template event is called immediately after the subject template is loaded and can be used to alter the template. Parameters: template : a Jinja2 Template object template_name : string filename of template config: global configuration object Returns: a Jinja2 Template object on_template_context \uf0c1 The template_context event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only. Parameters: context : dict of template context variables template_name : string filename of template config: global configuration object Returns: dict of template context variables on_post_template \uf0c1 The post_template event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc. Parameters: output_content : output of rendered template as string template_name : string filename of template config: global configuration object Returns: output of rendered template as string Page Events \uf0c1 Page events are called once for each Markdown page included in the site. All page events are called after the post_template event and before the post_build event. on_pre_page \uf0c1 The pre_page event is called before any actions are taken on the subject page and can be used to alter the Page instance. Parameters: page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: mkdocs.nav.Page instance on_page_read_source \uf0c1 The on_page_read_source event can replace the default mechanism to read the contents of a page's source from the filesystem. Parameters: page: mkdocs.nav.Page instance config: global configuration object Returns: The raw source for a page as unicode string. If None is returned, the default loading from a file will be performed. on_page_markdown \uf0c1 The page_markdown event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as page.meta at this point. Parameters: markdown: Markdown source text of page as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: Markdown source text of page as string on_page_content \uf0c1 The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page. Parameters: html: HTML rendered from Markdown source as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: HTML rendered from Markdown source as string on_page_context \uf0c1 The page_context event is called after the context for a page is created and can be used to alter the context for that specific page only. Parameters: context : dict of template context variables page: mkdocs.nav.Page instance config: global configuration object nav: global navigation object Returns: dict of template context variables on_post_page \uf0c1 The post_page event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc. Parameters: output: output of rendered template as string page: mkdocs.nav.Page instance config: global configuration object Returns: output of rendered template as string Handling Errors \uf0c1 MkDocs defines four error types: mkdocs.exceptions.MkDocsException \uf0c1 The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead. mkdocs.exceptions.ConfigurationError \uf0c1 This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's config_scheme . mkdocs.exceptions.BuildError \uf0c1 This error may be raised by MkDocs during the build process. Plugins should not raise this error. mkdocs.exceptions.PluginError \uf0c1 A subclass of mkdocs.exceptions.BuildError which can be raised by plugin events. Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error message. Therefore, MkDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. Therefore, you might want to catch any exceptions within your plugin and raise a PluginError , passing in your own custom-crafted message, so that the build process is aborted with a helpful message. The on_build_error event will be triggered for any exception. For example: from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin class MyPlugin(BasePlugin): def on_post_page(self, output, page, config, **kwargs): try: # some code that could throw a KeyError ... except KeyError as error: raise PluginError(str(error)) def on_build_error(self, error): # some code to clean things up ... Entry Point \uf0c1 Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_point. Add the following to your setup.py script: entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself ( from path.to.some_plugin import SomePluginClass ) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry_point. entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] } Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.","title":"Plugins"},{"location":"dev-guide/plugins/#mkdocs-plugins","text":"A Guide to installing, using and creating MkDocs Plugins","title":"MkDocs Plugins"},{"location":"dev-guide/plugins/#installing-plugins","text":"Before a plugin can be used, it must be installed on the system. If you are using a plugin which comes with MkDocs, then it was installed when you installed MkDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using pip : pip install mkdocs-foo-plugin Once a plugin has been successfully installed, it is ready to use. It just needs to be enabled in the configuration file. The MkDocs Plugins wiki page has a growing list of plugins that you can install and use.","title":"Installing Plugins"},{"location":"dev-guide/plugins/#using-plugins","text":"The plugins configuration option should contain a list of plugins to use when building the site. Each \"plugin\" must be a string name assigned to the plugin (see the documentation for a given plugin to determine its \"name\"). A plugin listed here must already be installed . plugins: - search Some plugins may 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 plugin supports. Note that a colon ( : ) must follow the plugin name and then on a new line the option name and value must be indented and separated by a colon. If you would like to define multiple options for a single plugin, each option must be defined on a separate line. plugins: - search: lang: en foo: bar For information regarding the configuration options available for a given plugin, see that plugin's documentation. For a list of default plugins and how to override them, see the configuration documentation.","title":"Using Plugins"},{"location":"dev-guide/plugins/#developing-plugins","text":"Like MkDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is possible to define multiple plugins in the same module. At a minimum, a MkDocs Plugin must consist of a BasePlugin subclass and an entry point which points to it.","title":"Developing Plugins"},{"location":"dev-guide/plugins/#baseplugin","text":"A subclass of mkdocs.plugins.BasePlugin should define the behavior of the plugin. The class generally consists of actions to perform on specific events in the build process as well as a configuration scheme for the plugin. All BasePlugin subclasses contain the following attributes:","title":"BasePlugin"},{"location":"dev-guide/plugins/#config_scheme","text":"A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of mkdocs.config.config_options.BaseConfigOption or any of its subclasses. For example, the following config_scheme defines three configuration options: foo , which accepts a string; bar , which accepts an integer; and baz , which accepts a boolean value. class MyPlugin(mkdocs.plugins.BasePlugin): config_scheme = ( ('foo', mkdocs.config.config_options.Type(str, default='a default value')), ('bar', mkdocs.config.config_options.Type(int, default=0)), ('baz', mkdocs.config.config_options.Type(bool, default=True)) ) When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes provided in mkdocs.config.config_options or a third party subclass defined in the plugin. Any settings provided by the user which fail validation or are not defined in the config_scheme will raise a mkdocs.config.base.ValidationError .","title":"config_scheme"},{"location":"dev-guide/plugins/#config","text":"A dictionary of configuration options for the plugin, which is populated by the load_config method after configuration validation has completed. Use this attribute to access options provided by the user. def on_pre_build(self, config): if self.config['bool_option']: # implement \"bool_option\" functionality here... All BasePlugin subclasses contain the following method(s):","title":"config"},{"location":"dev-guide/plugins/#load_configoptions","text":"Loads configuration from a dictionary of options. Returns a tuple of (errors, warnings) . This method is called by MkDocs during configuration validation and should not need to be called by the plugin.","title":"load_config(options)"},{"location":"dev-guide/plugins/#on_event_name","text":"Optional methods which define the behavior for specific events . The plugin should define its behavior within these methods. Replace <event_name> with the actual name of the event. For example, the pre_build event would be defined in the on_pre_build method. Most events accept one positional argument and various keyword arguments. It is generally expected that the positional argument would be modified (or replaced) by the plugin and returned. If nothing is returned (the method returns None ), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as **kwargs . In the event that additional keywords are provided to an event in a future version of MkDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to the theme config: class MyPlugin(BasePlugin): def on_config(self, config, **kwargs): config['theme'].static_templates.add('my_template.html') return config","title":"on_&lt;event_name&gt;()"},{"location":"dev-guide/plugins/#events","text":"There are three kinds of events: Global Events , Page Events and Template Events .","title":"Events"},{"location":"dev-guide/plugins/#global-events","text":"Global events are called once per build at either the beginning or end of the build process. Any changes made in these events will have a global effect on the entire site.","title":"Global Events"},{"location":"dev-guide/plugins/#on_serve","text":"The serve event is only called when the serve command is used during development. It is passed the Server instance which can be modified before it is activated. For example, additional files or directories could be added to the list of \"watched\" files for auto-reloading. Parameters: server: livereload.Server instance config: global configuration object builder: a callable which gets passed to each call to server.watch Returns: livereload.Server instance","title":"on_serve"},{"location":"dev-guide/plugins/#on_config","text":"The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here. Parameters: config: global configuration object Returns: global configuration object","title":"on_config"},{"location":"dev-guide/plugins/#on_pre_build","text":"The pre_build event does not alter any variables. Use this event to call pre-build scripts. Parameters: config: global configuration object","title":"on_pre_build"},{"location":"dev-guide/plugins/#on_files","text":"The files event is called after the files collection is populated from the docs_dir . Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data. Parameters: files: global files collection config: global configuration object Returns: global files collection","title":"on_files"},{"location":"dev-guide/plugins/#on_nav","text":"The nav event is called after the site navigation is created and can be used to alter the site navigation. Parameters: nav: global navigation object config: global configuration object files: global files collection Returns: global navigation object","title":"on_nav"},{"location":"dev-guide/plugins/#on_env","text":"The env event is called after the Jinja template environment is created and can be used to alter the Jinja environment . Parameters: env: global Jinja environment config: global configuration object files: global files collection Returns: global Jinja Environment","title":"on_env"},{"location":"dev-guide/plugins/#on_post_build","text":"The post_build event does not alter any variables. Use this event to call post-build scripts. Parameters: config: global configuration object","title":"on_post_build"},{"location":"dev-guide/plugins/#on_build_error","text":"The build_error event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See Handling Errors for more details. Parameters: error: exception raised","title":"on_build_error"},{"location":"dev-guide/plugins/#template-events","text":"Template events are called once for each non-page template. Each template event will be called for each template defined in the extra_templates config setting as well as any static_templates defined in the theme. All template events are called after the env event and before any page events .","title":"Template Events"},{"location":"dev-guide/plugins/#on_pre_template","text":"The pre_template event is called immediately after the subject template is loaded and can be used to alter the template. Parameters: template : a Jinja2 Template object template_name : string filename of template config: global configuration object Returns: a Jinja2 Template object","title":"on_pre_template"},{"location":"dev-guide/plugins/#on_template_context","text":"The template_context event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only. Parameters: context : dict of template context variables template_name : string filename of template config: global configuration object Returns: dict of template context variables","title":"on_template_context"},{"location":"dev-guide/plugins/#on_post_template","text":"The post_template event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc. Parameters: output_content : output of rendered template as string template_name : string filename of template config: global configuration object Returns: output of rendered template as string","title":"on_post_template"},{"location":"dev-guide/plugins/#page-events","text":"Page events are called once for each Markdown page included in the site. All page events are called after the post_template event and before the post_build event.","title":"Page Events"},{"location":"dev-guide/plugins/#on_pre_page","text":"The pre_page event is called before any actions are taken on the subject page and can be used to alter the Page instance. Parameters: page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: mkdocs.nav.Page instance","title":"on_pre_page"},{"location":"dev-guide/plugins/#on_page_read_source","text":"The on_page_read_source event can replace the default mechanism to read the contents of a page's source from the filesystem. Parameters: page: mkdocs.nav.Page instance config: global configuration object Returns: The raw source for a page as unicode string. If None is returned, the default loading from a file will be performed.","title":"on_page_read_source"},{"location":"dev-guide/plugins/#on_page_markdown","text":"The page_markdown event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as page.meta at this point. Parameters: markdown: Markdown source text of page as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: Markdown source text of page as string","title":"on_page_markdown"},{"location":"dev-guide/plugins/#on_page_content","text":"The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page. Parameters: html: HTML rendered from Markdown source as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: HTML rendered from Markdown source as string","title":"on_page_content"},{"location":"dev-guide/plugins/#on_page_context","text":"The page_context event is called after the context for a page is created and can be used to alter the context for that specific page only. Parameters: context : dict of template context variables page: mkdocs.nav.Page instance config: global configuration object nav: global navigation object Returns: dict of template context variables","title":"on_page_context"},{"location":"dev-guide/plugins/#on_post_page","text":"The post_page event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc. Parameters: output: output of rendered template as string page: mkdocs.nav.Page instance config: global configuration object Returns: output of rendered template as string","title":"on_post_page"},{"location":"dev-guide/plugins/#handling-errors","text":"MkDocs defines four error types:","title":"Handling Errors"},{"location":"dev-guide/plugins/#mkdocsexceptionsmkdocsexception","text":"The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead.","title":"mkdocs.exceptions.MkDocsException"},{"location":"dev-guide/plugins/#mkdocsexceptionsconfigurationerror","text":"This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's config_scheme .","title":"mkdocs.exceptions.ConfigurationError"},{"location":"dev-guide/plugins/#mkdocsexceptionsbuilderror","text":"This error may be raised by MkDocs during the build process. Plugins should not raise this error.","title":"mkdocs.exceptions.BuildError"},{"location":"dev-guide/plugins/#mkdocsexceptionspluginerror","text":"A subclass of mkdocs.exceptions.BuildError which can be raised by plugin events. Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error message. Therefore, MkDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. Therefore, you might want to catch any exceptions within your plugin and raise a PluginError , passing in your own custom-crafted message, so that the build process is aborted with a helpful message. The on_build_error event will be triggered for any exception. For example: from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin class MyPlugin(BasePlugin): def on_post_page(self, output, page, config, **kwargs): try: # some code that could throw a KeyError ... except KeyError as error: raise PluginError(str(error)) def on_build_error(self, error): # some code to clean things up ...","title":"mkdocs.exceptions.PluginError"},{"location":"dev-guide/plugins/#entry-point","text":"Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_point. Add the following to your setup.py script: entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself ( from path.to.some_plugin import SomePluginClass ) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry_point. entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] } Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.","title":"Entry Point"},{"location":"dev-guide/themes/","text":"Developing Themes \uf0c1 A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage. Creating a custom theme \uf0c1 The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \"mkdocs\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme. Basic theme \uf0c1 The simplest main.html file is the following: <!DOCTYPE html> <html> <head> <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title> </head> <body> {{ page.content }} </body> </html> The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency. Theme Files \uf0c1 There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file. Template Files \uf0c1 Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension. Theme Meta Files \uf0c1 The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files. Dot Files \uf0c1 Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt Documentation Files \uf0c1 All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored. Template Variables \uf0c1 Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html. Global Context \uf0c1 The following variables are available globally on any template. config \uf0c1 The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics nav \uf0c1 The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes: nav.homepage \uf0c1 The page object for the homepage of the site. nav.pages \uf0c1 A flat list of all page objects contained in the navigation. This list is not necessarily a complete list of all site pages as it does not contain pages which are not included in the navigation. This list does match the list and order of pages used for all \"next page\" and \"previous page\" links. For a list of all pages, use the pages template variable. Nav Example \uf0c1 Following is a basic usage example which outputs the first and second level navigation as a nested list. {% if nav|length>1 %} <ul> {% for nav_item in nav %} {% if nav_item.children %} <li>{{ nav_item.title }} <ul> {% for nav_item in nav_item.children %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endfor %} </ul> </li> {% else %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endif %} {% endfor %} </ul> {% endif %} base_url \uf0c1 The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url . mkdocs_version \uf0c1 Contains the current MkDocs version. build_date_utc \uf0c1 A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated. pages \uf0c1 A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page . page \uf0c1 In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes: page.title \uf0c1 Contains the Title for the current page. page.content \uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. page.toc \uf0c1 An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink which contains the following attributes: AnchorLink.title : The text of the item. AnchorLink.url : The hash fragment of a URL pointing to the item. AnchorLink.level : The zero-based level of the item. AnchorLink.children : An iterable of any child items. The following example would display the top two levels of the Table of Contents for a page. <ul> {% for toc_item in page.toc %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% for toc_item in toc_item.children %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% endfor %} {% endfor %} </ul> page.meta \uf0c1 A mapping of the metadata included at the top of the markdown page. In this example we define a source property above the page title. source: generics.py mixins.py # Page title Content... A template can access this metadata for the page with the meta.source variable. This could then be used to link to source files related to the documentation page. {% for filename in page.meta.source %} <a class=\"github\" href=\"https://github.com/.../{{ filename }}\"> <span class=\"label label-info\">{{ filename }}</span> </a> {% endfor %} page.url \uf0c1 The URL of the page relative to the MkDocs site_dir . It is expected that this be used with the url filter to ensure the URL is relative to the current page. <a href=\"{{ page.url|url }}\">{{ page.title }}</a> page.abs_url \uf0c1 The absolute URL of the page from the server root as determined by the value assigned to the site_url configuration setting. The value includes any subdirectory included in the site_url , but not the domain. base_url should not be used with this variable. For example, if site_url: https://example.com/ , then the value of page.abs_url for the page foo.md would be /foo/ . However, if site_url: https://example.com/bar/ , then the value of page.abs_url for the page foo.md would be /bar/foo/ . page.canonical_url \uf0c1 The full, canonical URL to the current page as determined by the value assigned to the site_url configuration setting. The value includes the domain and any subdirectory included in the site_url . base_url should not be used with this variable. page.edit_url \uf0c1 The full URL to the source page in the source repository. Typically used to provide a link to edit the source page. base_url should not be used with this variable. page.is_homepage \uf0c1 Evaluates to True for the homepage of the site and False for all other pages. This can be used in conjunction with other attributes of the page object to alter the behavior. For example, to display a different title on the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }} page.previous_page \uf0c1 The page object for the previous page or None . The value will be None if the current page is the first item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page . page.next_page \uf0c1 The page object for the next page or None . The value will be None if the current page is the last item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page . page.parent \uf0c1 The immediate parent of the page in the site navigation . None if the page is at the top level. page.children \uf0c1 Pages do not contain children and the attribute is always None . page.active \uf0c1 When True , indicates that this page is the currently viewed page. Defaults to False . page.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for page objects. page.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always True for page objects. page.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for page objects. Navigation Objects \uf0c1 Navigation objects contained in the nav template variable may be one of section objects, page objects, and link objects. While section objects may contain nested navigation objects, pages and links do not. Page objects are the full page object as used for the current page with all of the same attributes available. Section and Link objects contain a subset of those attributes as defined below: Section \uf0c1 A section navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain URLs and are not links of any kind. However, by default, MkDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. The following attributes are available on section objects: section.title \uf0c1 The title of the section. section.parent \uf0c1 The immediate parent of the section or None if the section is at the top level. section.children \uf0c1 An iterable of all child navigation objects. Children may include nested sections, pages and links. section.active \uf0c1 When True , indicates that a child page of this section is the current page and can be used to highlight the section as the currently viewed section. Defaults to False . section.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always True for section objects. section.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for section objects. section.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for section objects. Link \uf0c1 A link navigation object contains a link which does not point to an internal MkDocs page. The following attributes are available on link objects: link.title \uf0c1 The title of the link. This would generally be used as the label of the link. link.url \uf0c1 The URL that the link points to. The URL should always be an absolute URLs and should not need to have base_url prepended. link.parent \uf0c1 The immediate parent of the link. None if the link is at the top level. link.children \uf0c1 Links do not contain children and the attribute is always None . link.active \uf0c1 External links cannot be \"active\" and the attribute is always False . link.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for link objects. link.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for link objects. link.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always True for link objects. Extra Context \uf0c1 Additional variables can be passed to the template with the extra configuration option. This is a set of key value pairs that can make custom templates far more flexible. For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following extra configuration: extra: version: 0.13.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - https://www.mkdocs.org/ And then displayed with this HTML in the custom theme. {{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %} Template Filters \uf0c1 In addition to Jinja's default filters, the following custom filters are available to use in MkDocs templates: url \uf0c1 Normalizes a URL. Absolute URLs are passed through unaltered. If the URL is relative and the template context includes a page object, then the URL is returned relative to the page object. Otherwise, the URL is returned with base_url prepended. <a href=\"{{ page.url|url }}\">{{ page.title }}</a> tojson \uf0c1 Safety convert a Python object to a value in a JavaScript script. <script> var mkdocs_page_name = {{ page.title|tojson|safe }}; </script> Search and themes \uf0c1 As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. <script>var base_url = '{{ base_url }}';</script> With properly configured settings, the following HTML in a template will add a full search implementation to your theme. <h1 id=\"search\">Search Results</h1> <form action=\"search.html\"> <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" > </form> <div id=\"mkdocs-search-results\"> Sorry, page not found. </div> The JavaScript in the plugin works by looking for the specific ID's used in the above HTML. The form input for the user to type the search query must be identified with id=\"mkdocs-search-query\" and the div where the results will be placed must be identified with id=\"mkdocs-search-results\" . The plugin supports the following options being set in the theme's configuration file , mkdocs_theme.yml : include_search_page \uf0c1 Determines whether the search plugin expects the theme to provide a dedicated search page via a template located at search/search.html . When include_search_page is set to true , the search template will be built and available at search/search.html . This method is used by the readthedocs theme. When include_search_page is set to false or not defined, it is expected that the theme provide some other mechanisms for displaying search results. For example, the mkdocs theme displays results on any page via a modal. search_index_only \uf0c1 Determines whether the search plugin should only generate a search index or a complete search solution. When search_index_only is set to false , then the search plugin modifies the Jinja environment by adding its own templates directory (with a lower precedence than the theme) and adds its scripts to the extra_javascript config setting. When search_index_only is set to true or not defined, the search plugin makes no modifications to the Jinja environment. A complete solution using the provided index file is the responsibility of the theme. The search index is written to a JSON file at search/search_index.json in the site_dir . The JSON object contained within the file may contain up to three objects. { config: {...}, data: [...], index: {...} } If present, the config object contains the key/value pairs of config options defined for the plugin in the user's mkdocs.yml config file under plugings.search . The config object was new in MkDocs version 1.0 . The data object contains a list of document objects. Each document object is made up of a location (URL), a title , and text which can be used to create a search index and/or display search results. If present, the index object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the prebuild_index config option. Themes should expect the index to not be present, but can choose to use the index when it is available. The index object was new in MkDocs version 1.0 . Packaging Themes \uf0c1 MkDocs makes use of Python packaging to distribute themes. This comes with a few requirements. To see an example of a package containing one theme, see the MkDocs Bootstrap theme and to see a package that contains many themes, see the MkDocs Bootswatch theme . Note It is not strictly necessary to package a theme, as the entire theme can be contained in the custom_dir . If you have created a \"one-off theme,\" that should be sufficient. However, if you intend to distribute your theme for others to use, packaging the theme has some advantages. By packaging your theme, your users can more easily install it, they can rely on a default configuration being defined, and they can then take advantage of the custom_dir to make tweaks to your theme to better suit their needs. Package Layout \uf0c1 The following layout is recommended for themes. Two files at the top level directory called MANIFEST.in and setup.py beside the theme directory which contains an empty __init__.py file, a theme configuration file ( mkdocs-theme.yml ), and your template and media files. . |-- MANIFEST.in |-- theme_name | |-- __init__.py | |-- mkdocs-theme.yml | |-- main.html | |-- styles.css `-- setup.py The MANIFEST.in file should contain the following contents but with theme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff recursive-exclude * __pycache__ recursive-exclude * *.py[co] The setup.py should include the following text with the modifications described below. from setuptools import setup, find_packages VERSION = '0.0.1' setup( name=\"mkdocs-themename\", version=VERSION, url='', license='', description='', author='', author_email='', packages=find_packages(), include_package_data=True, entry_points={ 'mkdocs.themes': [ 'themename = theme_name', ] }, zip_safe=False ) Fill in the URL, license, description, author and author email address. The name should follow the convention mkdocs-themename (like mkdocs- bootstrap and mkdocs-bootswatch ), starting with MkDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to change is the entry_points. This is how MkDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. The directory you created at the start of this section with the main.html file should contain all of the other theme files. The minimum requirement is that it includes a main.html for the theme. It must also include a __init__.py file which should be empty, this file tells Python that the directory is a package. Theme Configuration \uf0c1 A packaged theme is required to include a configuration file named mkdocs_theme.yml which is placed in the root of your template files. The file should contain default configuration options for the theme. However, if the theme offers no configuration options, the file is still required and can be left blank. A theme which is not packaged does not need a mkdocs_theme.yml file as that file is not loaded from theme.custom_dir . The theme author is free to define any arbitrary options deemed necessary and those options will be made available in the templates to control behavior. For example, a theme might want to make a sidebar optional and include the following in the mkdocs_theme.yml file: show_sidebar: true Then in a template, that config option could be referenced: {% if config.theme.show_sidebar %} <div id=\"sidebar\">...</div> {% endif %} And the user could override the default in their project's mkdocs.yml config file: theme: name: themename show_sidebar: false In addition to arbitrary options defined by the theme, MkDocs defines a few special options which alters its behavior: locale \uf0c1 This option mirrors the theme config option of the same name. If this value is not defined in the mkdocs_theme.yml file and the user does not set it in mkdocs.yml then it will default to en (English). The value is expected to match the language used in the text provided by the theme (such a \"next\" and \"previous\" links) and should be used as the value of the <html> tag's lang attribute. See Supporting theme localization/ translation for more information. Note that during configuration validation, the provided string is converted to a Locale object. The object contains Locale.language and Locale.territory attributes and will resolve as a string from within a template. Therefore, the following will work fine: <html lang=\"{ config.theme.locale }\"> If the locale was set to fr_CA (Canadian French), then the above template would render as: <html lang=\"fr_CA\"> If you did not want the territory attribute to be included, then reference the language attribute directly: <html lang=\"{ config.theme.locale.language }\"> That would render as: <html lang=\"fr\"> static_templates \uf0c1 This option mirrors the theme config option of the same name and allows some defaults to be set by the theme. Note that while the user can add templates to this list, the user cannot remove templates included in the theme's config. extends \uf0c1 Defines a parent theme that this theme inherits from. The value should be the string name of the parent theme. Normal Jinja inheritance rules apply. Plugins may also define some options which allow the theme to inform a plugin about which set of plugin options it expects. See the documentation for any plugins you may wish to support in your theme. Distributing Themes \uf0c1 With the above changes, your theme should now be ready to install. This can be done with pip, using pip install . if you are still in the same directory as the setup.py. Most Python packages, including MkDocs, are distributed on PyPI. To do this, you should run the following command. python setup.py register If you don't have an account setup, you should be prompted to create one. For a much more detailed guide, see the official Python packaging documentation for Packaging and Distributing Projects . Supporting theme Localization/Translation \uf0c1 While the built-in themes provide support for localization/translation of templates, custom themes and third-party themes may choose not to. Regardless, the locale setting of the theme configuration option is always present and is relied upon by other parts of the system. Therefore, it is recommended that all third-party themes use the same setting for designating a language regardless of the system they use for translation. In that way, users will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the same commands utilized by MkDocs. Enabling the Localization/Translation commands \uf0c1 MkDocs includes some helper commands which are light wrappers around pybabel's commands . To use the commands on your own theme, add the following to your theme's setup.py script: from mkdocs.commands.setup import babel_cmdclass setup( ... cmdclass=babel_cmdclass ) Note that cmdclass=babel_cmdclass was added an a parameter passed to the setup function. Warning As pybabel is not installed by default and most users will not have pybabel installed, theme developers and/or translators should make sure to have installed the necessary dependencies (using pip install mkdocs[i18n] ) in order for the commands to be available for use. Using the Localization/Translation commands \uf0c1 Since the translation commands are embedded in the setup.py script of your custom theme they should be called from the root of your theme's working tree as follows: python setup.py <command_name> [OPTIONS] Each command provides a detailed list of options available with the -h/--help option. For an overview of the workflow used by MkDocs to translate the built-in themes, see the appropriate section of the Contributing Guide and the Translation Guide . Default values for many of the options to the commands can be defined in a setup.cfg file. Create a section using the command name as the section name, and the long option name as the key. See MkDocs' own setup.cfg file for an example. A summary of changes/additions to the behavior and options of the upstream pybabel commands are summarized below. compile_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value of the -d/--directory option. The --directory option is set to {theme_dir}/locales . If a directory is passed to the --directory option, then the theme option is ignored. extract_messages \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the --input-dirs and --output-file options. The --input-dirs option is set to the theme directory and --output-file is set to {theme_dir}/{domain}.pot . If a path is provided to either option, then the theme option is ignored for that option. The --domain option has been added to this command and can be used to override the domain used for the output-file based on the theme . Defaults to messages . The -F/--mapping-file option defaults to the mapping file used by MkDocs' built-in themes. However, if that mapping file does not meet your theme's needs to can override it by providing your own and passing the path of that file into the option. init_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option. update_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option. Example custom theme Localization/Translation workflow \uf0c1 Note If your theme inherits from an existing theme which already provides translation catalogs, your theme's translations will be merged with the parent theme's translations during a MkDocs build. This means that you only need to concentrate on the added translations. Yet, you will still benefit from the translations of the parent theme. At the same time, you may override any of parent theme's translations! Let's suppose that you're working on your own fork of the mkdocs-basic-theme and want to add translations to it. You would first modify the setup.py like this: --- a/setup.py +++ b/setup.py @@ -1,4 +1,5 @@ from setuptools import setup, find_packages +from mkdocs.commands.setup import babel_cmdclass VERSION = '1.1' @@ -18,5 +19,6 @@ setup( 'basictheme = basic_theme', ] }, - zip_safe=False + zip_safe=False, + cmdclass=babel_cmdclass ) Next, you would edit the templates by wrapping text in your HTML sources with {% trans %} and {% endtrans %} as follows: --- a/basic_theme/base.html +++ b/basic_theme/base.html @@ -88,7 +88,7 @@ <body> - <h1>This is an example theme for MkDocs.</h1> + <h1>{% trans %}This is an example theme for MkDocs.{% endtrans %}</h1> <p> It is designed to be read by looking at the theme HTML which is heavily Then you would follow the Translation Guide as usual to get your translations running. Packaging Translations with your theme \uf0c1 While the Portable Object Template ( pot ) file created by the extract_messages command and the Portable Object ( po ) files created by the init_catalog and update_catalog commands are useful for creating and editing translations, they are not used by MkDocs directly and do not need to be included in a packaged release of a theme. When MkDocs builds a site with translations, it only makes use of the binary mo files(s) for the specified locale. Therefore, when packaging a theme , you would need to make the following addition to your MANIFEST.in file: recursive-include theme_name *.mo Then, before building your Python package, you will want to ensure that the binary mo file for each locale is up-to-date by running the compile_catalog command for each locale. MkDocs expects the binary mo files to be located at locales/<locale>/LC_MESSAGES/messages.mo , which the compile_catalog command automatically does for you. See Testing theme translations for details. Note As outlined in our Translation Guide , the MkDocs project has chosen to include the pot and po files in our code repository, but not the mo files. This requires us to always run compile_catalog before packaging a new release regardless of whether any changes were made to a translation or not. However, you may chose an alternate workflow for your theme. At a minimum, you need to ensure that up-to-date mo files are included at the correct location in each release. However, you may use a different process for generating those mo files if you chose to do so.","title":"Themes"},{"location":"dev-guide/themes/#developing-themes","text":"A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage.","title":"Developing Themes"},{"location":"dev-guide/themes/#creating-a-custom-theme","text":"The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \"mkdocs\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme.","title":"Creating a custom theme"},{"location":"dev-guide/themes/#basic-theme","text":"The simplest main.html file is the following: <!DOCTYPE html> <html> <head> <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title> </head> <body> {{ page.content }} </body> </html> The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency.","title":"Basic theme"},{"location":"dev-guide/themes/#theme-files","text":"There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file.","title":"Theme Files"},{"location":"dev-guide/themes/#template-files","text":"Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension.","title":"Template Files"},{"location":"dev-guide/themes/#theme-meta-files","text":"The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files.","title":"Theme Meta Files"},{"location":"dev-guide/themes/#dot-files","text":"Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt","title":"Dot Files"},{"location":"dev-guide/themes/#documentation-files","text":"All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored.","title":"Documentation Files"},{"location":"dev-guide/themes/#template-variables","text":"Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html.","title":"Template Variables"},{"location":"dev-guide/themes/#global-context","text":"The following variables are available globally on any template.","title":"Global Context"},{"location":"dev-guide/themes/#config","text":"The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics","title":"config"},{"location":"dev-guide/themes/#nav","text":"The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes:","title":"nav"},{"location":"dev-guide/themes/#navhomepage","text":"The page object for the homepage of the site.","title":"nav.homepage"},{"location":"dev-guide/themes/#navpages","text":"A flat list of all page objects contained in the navigation. This list is not necessarily a complete list of all site pages as it does not contain pages which are not included in the navigation. This list does match the list and order of pages used for all \"next page\" and \"previous page\" links. For a list of all pages, use the pages template variable.","title":"nav.pages"},{"location":"dev-guide/themes/#nav-example","text":"Following is a basic usage example which outputs the first and second level navigation as a nested list. {% if nav|length>1 %} <ul> {% for nav_item in nav %} {% if nav_item.children %} <li>{{ nav_item.title }} <ul> {% for nav_item in nav_item.children %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endfor %} </ul> </li> {% else %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endif %} {% endfor %} </ul> {% endif %}","title":"Nav Example"},{"location":"dev-guide/themes/#base_url","text":"The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url .","title":"base_url"},{"location":"dev-guide/themes/#mkdocs_version","text":"Contains the current MkDocs version.","title":"mkdocs_version"},{"location":"dev-guide/themes/#build_date_utc","text":"A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated.","title":"build_date_utc"},{"location":"dev-guide/themes/#pages","text":"A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page .","title":"pages"},{"location":"dev-guide/themes/#page","text":"In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes:","title":"page"},{"location":"dev-guide/themes/#pagetitle","text":"Contains the Title for the current page.","title":"page.title"},{"location":"dev-guide/themes/#pagecontent","text":"The rendered Markdown as HTML, this is the contents of the documentation.","title":"page.content"},{"location":"dev-guide/themes/#pagetoc","text":"An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink which contains the following attributes: AnchorLink.title : The text of the item. AnchorLink.url : The hash fragment of a URL pointing to the item. AnchorLink.level : The zero-based level of the item. AnchorLink.children : An iterable of any child items. The following example would display the top two levels of the Table of Contents for a page. <ul> {% for toc_item in page.toc %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% for toc_item in toc_item.children %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% endfor %} {% endfor %} </ul>","title":"page.toc"},{"location":"dev-guide/themes/#pagemeta","text":"A mapping of the metadata included at the top of the markdown page. In this example we define a source property above the page title. source: generics.py mixins.py # Page title Content... A template can access this metadata for the page with the meta.source variable. This could then be used to link to source files related to the documentation page. {% for filename in page.meta.source %} <a class=\"github\" href=\"https://github.com/.../{{ filename }}\"> <span class=\"label label-info\">{{ filename }}</span> </a> {% endfor %}","title":"page.meta"},{"location":"dev-guide/themes/#pageurl","text":"The URL of the page relative to the MkDocs site_dir . It is expected that this be used with the url filter to ensure the URL is relative to the current page. <a href=\"{{ page.url|url }}\">{{ page.title }}</a>","title":"page.url"},{"location":"dev-guide/themes/#pageabs_url","text":"The absolute URL of the page from the server root as determined by the value assigned to the site_url configuration setting. The value includes any subdirectory included in the site_url , but not the domain. base_url should not be used with this variable. For example, if site_url: https://example.com/ , then the value of page.abs_url for the page foo.md would be /foo/ . However, if site_url: https://example.com/bar/ , then the value of page.abs_url for the page foo.md would be /bar/foo/ .","title":"page.abs_url"},{"location":"dev-guide/themes/#pagecanonical_url","text":"The full, canonical URL to the current page as determined by the value assigned to the site_url configuration setting. The value includes the domain and any subdirectory included in the site_url . base_url should not be used with this variable.","title":"page.canonical_url"},{"location":"dev-guide/themes/#pageedit_url","text":"The full URL to the source page in the source repository. Typically used to provide a link to edit the source page. base_url should not be used with this variable.","title":"page.edit_url"},{"location":"dev-guide/themes/#pageis_homepage","text":"Evaluates to True for the homepage of the site and False for all other pages. This can be used in conjunction with other attributes of the page object to alter the behavior. For example, to display a different title on the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}","title":"page.is_homepage"},{"location":"dev-guide/themes/#pageprevious_page","text":"The page object for the previous page or None . The value will be None if the current page is the first item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page .","title":"page.previous_page"},{"location":"dev-guide/themes/#pagenext_page","text":"The page object for the next page or None . The value will be None if the current page is the last item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page .","title":"page.next_page"},{"location":"dev-guide/themes/#pageparent","text":"The immediate parent of the page in the site navigation . None if the page is at the top level.","title":"page.parent"},{"location":"dev-guide/themes/#pagechildren","text":"Pages do not contain children and the attribute is always None .","title":"page.children"},{"location":"dev-guide/themes/#pageactive","text":"When True , indicates that this page is the currently viewed page. Defaults to False .","title":"page.active"},{"location":"dev-guide/themes/#pageis_section","text":"Indicates that the navigation object is a \"section\" object. Always False for page objects.","title":"page.is_section"},{"location":"dev-guide/themes/#pageis_page","text":"Indicates that the navigation object is a \"page\" object. Always True for page objects.","title":"page.is_page"},{"location":"dev-guide/themes/#pageis_link","text":"Indicates that the navigation object is a \"link\" object. Always False for page objects.","title":"page.is_link"},{"location":"dev-guide/themes/#navigation-objects","text":"Navigation objects contained in the nav template variable may be one of section objects, page objects, and link objects. While section objects may contain nested navigation objects, pages and links do not. Page objects are the full page object as used for the current page with all of the same attributes available. Section and Link objects contain a subset of those attributes as defined below:","title":"Navigation Objects"},{"location":"dev-guide/themes/#section","text":"A section navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain URLs and are not links of any kind. However, by default, MkDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. The following attributes are available on section objects:","title":"Section"},{"location":"dev-guide/themes/#sectiontitle","text":"The title of the section.","title":"section.title"},{"location":"dev-guide/themes/#sectionparent","text":"The immediate parent of the section or None if the section is at the top level.","title":"section.parent"},{"location":"dev-guide/themes/#sectionchildren","text":"An iterable of all child navigation objects. Children may include nested sections, pages and links.","title":"section.children"},{"location":"dev-guide/themes/#sectionactive","text":"When True , indicates that a child page of this section is the current page and can be used to highlight the section as the currently viewed section. Defaults to False .","title":"section.active"},{"location":"dev-guide/themes/#sectionis_section","text":"Indicates that the navigation object is a \"section\" object. Always True for section objects.","title":"section.is_section"},{"location":"dev-guide/themes/#sectionis_page","text":"Indicates that the navigation object is a \"page\" object. Always False for section objects.","title":"section.is_page"},{"location":"dev-guide/themes/#sectionis_link","text":"Indicates that the navigation object is a \"link\" object. Always False for section objects.","title":"section.is_link"},{"location":"dev-guide/themes/#link","text":"A link navigation object contains a link which does not point to an internal MkDocs page. The following attributes are available on link objects:","title":"Link"},{"location":"dev-guide/themes/#linktitle","text":"The title of the link. This would generally be used as the label of the link.","title":"link.title"},{"location":"dev-guide/themes/#linkurl","text":"The URL that the link points to. The URL should always be an absolute URLs and should not need to have base_url prepended.","title":"link.url"},{"location":"dev-guide/themes/#linkparent","text":"The immediate parent of the link. None if the link is at the top level.","title":"link.parent"},{"location":"dev-guide/themes/#linkchildren","text":"Links do not contain children and the attribute is always None .","title":"link.children"},{"location":"dev-guide/themes/#linkactive","text":"External links cannot be \"active\" and the attribute is always False .","title":"link.active"},{"location":"dev-guide/themes/#linkis_section","text":"Indicates that the navigation object is a \"section\" object. Always False for link objects.","title":"link.is_section"},{"location":"dev-guide/themes/#linkis_page","text":"Indicates that the navigation object is a \"page\" object. Always False for link objects.","title":"link.is_page"},{"location":"dev-guide/themes/#linkis_link","text":"Indicates that the navigation object is a \"link\" object. Always True for link objects.","title":"link.is_link"},{"location":"dev-guide/themes/#extra-context","text":"Additional variables can be passed to the template with the extra configuration option. This is a set of key value pairs that can make custom templates far more flexible. For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following extra configuration: extra: version: 0.13.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - https://www.mkdocs.org/ And then displayed with this HTML in the custom theme. {{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %}","title":"Extra Context"},{"location":"dev-guide/themes/#template-filters","text":"In addition to Jinja's default filters, the following custom filters are available to use in MkDocs templates:","title":"Template Filters"},{"location":"dev-guide/themes/#url","text":"Normalizes a URL. Absolute URLs are passed through unaltered. If the URL is relative and the template context includes a page object, then the URL is returned relative to the page object. Otherwise, the URL is returned with base_url prepended. <a href=\"{{ page.url|url }}\">{{ page.title }}</a>","title":"url"},{"location":"dev-guide/themes/#tojson","text":"Safety convert a Python object to a value in a JavaScript script. <script> var mkdocs_page_name = {{ page.title|tojson|safe }}; </script>","title":"tojson"},{"location":"dev-guide/themes/#search-and-themes","text":"As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. <script>var base_url = '{{ base_url }}';</script> With properly configured settings, the following HTML in a template will add a full search implementation to your theme. <h1 id=\"search\">Search Results</h1> <form action=\"search.html\"> <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" > </form> <div id=\"mkdocs-search-results\"> Sorry, page not found. </div> The JavaScript in the plugin works by looking for the specific ID's used in the above HTML. The form input for the user to type the search query must be identified with id=\"mkdocs-search-query\" and the div where the results will be placed must be identified with id=\"mkdocs-search-results\" . The plugin supports the following options being set in the theme's configuration file , mkdocs_theme.yml :","title":"Search and themes"},{"location":"dev-guide/themes/#include_search_page","text":"Determines whether the search plugin expects the theme to provide a dedicated search page via a template located at search/search.html . When include_search_page is set to true , the search template will be built and available at search/search.html . This method is used by the readthedocs theme. When include_search_page is set to false or not defined, it is expected that the theme provide some other mechanisms for displaying search results. For example, the mkdocs theme displays results on any page via a modal.","title":"include_search_page"},{"location":"dev-guide/themes/#search_index_only","text":"Determines whether the search plugin should only generate a search index or a complete search solution. When search_index_only is set to false , then the search plugin modifies the Jinja environment by adding its own templates directory (with a lower precedence than the theme) and adds its scripts to the extra_javascript config setting. When search_index_only is set to true or not defined, the search plugin makes no modifications to the Jinja environment. A complete solution using the provided index file is the responsibility of the theme. The search index is written to a JSON file at search/search_index.json in the site_dir . The JSON object contained within the file may contain up to three objects. { config: {...}, data: [...], index: {...} } If present, the config object contains the key/value pairs of config options defined for the plugin in the user's mkdocs.yml config file under plugings.search . The config object was new in MkDocs version 1.0 . The data object contains a list of document objects. Each document object is made up of a location (URL), a title , and text which can be used to create a search index and/or display search results. If present, the index object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the prebuild_index config option. Themes should expect the index to not be present, but can choose to use the index when it is available. The index object was new in MkDocs version 1.0 .","title":"search_index_only"},{"location":"dev-guide/themes/#packaging-themes","text":"MkDocs makes use of Python packaging to distribute themes. This comes with a few requirements. To see an example of a package containing one theme, see the MkDocs Bootstrap theme and to see a package that contains many themes, see the MkDocs Bootswatch theme . Note It is not strictly necessary to package a theme, as the entire theme can be contained in the custom_dir . If you have created a \"one-off theme,\" that should be sufficient. However, if you intend to distribute your theme for others to use, packaging the theme has some advantages. By packaging your theme, your users can more easily install it, they can rely on a default configuration being defined, and they can then take advantage of the custom_dir to make tweaks to your theme to better suit their needs.","title":"Packaging Themes"},{"location":"dev-guide/themes/#package-layout","text":"The following layout is recommended for themes. Two files at the top level directory called MANIFEST.in and setup.py beside the theme directory which contains an empty __init__.py file, a theme configuration file ( mkdocs-theme.yml ), and your template and media files. . |-- MANIFEST.in |-- theme_name | |-- __init__.py | |-- mkdocs-theme.yml | |-- main.html | |-- styles.css `-- setup.py The MANIFEST.in file should contain the following contents but with theme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff recursive-exclude * __pycache__ recursive-exclude * *.py[co] The setup.py should include the following text with the modifications described below. from setuptools import setup, find_packages VERSION = '0.0.1' setup( name=\"mkdocs-themename\", version=VERSION, url='', license='', description='', author='', author_email='', packages=find_packages(), include_package_data=True, entry_points={ 'mkdocs.themes': [ 'themename = theme_name', ] }, zip_safe=False ) Fill in the URL, license, description, author and author email address. The name should follow the convention mkdocs-themename (like mkdocs- bootstrap and mkdocs-bootswatch ), starting with MkDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to change is the entry_points. This is how MkDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. The directory you created at the start of this section with the main.html file should contain all of the other theme files. The minimum requirement is that it includes a main.html for the theme. It must also include a __init__.py file which should be empty, this file tells Python that the directory is a package.","title":"Package Layout"},{"location":"dev-guide/themes/#theme-configuration","text":"A packaged theme is required to include a configuration file named mkdocs_theme.yml which is placed in the root of your template files. The file should contain default configuration options for the theme. However, if the theme offers no configuration options, the file is still required and can be left blank. A theme which is not packaged does not need a mkdocs_theme.yml file as that file is not loaded from theme.custom_dir . The theme author is free to define any arbitrary options deemed necessary and those options will be made available in the templates to control behavior. For example, a theme might want to make a sidebar optional and include the following in the mkdocs_theme.yml file: show_sidebar: true Then in a template, that config option could be referenced: {% if config.theme.show_sidebar %} <div id=\"sidebar\">...</div> {% endif %} And the user could override the default in their project's mkdocs.yml config file: theme: name: themename show_sidebar: false In addition to arbitrary options defined by the theme, MkDocs defines a few special options which alters its behavior:","title":"Theme Configuration"},{"location":"dev-guide/themes/#locale","text":"This option mirrors the theme config option of the same name. If this value is not defined in the mkdocs_theme.yml file and the user does not set it in mkdocs.yml then it will default to en (English). The value is expected to match the language used in the text provided by the theme (such a \"next\" and \"previous\" links) and should be used as the value of the <html> tag's lang attribute. See Supporting theme localization/ translation for more information. Note that during configuration validation, the provided string is converted to a Locale object. The object contains Locale.language and Locale.territory attributes and will resolve as a string from within a template. Therefore, the following will work fine: <html lang=\"{ config.theme.locale }\"> If the locale was set to fr_CA (Canadian French), then the above template would render as: <html lang=\"fr_CA\"> If you did not want the territory attribute to be included, then reference the language attribute directly: <html lang=\"{ config.theme.locale.language }\"> That would render as: <html lang=\"fr\">","title":"locale"},{"location":"dev-guide/themes/#static_templates","text":"This option mirrors the theme config option of the same name and allows some defaults to be set by the theme. Note that while the user can add templates to this list, the user cannot remove templates included in the theme's config.","title":"static_templates"},{"location":"dev-guide/themes/#extends","text":"Defines a parent theme that this theme inherits from. The value should be the string name of the parent theme. Normal Jinja inheritance rules apply. Plugins may also define some options which allow the theme to inform a plugin about which set of plugin options it expects. See the documentation for any plugins you may wish to support in your theme.","title":"extends"},{"location":"dev-guide/themes/#distributing-themes","text":"With the above changes, your theme should now be ready to install. This can be done with pip, using pip install . if you are still in the same directory as the setup.py. Most Python packages, including MkDocs, are distributed on PyPI. To do this, you should run the following command. python setup.py register If you don't have an account setup, you should be prompted to create one. For a much more detailed guide, see the official Python packaging documentation for Packaging and Distributing Projects .","title":"Distributing Themes"},{"location":"dev-guide/themes/#supporting-theme-localizationtranslation","text":"While the built-in themes provide support for localization/translation of templates, custom themes and third-party themes may choose not to. Regardless, the locale setting of the theme configuration option is always present and is relied upon by other parts of the system. Therefore, it is recommended that all third-party themes use the same setting for designating a language regardless of the system they use for translation. In that way, users will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the same commands utilized by MkDocs.","title":"Supporting theme Localization/Translation"},{"location":"dev-guide/themes/#enabling-the-localizationtranslation-commands","text":"MkDocs includes some helper commands which are light wrappers around pybabel's commands . To use the commands on your own theme, add the following to your theme's setup.py script: from mkdocs.commands.setup import babel_cmdclass setup( ... cmdclass=babel_cmdclass ) Note that cmdclass=babel_cmdclass was added an a parameter passed to the setup function. Warning As pybabel is not installed by default and most users will not have pybabel installed, theme developers and/or translators should make sure to have installed the necessary dependencies (using pip install mkdocs[i18n] ) in order for the commands to be available for use.","title":"Enabling the Localization/Translation commands"},{"location":"dev-guide/themes/#using-the-localizationtranslation-commands","text":"Since the translation commands are embedded in the setup.py script of your custom theme they should be called from the root of your theme's working tree as follows: python setup.py <command_name> [OPTIONS] Each command provides a detailed list of options available with the -h/--help option. For an overview of the workflow used by MkDocs to translate the built-in themes, see the appropriate section of the Contributing Guide and the Translation Guide . Default values for many of the options to the commands can be defined in a setup.cfg file. Create a section using the command name as the section name, and the long option name as the key. See MkDocs' own setup.cfg file for an example. A summary of changes/additions to the behavior and options of the upstream pybabel commands are summarized below.","title":"Using the Localization/Translation commands"},{"location":"dev-guide/themes/#compile_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value of the -d/--directory option. The --directory option is set to {theme_dir}/locales . If a directory is passed to the --directory option, then the theme option is ignored.","title":"compile_catalog"},{"location":"dev-guide/themes/#extract_messages","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the --input-dirs and --output-file options. The --input-dirs option is set to the theme directory and --output-file is set to {theme_dir}/{domain}.pot . If a path is provided to either option, then the theme option is ignored for that option. The --domain option has been added to this command and can be used to override the domain used for the output-file based on the theme . Defaults to messages . The -F/--mapping-file option defaults to the mapping file used by MkDocs' built-in themes. However, if that mapping file does not meet your theme's needs to can override it by providing your own and passing the path of that file into the option.","title":"extract_messages"},{"location":"dev-guide/themes/#init_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option.","title":"init_catalog"},{"location":"dev-guide/themes/#update_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option.","title":"update_catalog"},{"location":"dev-guide/themes/#example-custom-theme-localizationtranslation-workflow","text":"Note If your theme inherits from an existing theme which already provides translation catalogs, your theme's translations will be merged with the parent theme's translations during a MkDocs build. This means that you only need to concentrate on the added translations. Yet, you will still benefit from the translations of the parent theme. At the same time, you may override any of parent theme's translations! Let's suppose that you're working on your own fork of the mkdocs-basic-theme and want to add translations to it. You would first modify the setup.py like this: --- a/setup.py +++ b/setup.py @@ -1,4 +1,5 @@ from setuptools import setup, find_packages +from mkdocs.commands.setup import babel_cmdclass VERSION = '1.1' @@ -18,5 +19,6 @@ setup( 'basictheme = basic_theme', ] }, - zip_safe=False + zip_safe=False, + cmdclass=babel_cmdclass ) Next, you would edit the templates by wrapping text in your HTML sources with {% trans %} and {% endtrans %} as follows: --- a/basic_theme/base.html +++ b/basic_theme/base.html @@ -88,7 +88,7 @@ <body> - <h1>This is an example theme for MkDocs.</h1> + <h1>{% trans %}This is an example theme for MkDocs.{% endtrans %}</h1> <p> It is designed to be read by looking at the theme HTML which is heavily Then you would follow the Translation Guide as usual to get your translations running.","title":"Example custom theme Localization/Translation workflow"},{"location":"dev-guide/themes/#packaging-translations-with-your-theme","text":"While the Portable Object Template ( pot ) file created by the extract_messages command and the Portable Object ( po ) files created by the init_catalog and update_catalog commands are useful for creating and editing translations, they are not used by MkDocs directly and do not need to be included in a packaged release of a theme. When MkDocs builds a site with translations, it only makes use of the binary mo files(s) for the specified locale. Therefore, when packaging a theme , you would need to make the following addition to your MANIFEST.in file: recursive-include theme_name *.mo Then, before building your Python package, you will want to ensure that the binary mo file for each locale is up-to-date by running the compile_catalog command for each locale. MkDocs expects the binary mo files to be located at locales/<locale>/LC_MESSAGES/messages.mo , which the compile_catalog command automatically does for you. See Testing theme translations for details. Note As outlined in our Translation Guide , the MkDocs project has chosen to include the pot and po files in our code repository, but not the mo files. This requires us to always run compile_catalog before packaging a new release regardless of whether any changes were made to a translation or not. However, you may chose an alternate workflow for your theme. At a minimum, you need to ensure that up-to-date mo files are included at the correct location in each release. However, you may use a different process for generating those mo files if you chose to do so.","title":"Packaging Translations with your theme"},{"location":"dev-guide/translations/","text":"Translations \uf0c1 Theme localization guide. The built-in themes that are included with MkDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the Contributing Guide . To enable a specific translation see the documentation about the specific theme you are using in the User Guide . For translations of third-party themes, please see the documentation for those themes. For a third-party theme to make use of MkDocs' translation tools and methods, that theme must be properly configured to make use of those tools. Note Translations only apply to text contained within a theme's template, such as \"next\" and \"previous\" links. The Markdown content of a page is not translated. If you wish to create multilingual documentation, you need to combine theme localization with a third-party internationalization/localization plugin. Localization tooling prerequisites \uf0c1 Theme localization makes use of the babel project for generation and compilation of localization files. Custom commands are available from the MkDocs' setup.py script as described below to assist with the process of updating and contributing translations. You will need to be working from the git working tree on your local machine to make use of the helper scripts. See the Contributing Guide for direction on how to Install for Development and Submit a Pull Request . The instructions in this document assume that you are working from a properly configured development environment. Make sure translation requirements are installed in your environment: pip install mkdocs[i18n] Adding language translations to themes \uf0c1 If your favorite language locale is not yet supported on one (or both) of the built-in themes ( mkdocs and readthedocs ), you can easily contribute a translation by following the steps below. Here is a quick summary of what you'll need to do: Initialize new localization catalogs for your language (if a translation for your locale already exists, follow the instructions for updating theme localization files instead). Add a translation for every text placeholder in the localized catalogs. Locally serve and test the translated themes for your language. Update the documentation about supported translations for each translated theme. Contribute your translation through a Pull Request. Note Translation locales are usually identified using the ISO-639-1 (2-letter) language codes. While territory/region/county codes are also supported, location specific translations should only be added after the general language translation has been completed and the regional dialect requires use of a term which differs from the general language translation. Initializing the localization catalogs \uf0c1 The templates for each theme contain text placeholders that have been extracted into a Portable Object Template ( messages.pot ) file, which is present in each theme's folder. Initializing a catalog consists of running a command which will create a directory structure for your desired language and prepare a Portable Object ( messages.po ) file derived from the pot file of the theme. Use the init_catalog command on each theme ( -t <theme> ) and provide the appropriate language code ( -l <language> ). For example, to add a translation for the Spanish es language to the mkdocs theme, run the following command: python setup.py init_catalog -t mkdocs -l es The above command will create the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u2514\u2500\u2500 messages.po You can now move on to the next step and add a translation for every text placeholder in the localized catalog. Updating a theme translation \uf0c1 If a theme's messages.pot template file has been updated since the messages.po was last updated for your locale, follow the steps below to update the theme's messages.po file: Update the theme's translation catalog to refresh the translatable text placeholders of each theme. Translate the newly added translatable text placeholders on every messages.po catalog file language you can. Locally serve and test the translated themes for your language. Contribute your translation through a Pull Request. Updating the translation catalogs \uf0c1 This step should be completed after a theme template have been updated for each language that you are comfortable contributing a translation for. To update the fr translation catalog of the mkdocs theme, use the following command: python setup.py update_catalog -t mkdocs -l fr You can now move on to the next step and add a translation for every updated text placeholder in the localized catalog. Translating the MkDocs themes \uf0c1 Now that your localized messages.po files are ready, all you need to do is add a translation in each msgstr item for each msgid item in the file. msgid \"Next\" msgstr \"Siguiente\" Warning Do not modify the msgid as it is common to all translations. Just add its translation in the msgstr item. Once you have finished translating all of the terms listed in the po file, you'll want to test your localized theme . Testing theme translations \uf0c1 To test a theme with translations, you need to first compile the messages.po files of your theme into messages.mo files. The following command will compile the es translation for the mkdocs theme. python setup.py compile_catalog -t mkdocs -l es The above command results in the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u251c\u2500\u2500 messages.mo \u2502 \u2514\u2500\u2500 messages.po Note that the compiled messages.mo file was generated based on the messages.po file that you just edited. Then modify the mkdocs.yml file at the root of the project to test the new and/or updated locale: theme: name: mkdocs locale: es Finally, run mkdocs serve to check out your new localized version of the theme. Note The build and release process takes care of compiling and distributing all locales to end users so you only have to worry about contributing the actual text translation messages.po files (the rest is ignored by git). After you have finished testing your work, be sure to undo the change to the locale setting in the mkdocs.yml file before submitting your changes. Updating theme documentation \uf0c1 Update the lists of supported translations for each translated theme located at Choosing your theme ( docs/user-guide/choosing-your-theme.md ), in their locale options. Contributing translations \uf0c1 It is now time for you to contribute your nice work to the project. Thank you!","title":"Translations"},{"location":"dev-guide/translations/#translations","text":"Theme localization guide. The built-in themes that are included with MkDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the Contributing Guide . To enable a specific translation see the documentation about the specific theme you are using in the User Guide . For translations of third-party themes, please see the documentation for those themes. For a third-party theme to make use of MkDocs' translation tools and methods, that theme must be properly configured to make use of those tools. Note Translations only apply to text contained within a theme's template, such as \"next\" and \"previous\" links. The Markdown content of a page is not translated. If you wish to create multilingual documentation, you need to combine theme localization with a third-party internationalization/localization plugin.","title":"Translations"},{"location":"dev-guide/translations/#localization-tooling-prerequisites","text":"Theme localization makes use of the babel project for generation and compilation of localization files. Custom commands are available from the MkDocs' setup.py script as described below to assist with the process of updating and contributing translations. You will need to be working from the git working tree on your local machine to make use of the helper scripts. See the Contributing Guide for direction on how to Install for Development and Submit a Pull Request . The instructions in this document assume that you are working from a properly configured development environment. Make sure translation requirements are installed in your environment: pip install mkdocs[i18n]","title":"Localization tooling prerequisites"},{"location":"dev-guide/translations/#adding-language-translations-to-themes","text":"If your favorite language locale is not yet supported on one (or both) of the built-in themes ( mkdocs and readthedocs ), you can easily contribute a translation by following the steps below. Here is a quick summary of what you'll need to do: Initialize new localization catalogs for your language (if a translation for your locale already exists, follow the instructions for updating theme localization files instead). Add a translation for every text placeholder in the localized catalogs. Locally serve and test the translated themes for your language. Update the documentation about supported translations for each translated theme. Contribute your translation through a Pull Request. Note Translation locales are usually identified using the ISO-639-1 (2-letter) language codes. While territory/region/county codes are also supported, location specific translations should only be added after the general language translation has been completed and the regional dialect requires use of a term which differs from the general language translation.","title":"Adding language translations to themes"},{"location":"dev-guide/translations/#initializing-the-localization-catalogs","text":"The templates for each theme contain text placeholders that have been extracted into a Portable Object Template ( messages.pot ) file, which is present in each theme's folder. Initializing a catalog consists of running a command which will create a directory structure for your desired language and prepare a Portable Object ( messages.po ) file derived from the pot file of the theme. Use the init_catalog command on each theme ( -t <theme> ) and provide the appropriate language code ( -l <language> ). For example, to add a translation for the Spanish es language to the mkdocs theme, run the following command: python setup.py init_catalog -t mkdocs -l es The above command will create the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u2514\u2500\u2500 messages.po You can now move on to the next step and add a translation for every text placeholder in the localized catalog.","title":"Initializing the localization catalogs"},{"location":"dev-guide/translations/#updating-a-theme-translation","text":"If a theme's messages.pot template file has been updated since the messages.po was last updated for your locale, follow the steps below to update the theme's messages.po file: Update the theme's translation catalog to refresh the translatable text placeholders of each theme. Translate the newly added translatable text placeholders on every messages.po catalog file language you can. Locally serve and test the translated themes for your language. Contribute your translation through a Pull Request.","title":"Updating a theme translation"},{"location":"dev-guide/translations/#updating-the-translation-catalogs","text":"This step should be completed after a theme template have been updated for each language that you are comfortable contributing a translation for. To update the fr translation catalog of the mkdocs theme, use the following command: python setup.py update_catalog -t mkdocs -l fr You can now move on to the next step and add a translation for every updated text placeholder in the localized catalog.","title":"Updating the translation catalogs"},{"location":"dev-guide/translations/#translating-the-mkdocs-themes","text":"Now that your localized messages.po files are ready, all you need to do is add a translation in each msgstr item for each msgid item in the file. msgid \"Next\" msgstr \"Siguiente\" Warning Do not modify the msgid as it is common to all translations. Just add its translation in the msgstr item. Once you have finished translating all of the terms listed in the po file, you'll want to test your localized theme .","title":"Translating the MkDocs themes"},{"location":"dev-guide/translations/#testing-theme-translations","text":"To test a theme with translations, you need to first compile the messages.po files of your theme into messages.mo files. The following command will compile the es translation for the mkdocs theme. python setup.py compile_catalog -t mkdocs -l es The above command results in the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u251c\u2500\u2500 messages.mo \u2502 \u2514\u2500\u2500 messages.po Note that the compiled messages.mo file was generated based on the messages.po file that you just edited. Then modify the mkdocs.yml file at the root of the project to test the new and/or updated locale: theme: name: mkdocs locale: es Finally, run mkdocs serve to check out your new localized version of the theme. Note The build and release process takes care of compiling and distributing all locales to end users so you only have to worry about contributing the actual text translation messages.po files (the rest is ignored by git). After you have finished testing your work, be sure to undo the change to the locale setting in the mkdocs.yml file before submitting your changes.","title":"Testing theme translations"},{"location":"dev-guide/translations/#updating-theme-documentation","text":"Update the lists of supported translations for each translated theme located at Choosing your theme ( docs/user-guide/choosing-your-theme.md ), in their locale options.","title":"Updating theme documentation"},{"location":"dev-guide/translations/#contributing-translations","text":"It is now time for you to contribute your nice work to the project. Thank you!","title":"Contributing translations"},{"location":"user-guide/","text":"User Guide \uf0c1 Building Documentation with MkDocs The MkDocs Developer Guide provides documentation for users of MkDocs. See Getting Started for an introductory tutorial. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Installation Writing Your Docs Choosing Your Theme Customizing Your Theme Configuration Deploying Your Docs","title":"Overview"},{"location":"user-guide/#user-guide","text":"Building Documentation with MkDocs The MkDocs Developer Guide provides documentation for users of MkDocs. See Getting Started for an introductory tutorial. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Installation Writing Your Docs Choosing Your Theme Customizing Your Theme Configuration Deploying Your Docs","title":"User Guide"},{"location":"user-guide/choosing-your-theme/","text":"Choosing your Theme \uf0c1 Selecting and configuring a theme. MkDocs includes two built-in themes ( mkdocs and readthedocs ), as documented below. However, many third party themes are available to choose from as well. To choose a theme, set the theme configuration option in your mkdocs.yml config file. theme: name: readthedocs mkdocs \uf0c1 The default theme, which was built as a custom Bootstrap theme, supports most every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides 79 different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: github . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: mkdocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: mkdocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the site. shortcuts : Defines keyboard shortcut keys. theme: name: mkdocs shortcuts: help: 191 # ? next: 78 # n previous: 80 # p search: 83 # s All values must be numeric key codes. It is best to use keys which are available on all keyboards. You may use https://keycode.info/ to determine the key code for a given key. help : Display a help modal which lists the keyboard shortcuts. Default: 191 (?) next : Navigate to the \"next\" page. Default: 78 (n) previous : Navigate to the \"previous\" page. Default: 80 (p) search : Display the search modal. Default: 83 (s) navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 2 . nav_style : This adjusts the visual style for the top navigation bar; by default, this is set to primary (the default), but it can also be set to dark or light . theme: name: mkdocs nav_style: dark locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish See the guide on localizing your theme for more information. readthedocs \uf0c1 A clone of the default theme used by the Read the Docs service, which offers the same restricted feature-set as its parent theme. Like its parent theme, only two levels of navigation are supported. In addition to the default theme configuration options , the readthedocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: readthedocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: readthedocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the include_homepage_in_sidebar : Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the nav configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: True . prev_next_buttons_location : One of bottom , top , both , or none . Displays the \u201cNext\u201d and \u201cPrevious\u201d buttons accordingly. Default: bottom . navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 4 . collapse_navigation : Only include the page section headers in the sidebar for the current page. Default: True . titles_only : Only include page titles in the sidebar, excluding all section headers for all pages. Default: False . sticky_navigation : If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: True . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish See the guide on localizing your theme for more information. Third Party Themes \uf0c1 A list of third party themes can be found in the MkDocs community wiki . If you have created your own, please feel free to add it to the list.","title":"Choosing Your Theme"},{"location":"user-guide/choosing-your-theme/#choosing-your-theme","text":"Selecting and configuring a theme. MkDocs includes two built-in themes ( mkdocs and readthedocs ), as documented below. However, many third party themes are available to choose from as well. To choose a theme, set the theme configuration option in your mkdocs.yml config file. theme: name: readthedocs","title":"Choosing your Theme"},{"location":"user-guide/choosing-your-theme/#mkdocs","text":"The default theme, which was built as a custom Bootstrap theme, supports most every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides 79 different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: github . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: mkdocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: mkdocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the site. shortcuts : Defines keyboard shortcut keys. theme: name: mkdocs shortcuts: help: 191 # ? next: 78 # n previous: 80 # p search: 83 # s All values must be numeric key codes. It is best to use keys which are available on all keyboards. You may use https://keycode.info/ to determine the key code for a given key. help : Display a help modal which lists the keyboard shortcuts. Default: 191 (?) next : Navigate to the \"next\" page. Default: 78 (n) previous : Navigate to the \"previous\" page. Default: 80 (p) search : Display the search modal. Default: 83 (s) navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 2 . nav_style : This adjusts the visual style for the top navigation bar; by default, this is set to primary (the default), but it can also be set to dark or light . theme: name: mkdocs nav_style: dark locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish See the guide on localizing your theme for more information.","title":"mkdocs"},{"location":"user-guide/choosing-your-theme/#readthedocs","text":"A clone of the default theme used by the Read the Docs service, which offers the same restricted feature-set as its parent theme. Like its parent theme, only two levels of navigation are supported. In addition to the default theme configuration options , the readthedocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: readthedocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: readthedocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the include_homepage_in_sidebar : Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the nav configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: True . prev_next_buttons_location : One of bottom , top , both , or none . Displays the \u201cNext\u201d and \u201cPrevious\u201d buttons accordingly. Default: bottom . navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 4 . collapse_navigation : Only include the page section headers in the sidebar for the current page. Default: True . titles_only : Only include page titles in the sidebar, excluding all section headers for all pages. Default: False . sticky_navigation : If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: True . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish See the guide on localizing your theme for more information.","title":"readthedocs"},{"location":"user-guide/choosing-your-theme/#third-party-themes","text":"A list of third party themes can be found in the MkDocs community wiki . If you have created your own, please feel free to add it to the list.","title":"Third Party Themes"},{"location":"user-guide/configuration/","text":"Configuration \uf0c1 Guide to all available configuration settings. Introduction \uf0c1 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 and site_url settings. All other settings are optional. Project information \uf0c1 site_name \uf0c1 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 \uf0c1 Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting ( https://example.com/foo/ ). This setting is also used for mkdocs serve : the server will be mounted onto a path taken from the path component of the URL, e.g. some/page.md will be served from http://127.0.0.1:8000/foo/some/page/ to mimick the expected remote layout. default : null repo_url \uf0c1 When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page. repo_url: https://github.com/example/repository/ default : null repo_name \uf0c1 When set, provides the name for the link to your repository on each page. default : 'GitHub' , 'Bitbucket' or 'GitLab' if the repo_url matches those domains, otherwise the hostname from the repo_url . edit_uri \uf0c1 The path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself. MkDocs concatenates repo_url and edit_uri , and appends the input path of the page. When set, and if your theme supports it, provides a link directly to the page in your source repository. This makes it easier to find and edit the source for the page. If repo_url is not set, this option is ignored. On some themes, setting this option may cause an edit link to be used in place of a repository link. Other themes may show both links. The edit_uri supports query ('?') and fragment ('#') characters. For repository hosts that use a query or a fragment to access the files, the edit_uri might be set as follows. (Note the ? and # in the URI...) # Query string example edit_uri: '?query=root/path/docs/' # Hash fragment example edit_uri: '#root/path/docs/' For other repository hosts, simply specify the relative path to the docs directory. # Query string example edit_uri: root/path/docs/ Note On a few known hosts (specifically GitHub, Bitbucket and GitLab), the edit_uri is derived from the 'repo_url' and does not need to be set manually. Simply defining a repo_url will automatically populate the edit_uri configs setting. For example, for a GitHub- or GitLab-hosted repository, the edit_uri would be automatically set as edit/master/docs/ (Note the edit path and master branch). For a Bitbucket-hosted repository, the equivalent edit_uri would be automatically set as src/default/docs/ (note the src path and default branch). To use a different URI than the default (for example a different branch), simply set the edit_uri to your desired string. If you do not want any \"edit URL link\" displayed on your pages, then set edit_uri to an empty string to disable the automatic setting. Warning On GitHub and GitLab, the default \"edit\" path ( edit/master/docs/ ) opens the page in the online editor. This functionality requires that the user have and be logged in to a GitHub/GitLab account. Otherwise, the user will be redirected to a login/signup page. Alternatively, use the \"blob\" path ( blob/master/docs/ ) to open a read-only view, which supports anonymous access. default : edit/master/docs/ for GitHub and GitLab repos or src/default/docs/ for a Bitbucket repo, if repo_url matches those domains, otherwise null site_description \uf0c1 Set the site description. This will add a meta tag to the generated HTML header. default : null site_author \uf0c1 Set the name of the author. This will add a meta tag to the generated HTML header. default : null copyright \uf0c1 Set the copyright information to be included in the documentation by the theme. default : null remote_branch \uf0c1 Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : gh-pages remote_name \uf0c1 Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : origin Documentation layout \uf0c1 nav \uf0c1 This setting is used to determine the format and layout of the global navigation for the site. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths must be relative to the mkdocs.yml configuration file. See the section on configuring pages and navigation for a more detailed breakdown, including how to create sub-sections. Navigation items may also include links to external sites. While titles are optional for internal links, they are required for external links. An external link may be a full URL or a relative URL. Any path which is not found in the files is assumed to be an external link. See the section about [Meta-Data] on how MkDocs determines the page title of a document. nav: - Introduction: 'index.md' - 'about.md' - 'Issue Tracker': 'https://example.com/' In the above example, the first two items point to local files while the third points to an external site. However, sometimes the MkDocs site is hosted in a subdirectory of a project's site and you may want to link to other parts of the same site without including the full domain. In that case, you may use an appropriate relative URL. site_url: https://example.com/foo/ nav: - Home: '../' - 'User Guide': 'user-guide.md' - 'Bug Tracker': '/bugs/' In the above example, two different styles of external links are used. First, note that the site_url indicates that the MkDocs site is hosted in the /foo/ subdirectory of the domain. Therefore, the Home navigation item is a relative link that steps up one level to the server root and effectively points to https://example.com/ . The Bug Tracker item uses an absolute path from the server root and effectively points to https://example.com/bugs/ . Of course, the User Guide points to a local MkDocs page. default : By default nav will contain an alphanumerically sorted, nested list of all the Markdown files found within the docs_dir and its sub-directories. Index files will always be listed first within a sub-section. Build directories \uf0c1 theme \uf0c1 Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs. If a string, it must be the string name of a known installed theme. For a list of available themes visit Choosing Your Theme . An example set of key/value pairs might look something like this: theme: name: mkdocs locale: en custom_dir: my_theme_customizations/ static_templates: - sitemap.html include_sidebar: false If a set of key/value pairs, the following nested keys can be defined: name: \uf0c1 The string name of a known installed theme. For a list of available themes visit Choosing Your Theme . locale: \uf0c1 A code representing the language of your site. See Localizing your theme for details. custom_dir: \uf0c1 A directory containing 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 from the root of your local file system. See Customizing Your Theme for details if you would like to tweak an existing theme. See the Theme Developer Guide if you would like to build your own theme from the ground up. static_templates: \uf0c1 A list of templates to render as static pages. The templates must be located in either the theme's template directory or in the custom_dir defined in the theme configuration. (theme specific keywords) \uf0c1 Any additional keywords supported by the theme can also be defined. See the documentation for the theme you are using for details. default : 'mkdocs' docs_dir \uf0c1 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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'docs' site_dir \uf0c1 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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'site' Note: If you are using source code control you will normally want to ensure that your build output files are not committed into the repository, and only keep the source files under version control. For example, if using git you might add the following line to your .gitignore file: site/ If you're using another source code control tool, you'll want to check its documentation on how to ignore specific directories. extra_css \uf0c1 Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir . extra_css: - css/extra.css - css/second_extra.css default : [] (an empty list). extra_javascript \uf0c1 Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage. default : [] (an empty list). extra_templates \uf0c1 Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage. default : [] (an empty list). extra \uf0c1 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. For example, if you are using a theme that supports displaying the project version, you can pass it to the theme like this: extra: version: 1.0 default : By default extra will be an empty key-value mapping. Preview controls \uf0c1 use_directory_urls \uf0c1 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 . Source file use_directory_urls: true use_directory_urls: false index.md / /index.html api-guide.md /api-guide/ /api-guide.html about/license.md /about/license/ /about/license.html 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 be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it creates links that point directly to the target file rather than the target directory . default : true strict \uf0c1 Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing. default : false dev_addr \uf0c1 Determines the address used when running mkdocs serve . Must be of the format IP:PORT . Allows a custom default to be set without the need to pass it through the --dev-addr option every time the mkdocs serve command is called. default : '127.0.0.1:8000' See also: site_url . Formatting options \uf0c1 markdown_extensions \uf0c1 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 separated by a colon. If you would like to define multiple options for a single extension, each option must be defined on a separate 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 In the above examples, each extension is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for extensions for which no options are defined. Therefore, the last example above could also be defined as follows: markdown_extensions: smarty: {} toc: permalink: True sane_lists: {} This alternative syntax is required if you intend to override some options via inheritance . See Also: The Python-Markdown documentation provides a list of extensions which are available out-of-the-box. For a list of configuration options available for a given extension, see the documentation for that extension. You may also install and use various third party extensions . Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list). plugins \uf0c1 A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. If the plugins config setting is defined in the mkdocs.yml config file, then any defaults (such as search ) are ignored and you need to explicitly re-enable the defaults if you would like to continue using them: plugins: - search - your_other_plugin To define options for a given plugin, use a nested set of key/value pairs: plugins: - search - your_other_plugin: option1: value option2: other value In the above examples, each plugin is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for plugins for which no options are defined. Therefore, the last example above could also be defined as follows: plugins: search: {} your_other_plugin: option1: value option2: other value This alternative syntax is required if you intend to override some options via inheritance . To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] default : ['search'] (the \"search\" plugin included with MkDocs). Search \uf0c1 A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin: separator \uf0c1 A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen ( - ) are used. To add the dot ( . ) as a word separator you might do this: plugins: - search: separator: '[\\s\\-\\.]+' default : '[\\s\\-]+' min_search_length \uf0c1 An integer value that defines the minimum length for a search query. By default searches shorter than 3 chars in length are ignored as search result quality with short search terms are poor. However, for some use cases (such as documentation about Message Queues which might generate searches for 'MQ') it may be preferable to set a shorter limit. plugins: - search: min_search_length: 2 default : 3 lang \uf0c1 A list of languages to use when building the search index as identified by their ISO 639-1 language codes. With Lunr Languages , the following languages are supported: ar : Arabic da : Danish nl : Dutch en : English fi : Finnish fr : French de : German hu : Hungarian it : Italian ja : Japanese no : Norwegian pt : Portuguese ro : Romanian ru : Russian es : Spanish sv : Swedish th : Thai tr : Turkish vi : Vietnamese You may contribute additional languages . Warning While search does support using multiple languages together, it is best not to add additional languages unless you really need them. Each additional language adds significant bandwidth requirements and uses more browser resources. Generally, it is best to keep each instance of MkDocs to a single language. Note Lunr Languages does not currently include support for Chinese or other Asian languages. However, some users have reported decent results using Japanese. default : The value of theme.locale if set, otherwise [en] . prebuild_index \uf0c1 Optionally generates a pre-built index of all pages, which provides some performance improvements for larger sites. Before enabling, confirm that the theme you are using explicitly supports using a prebuilt index (the builtin themes do). Set to true to enable. Warning This option requires that Node.js be installed and the command node be on the system path. If the call to node fails for any reason, a warning is issued and the build continues uninterupted. You may use the --strict flag when building to cause such a failure to raise an error instead. Note On smaller sites, using a pre-built index is not recommended as it creates a significant increase is bandwidth requirements with little to no noticeable improvement to your users. However, for larger sites (hundreds of pages), the bandwidth increase is relatively small and your users will notice a significant improvement in search performance. default : False indexing \uf0c1 Configures what strategy the search indexer will use when building the index for your pages. This property is particularly useful if your project is large in scale, and the index takes up an enormous amount of disk space. plugins: - search: indexing: 'full' Options \uf0c1 Option Description full Indexes the title, section headings, and full text of each page. sections Indexes the title and section headings of each page. titles Indexes only the title of each page. default : full Environment Variables \uf0c1 In most cases, the value of a configuration option is set directly in the configuration file. However, as an option, the value of a configuration option may be set to the value of an environment variable using the !ENV tag. For example, to set the value of the site_name option to the value of the variable SITE_NAME the YAML file may contain the following: site_name: !ENV SITE_NAME If the environment variable is not defined, then the configuration setting would be assigned a null (or None in Python) value. A default value can be defined as the last value in a list. Like this: site_name: !ENV [SITE_NAME, 'My default site name'] Multiple fallback variables can be used as well. Note that the last value is not an environment variable, but must be a value to use as a default if none of the specified environment variables are defined. site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] Simple types defined within an environment variable such as string, bool, integer, float, datestamp and null are parsed as if they were defined directly in the YAML file, which means that the value will be converted to the appropriate type. However, complex types such as lists and key/value pairs cannot be defined within a single environment variable. For more details, see the pyyaml_env_tag project. Configuration Inheritance \uf0c1 Generally, a single file would hold the entire configuration for a site. However, some organizations may maintain multiple sites which all share a common configuration across them. Rather than maintaining separate configurations for each, the common configuration options can be defined in a parent configuration while which each site's primary configuration file inherits. To define the parent for a configuration file, set the INHERIT (all caps) key to the path of the parent file. The path must be relative to the location of the primary file. For configuration options to be merged with a parent configuration, those options must be defined as key/value pairs. Specifically, the markdown_extensions and plugins options must use the alternative syntax which does not use list items (lines which start with - ). For example, suppose the common (parent) configuration is defined in base.yml : theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Then, for the \"foo\" site, the primary configuration file would be defined at foo/mkdocs.yml : INHERIT: ../base.yml site_name: Foo Project site_url: https://example.com/foo When running mkdocs build , the file at foo/mkdocs.yml would be passed in as the configuration file. MkDocs will then parse that file, retrieve and parse the parent file base.yml and deep merge the two. This would result in MkDocs receiving the following merged configuration: site_name: Foo Project site_url: https://example.com/foo theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Deep merging allows you to add and/or override various values in your primary configuration file. For example, suppose for one site you wanted to add support for definition lists, use a different symbol for permalinks, and define a different separator. In that site's primary configuration file you could do: INHERIT: ../base.yml site_name: Bar Project site_url: https://example.com/bar markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" In that case, the above configuration would be deep merged with base.yml and result in the following configuration: site_name: Bar Project site_url: https://example.com/bar theme: name: mkdocs locale: en highlightjs: true markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" admonition: {} Notice that the admonition extension was retained from the parent configuration, the def_list extension was added, the value of toc.permalink was replaced, and the value of toc.separator was added. You can replace or merge the value of any key. However, any non-key is always replaced. Therefore, you cannot append items to a list. You must redefine the entire list. As the nav configuration is made up of nested lists, this means that you cannot merge navigation items. Of course, you can replace the entire nav configuration with a new one. However, it is generally expected that the entire navigation would be defined in the primary configuration file for a project. Warning As a reminder, all path based configuration options must be relative to the primary configuration file and MkDocs does not alter the paths when merging. Therefore, defining paths in a parent file which is inherited by multiple different sites may not work as expected. It is generally best to define path based options in the primary configuration file only.","title":"Configuration"},{"location":"user-guide/configuration/#configuration","text":"Guide to all available configuration settings.","title":"Configuration"},{"location":"user-guide/configuration/#introduction","text":"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 and site_url settings. All other settings are optional.","title":"Introduction"},{"location":"user-guide/configuration/#project-information","text":"","title":"Project information"},{"location":"user-guide/configuration/#site_name","text":"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.","title":"site_name"},{"location":"user-guide/configuration/#site_url","text":"Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting ( https://example.com/foo/ ). This setting is also used for mkdocs serve : the server will be mounted onto a path taken from the path component of the URL, e.g. some/page.md will be served from http://127.0.0.1:8000/foo/some/page/ to mimick the expected remote layout. default : null","title":"site_url"},{"location":"user-guide/configuration/#repo_url","text":"When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page. repo_url: https://github.com/example/repository/ default : null","title":"repo_url"},{"location":"user-guide/configuration/#repo_name","text":"When set, provides the name for the link to your repository on each page. default : 'GitHub' , 'Bitbucket' or 'GitLab' if the repo_url matches those domains, otherwise the hostname from the repo_url .","title":"repo_name"},{"location":"user-guide/configuration/#edit_uri","text":"The path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself. MkDocs concatenates repo_url and edit_uri , and appends the input path of the page. When set, and if your theme supports it, provides a link directly to the page in your source repository. This makes it easier to find and edit the source for the page. If repo_url is not set, this option is ignored. On some themes, setting this option may cause an edit link to be used in place of a repository link. Other themes may show both links. The edit_uri supports query ('?') and fragment ('#') characters. For repository hosts that use a query or a fragment to access the files, the edit_uri might be set as follows. (Note the ? and # in the URI...) # Query string example edit_uri: '?query=root/path/docs/' # Hash fragment example edit_uri: '#root/path/docs/' For other repository hosts, simply specify the relative path to the docs directory. # Query string example edit_uri: root/path/docs/ Note On a few known hosts (specifically GitHub, Bitbucket and GitLab), the edit_uri is derived from the 'repo_url' and does not need to be set manually. Simply defining a repo_url will automatically populate the edit_uri configs setting. For example, for a GitHub- or GitLab-hosted repository, the edit_uri would be automatically set as edit/master/docs/ (Note the edit path and master branch). For a Bitbucket-hosted repository, the equivalent edit_uri would be automatically set as src/default/docs/ (note the src path and default branch). To use a different URI than the default (for example a different branch), simply set the edit_uri to your desired string. If you do not want any \"edit URL link\" displayed on your pages, then set edit_uri to an empty string to disable the automatic setting. Warning On GitHub and GitLab, the default \"edit\" path ( edit/master/docs/ ) opens the page in the online editor. This functionality requires that the user have and be logged in to a GitHub/GitLab account. Otherwise, the user will be redirected to a login/signup page. Alternatively, use the \"blob\" path ( blob/master/docs/ ) to open a read-only view, which supports anonymous access. default : edit/master/docs/ for GitHub and GitLab repos or src/default/docs/ for a Bitbucket repo, if repo_url matches those domains, otherwise null","title":"edit_uri"},{"location":"user-guide/configuration/#site_description","text":"Set the site description. This will add a meta tag to the generated HTML header. default : null","title":"site_description"},{"location":"user-guide/configuration/#site_author","text":"Set the name of the author. This will add a meta tag to the generated HTML header. default : null","title":"site_author"},{"location":"user-guide/configuration/#copyright","text":"Set the copyright information to be included in the documentation by the theme. default : null","title":"copyright"},{"location":"user-guide/configuration/#remote_branch","text":"Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : gh-pages","title":"remote_branch"},{"location":"user-guide/configuration/#remote_name","text":"Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : origin","title":"remote_name"},{"location":"user-guide/configuration/#documentation-layout","text":"","title":"Documentation layout"},{"location":"user-guide/configuration/#nav","text":"This setting is used to determine the format and layout of the global navigation for the site. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths must be relative to the mkdocs.yml configuration file. See the section on configuring pages and navigation for a more detailed breakdown, including how to create sub-sections. Navigation items may also include links to external sites. While titles are optional for internal links, they are required for external links. An external link may be a full URL or a relative URL. Any path which is not found in the files is assumed to be an external link. See the section about [Meta-Data] on how MkDocs determines the page title of a document. nav: - Introduction: 'index.md' - 'about.md' - 'Issue Tracker': 'https://example.com/' In the above example, the first two items point to local files while the third points to an external site. However, sometimes the MkDocs site is hosted in a subdirectory of a project's site and you may want to link to other parts of the same site without including the full domain. In that case, you may use an appropriate relative URL. site_url: https://example.com/foo/ nav: - Home: '../' - 'User Guide': 'user-guide.md' - 'Bug Tracker': '/bugs/' In the above example, two different styles of external links are used. First, note that the site_url indicates that the MkDocs site is hosted in the /foo/ subdirectory of the domain. Therefore, the Home navigation item is a relative link that steps up one level to the server root and effectively points to https://example.com/ . The Bug Tracker item uses an absolute path from the server root and effectively points to https://example.com/bugs/ . Of course, the User Guide points to a local MkDocs page. default : By default nav will contain an alphanumerically sorted, nested list of all the Markdown files found within the docs_dir and its sub-directories. Index files will always be listed first within a sub-section.","title":"nav"},{"location":"user-guide/configuration/#build-directories","text":"","title":"Build directories"},{"location":"user-guide/configuration/#theme","text":"Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs. If a string, it must be the string name of a known installed theme. For a list of available themes visit Choosing Your Theme . An example set of key/value pairs might look something like this: theme: name: mkdocs locale: en custom_dir: my_theme_customizations/ static_templates: - sitemap.html include_sidebar: false If a set of key/value pairs, the following nested keys can be defined:","title":"theme"},{"location":"user-guide/configuration/#name","text":"The string name of a known installed theme. For a list of available themes visit Choosing Your Theme .","title":"name:"},{"location":"user-guide/configuration/#locale","text":"A code representing the language of your site. See Localizing your theme for details.","title":"locale:"},{"location":"user-guide/configuration/#custom_dir","text":"A directory containing 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 from the root of your local file system. See Customizing Your Theme for details if you would like to tweak an existing theme. See the Theme Developer Guide if you would like to build your own theme from the ground up.","title":"custom_dir:"},{"location":"user-guide/configuration/#static_templates","text":"A list of templates to render as static pages. The templates must be located in either the theme's template directory or in the custom_dir defined in the theme configuration.","title":"static_templates:"},{"location":"user-guide/configuration/#theme-specific-keywords","text":"Any additional keywords supported by the theme can also be defined. See the documentation for the theme you are using for details. default : 'mkdocs'","title":"(theme specific keywords)"},{"location":"user-guide/configuration/#docs_dir","text":"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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'docs'","title":"docs_dir"},{"location":"user-guide/configuration/#site_dir","text":"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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'site' Note: If you are using source code control you will normally want to ensure that your build output files are not committed into the repository, and only keep the source files under version control. For example, if using git you might add the following line to your .gitignore file: site/ If you're using another source code control tool, you'll want to check its documentation on how to ignore specific directories.","title":"site_dir"},{"location":"user-guide/configuration/#extra_css","text":"Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir . extra_css: - css/extra.css - css/second_extra.css default : [] (an empty list).","title":"extra_css"},{"location":"user-guide/configuration/#extra_javascript","text":"Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage. default : [] (an empty list).","title":"extra_javascript"},{"location":"user-guide/configuration/#extra_templates","text":"Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage. default : [] (an empty list).","title":"extra_templates"},{"location":"user-guide/configuration/#extra","text":"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. For example, if you are using a theme that supports displaying the project version, you can pass it to the theme like this: extra: version: 1.0 default : By default extra will be an empty key-value mapping.","title":"extra"},{"location":"user-guide/configuration/#preview-controls","text":"","title":"Preview controls"},{"location":"user-guide/configuration/#use_directory_urls","text":"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 . Source file use_directory_urls: true use_directory_urls: false index.md / /index.html api-guide.md /api-guide/ /api-guide.html about/license.md /about/license/ /about/license.html 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 be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it creates links that point directly to the target file rather than the target directory . default : true","title":"use_directory_urls"},{"location":"user-guide/configuration/#strict","text":"Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing. default : false","title":"strict"},{"location":"user-guide/configuration/#dev_addr","text":"Determines the address used when running mkdocs serve . Must be of the format IP:PORT . Allows a custom default to be set without the need to pass it through the --dev-addr option every time the mkdocs serve command is called. default : '127.0.0.1:8000' See also: site_url .","title":"dev_addr"},{"location":"user-guide/configuration/#formatting-options","text":"","title":"Formatting options"},{"location":"user-guide/configuration/#markdown_extensions","text":"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 separated by a colon. If you would like to define multiple options for a single extension, each option must be defined on a separate 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 In the above examples, each extension is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for extensions for which no options are defined. Therefore, the last example above could also be defined as follows: markdown_extensions: smarty: {} toc: permalink: True sane_lists: {} This alternative syntax is required if you intend to override some options via inheritance . See Also: The Python-Markdown documentation provides a list of extensions which are available out-of-the-box. For a list of configuration options available for a given extension, see the documentation for that extension. You may also install and use various third party extensions . Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list).","title":"markdown_extensions"},{"location":"user-guide/configuration/#plugins","text":"A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. If the plugins config setting is defined in the mkdocs.yml config file, then any defaults (such as search ) are ignored and you need to explicitly re-enable the defaults if you would like to continue using them: plugins: - search - your_other_plugin To define options for a given plugin, use a nested set of key/value pairs: plugins: - search - your_other_plugin: option1: value option2: other value In the above examples, each plugin is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for plugins for which no options are defined. Therefore, the last example above could also be defined as follows: plugins: search: {} your_other_plugin: option1: value option2: other value This alternative syntax is required if you intend to override some options via inheritance . To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] default : ['search'] (the \"search\" plugin included with MkDocs).","title":"plugins"},{"location":"user-guide/configuration/#search","text":"A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin:","title":"Search"},{"location":"user-guide/configuration/#separator","text":"A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen ( - ) are used. To add the dot ( . ) as a word separator you might do this: plugins: - search: separator: '[\\s\\-\\.]+' default : '[\\s\\-]+'","title":"separator"},{"location":"user-guide/configuration/#min_search_length","text":"An integer value that defines the minimum length for a search query. By default searches shorter than 3 chars in length are ignored as search result quality with short search terms are poor. However, for some use cases (such as documentation about Message Queues which might generate searches for 'MQ') it may be preferable to set a shorter limit. plugins: - search: min_search_length: 2 default : 3","title":"min_search_length"},{"location":"user-guide/configuration/#lang","text":"A list of languages to use when building the search index as identified by their ISO 639-1 language codes. With Lunr Languages , the following languages are supported: ar : Arabic da : Danish nl : Dutch en : English fi : Finnish fr : French de : German hu : Hungarian it : Italian ja : Japanese no : Norwegian pt : Portuguese ro : Romanian ru : Russian es : Spanish sv : Swedish th : Thai tr : Turkish vi : Vietnamese You may contribute additional languages . Warning While search does support using multiple languages together, it is best not to add additional languages unless you really need them. Each additional language adds significant bandwidth requirements and uses more browser resources. Generally, it is best to keep each instance of MkDocs to a single language. Note Lunr Languages does not currently include support for Chinese or other Asian languages. However, some users have reported decent results using Japanese. default : The value of theme.locale if set, otherwise [en] .","title":"lang"},{"location":"user-guide/configuration/#prebuild_index","text":"Optionally generates a pre-built index of all pages, which provides some performance improvements for larger sites. Before enabling, confirm that the theme you are using explicitly supports using a prebuilt index (the builtin themes do). Set to true to enable. Warning This option requires that Node.js be installed and the command node be on the system path. If the call to node fails for any reason, a warning is issued and the build continues uninterupted. You may use the --strict flag when building to cause such a failure to raise an error instead. Note On smaller sites, using a pre-built index is not recommended as it creates a significant increase is bandwidth requirements with little to no noticeable improvement to your users. However, for larger sites (hundreds of pages), the bandwidth increase is relatively small and your users will notice a significant improvement in search performance. default : False","title":"prebuild_index"},{"location":"user-guide/configuration/#indexing","text":"Configures what strategy the search indexer will use when building the index for your pages. This property is particularly useful if your project is large in scale, and the index takes up an enormous amount of disk space. plugins: - search: indexing: 'full'","title":"indexing"},{"location":"user-guide/configuration/#options","text":"Option Description full Indexes the title, section headings, and full text of each page. sections Indexes the title and section headings of each page. titles Indexes only the title of each page. default : full","title":"Options"},{"location":"user-guide/configuration/#environment-variables","text":"In most cases, the value of a configuration option is set directly in the configuration file. However, as an option, the value of a configuration option may be set to the value of an environment variable using the !ENV tag. For example, to set the value of the site_name option to the value of the variable SITE_NAME the YAML file may contain the following: site_name: !ENV SITE_NAME If the environment variable is not defined, then the configuration setting would be assigned a null (or None in Python) value. A default value can be defined as the last value in a list. Like this: site_name: !ENV [SITE_NAME, 'My default site name'] Multiple fallback variables can be used as well. Note that the last value is not an environment variable, but must be a value to use as a default if none of the specified environment variables are defined. site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] Simple types defined within an environment variable such as string, bool, integer, float, datestamp and null are parsed as if they were defined directly in the YAML file, which means that the value will be converted to the appropriate type. However, complex types such as lists and key/value pairs cannot be defined within a single environment variable. For more details, see the pyyaml_env_tag project.","title":"Environment Variables"},{"location":"user-guide/configuration/#configuration-inheritance","text":"Generally, a single file would hold the entire configuration for a site. However, some organizations may maintain multiple sites which all share a common configuration across them. Rather than maintaining separate configurations for each, the common configuration options can be defined in a parent configuration while which each site's primary configuration file inherits. To define the parent for a configuration file, set the INHERIT (all caps) key to the path of the parent file. The path must be relative to the location of the primary file. For configuration options to be merged with a parent configuration, those options must be defined as key/value pairs. Specifically, the markdown_extensions and plugins options must use the alternative syntax which does not use list items (lines which start with - ). For example, suppose the common (parent) configuration is defined in base.yml : theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Then, for the \"foo\" site, the primary configuration file would be defined at foo/mkdocs.yml : INHERIT: ../base.yml site_name: Foo Project site_url: https://example.com/foo When running mkdocs build , the file at foo/mkdocs.yml would be passed in as the configuration file. MkDocs will then parse that file, retrieve and parse the parent file base.yml and deep merge the two. This would result in MkDocs receiving the following merged configuration: site_name: Foo Project site_url: https://example.com/foo theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Deep merging allows you to add and/or override various values in your primary configuration file. For example, suppose for one site you wanted to add support for definition lists, use a different symbol for permalinks, and define a different separator. In that site's primary configuration file you could do: INHERIT: ../base.yml site_name: Bar Project site_url: https://example.com/bar markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" In that case, the above configuration would be deep merged with base.yml and result in the following configuration: site_name: Bar Project site_url: https://example.com/bar theme: name: mkdocs locale: en highlightjs: true markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" admonition: {} Notice that the admonition extension was retained from the parent configuration, the def_list extension was added, the value of toc.permalink was replaced, and the value of toc.separator was added. You can replace or merge the value of any key. However, any non-key is always replaced. Therefore, you cannot append items to a list. You must redefine the entire list. As the nav configuration is made up of nested lists, this means that you cannot merge navigation items. Of course, you can replace the entire nav configuration with a new one. However, it is generally expected that the entire navigation would be defined in the primary configuration file for a project. Warning As a reminder, all path based configuration options must be relative to the primary configuration file and MkDocs does not alter the paths when merging. Therefore, defining paths in a parent file which is inherited by multiple different sites may not work as expected. It is generally best to define path based options in the primary configuration file only.","title":"Configuration Inheritance"},{"location":"user-guide/customizing-your-theme/","text":"Customizing Your Theme \uf0c1 Altering a theme to suit your needs. If you would like to make a few tweaks to an existing theme, there is no need to create your own theme from scratch. For minor tweaks which only require some CSS and/or JavaScript, you can use the docs_dir . However, for more complex customizations, including overriding templates, you will need to use the theme custom_dir setting. Using the docs_dir \uf0c1 The extra_css and extra_javascript configuration options can be used to make tweaks and customizations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your documentation directory . For example, to change the color of the headers in your documentation, create a file called extra.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Note If you are deploying your documentation with ReadTheDocs . You will need to explicitly list the CSS and JavaScript files you want to include in your config. To do this, add the following to your mkdocs.yml. extra_css: [extra.css] After making these changes, they should be visible when you run mkdocs serve - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML document after the page content. If you desire to include a JavaScript library, you may have better success including the library by using the theme custom_dir . Using the theme custom_dir \uf0c1 The theme.custom_dir configuration option can be used to point to a directory of files which override the files in a parent theme. The parent theme would be the theme defined in the theme.name configuration option. Any file in the custom_dir with the same name as a file in the parent theme will replace the file of the same name in the parent theme. Any additional files in the custom_dir will be added to the parent theme. The contents of the custom_dir should mirror the directory structure of the parent theme. You may include templates, JavaScript files, CSS files, images, fonts, or any other media included in a theme. Note For this to work, the theme.name setting must be set to a known installed theme. If the name setting is instead set to null (or not defined), then there is no theme to override and the contents of the custom_dir must be a complete, standalone theme. See the Theme Developer Guide for more information. For example, the mkdocs theme ( browse source ), contains the following directory structure (in part): - css\\ - fonts\\ - img\\ - favicon.ico - grid.png - js\\ - 404.html - base.html - content.html - nav-sub.html - nav.html - toc.html To override any of the files contained in that theme, create a new directory next to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: theme: name: mkdocs custom_dir: custom_theme/ To override the 404 error page (\"file not found\"), add a new template file named 404.html to the custom_theme directory. For information on what can be included in a template, review the Theme Developer Guide . To override the favicon, you can add a new icon file at custom_theme/img/favicon.ico . To include a JavaScript library, copy the library to the custom_theme/js/ directory. Your directory structure should now look like this: - docs/ - index.html - custom_theme/ - img/ - favicon.ico - js/ - somelib.js - 404.html - config.yml Note Any files included in the parent theme (defined in name ) but not included in the custom_dir will still be utilized. The custom_dir will only override/replace files in the parent theme. If you want to remove files, or build a theme from scratch, then you should review the Theme Developer Guide . Overriding Template Blocks \uf0c1 The built-in themes implement many of their parts inside template blocks which can be individually overridden in the main.html template. Simply create a main.html template file in your custom_dir and define replacement blocks within that file. Just make sure that the main.html extends base.html . For example, to alter the title of the MkDocs theme, your replacement main.html template would contain the following: {% extends \"base.html\" %} {% block htmltitle %} <title>Custom title goes here</title> {% endblock %} In the above example, the htmltitle block defined in your custom main.html file will be used in place of the default htmltitle block defined in the parent theme. You may re-define as many blocks as you desire, as long as those blocks are defined in the parent. For example, you could replace the Google Analytics script with one for a different service or replace the search feature with your own. You will need to consult the parent theme you are using to determine what blocks are available to override. The MkDocs and ReadTheDocs themes provide the following blocks: site_meta : Contains meta tags in the document head. htmltitle : Contains the page title in the document head. styles : Contains the link tags for stylesheets. libs : Contains the JavaScript libraries (jQuery, etc) included in the page header. scripts : Contains JavaScript scripts which should execute after a page loads. analytics : Contains the analytics script. extrahead : An empty block in the <head> to insert custom tags/scripts/etc. site_name : Contains the site name in the navigation bar. site_nav : Contains the site navigation in the navigation bar. search_button : Contains the search box in the navigation bar. next_prev : Contains the next and previous buttons in the navigation bar. repo : Contains the repository link in the navigation bar. content : Contains the page content and table of contents for the page. footer : Contains the page footer. You may need to view the source template files to ensure your modifications will work with the structure of the site. See Template Variables for a list of variables you can use within your custom blocks. For a more complete explanation of blocks, consult the Jinja documentation . Combining the custom_dir and Template Blocks \uf0c1 Adding a JavaScript library to the custom_dir will make it available, but won't include it in the pages generated by MkDocs. Therefore, a link needs to be added to the library from the HTML. Starting the with directory structure above (truncated): - docs/ - custom_theme/ - js/ - somelib.js - config.yml A link to the custom_theme/js/somelib.js file needs to be added to the template. As somelib.js is a JavaScript library, it would logically go in the libs block. However, a new libs block that only includes the new script will replace the block defined in the parent template and any links to libraries in the parent template will be removed. To avoid breaking the template, a super block can be used with a call to super from within the block: {% extends \"base.html\" %} {% block libs %} {{ super() }} <script src=\"{{ base_url }}/js/somelib.js\"></script> {% endblock %} Note that the base_url template variable was used to ensure that the link is always relative to the current page. Now the generated pages will include links to the template provided libraries as well as the library included in the custom_dir . The same would be required for any additional CSS files included in the custom_dir .","title":"Customizing Your Theme"},{"location":"user-guide/customizing-your-theme/#customizing-your-theme","text":"Altering a theme to suit your needs. If you would like to make a few tweaks to an existing theme, there is no need to create your own theme from scratch. For minor tweaks which only require some CSS and/or JavaScript, you can use the docs_dir . However, for more complex customizations, including overriding templates, you will need to use the theme custom_dir setting.","title":"Customizing Your Theme"},{"location":"user-guide/customizing-your-theme/#using-the-docs_dir","text":"The extra_css and extra_javascript configuration options can be used to make tweaks and customizations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your documentation directory . For example, to change the color of the headers in your documentation, create a file called extra.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Note If you are deploying your documentation with ReadTheDocs . You will need to explicitly list the CSS and JavaScript files you want to include in your config. To do this, add the following to your mkdocs.yml. extra_css: [extra.css] After making these changes, they should be visible when you run mkdocs serve - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML document after the page content. If you desire to include a JavaScript library, you may have better success including the library by using the theme custom_dir .","title":"Using the docs_dir"},{"location":"user-guide/customizing-your-theme/#using-the-theme-custom_dir","text":"The theme.custom_dir configuration option can be used to point to a directory of files which override the files in a parent theme. The parent theme would be the theme defined in the theme.name configuration option. Any file in the custom_dir with the same name as a file in the parent theme will replace the file of the same name in the parent theme. Any additional files in the custom_dir will be added to the parent theme. The contents of the custom_dir should mirror the directory structure of the parent theme. You may include templates, JavaScript files, CSS files, images, fonts, or any other media included in a theme. Note For this to work, the theme.name setting must be set to a known installed theme. If the name setting is instead set to null (or not defined), then there is no theme to override and the contents of the custom_dir must be a complete, standalone theme. See the Theme Developer Guide for more information. For example, the mkdocs theme ( browse source ), contains the following directory structure (in part): - css\\ - fonts\\ - img\\ - favicon.ico - grid.png - js\\ - 404.html - base.html - content.html - nav-sub.html - nav.html - toc.html To override any of the files contained in that theme, create a new directory next to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: theme: name: mkdocs custom_dir: custom_theme/ To override the 404 error page (\"file not found\"), add a new template file named 404.html to the custom_theme directory. For information on what can be included in a template, review the Theme Developer Guide . To override the favicon, you can add a new icon file at custom_theme/img/favicon.ico . To include a JavaScript library, copy the library to the custom_theme/js/ directory. Your directory structure should now look like this: - docs/ - index.html - custom_theme/ - img/ - favicon.ico - js/ - somelib.js - 404.html - config.yml Note Any files included in the parent theme (defined in name ) but not included in the custom_dir will still be utilized. The custom_dir will only override/replace files in the parent theme. If you want to remove files, or build a theme from scratch, then you should review the Theme Developer Guide .","title":"Using the theme custom_dir"},{"location":"user-guide/customizing-your-theme/#overriding-template-blocks","text":"The built-in themes implement many of their parts inside template blocks which can be individually overridden in the main.html template. Simply create a main.html template file in your custom_dir and define replacement blocks within that file. Just make sure that the main.html extends base.html . For example, to alter the title of the MkDocs theme, your replacement main.html template would contain the following: {% extends \"base.html\" %} {% block htmltitle %} <title>Custom title goes here</title> {% endblock %} In the above example, the htmltitle block defined in your custom main.html file will be used in place of the default htmltitle block defined in the parent theme. You may re-define as many blocks as you desire, as long as those blocks are defined in the parent. For example, you could replace the Google Analytics script with one for a different service or replace the search feature with your own. You will need to consult the parent theme you are using to determine what blocks are available to override. The MkDocs and ReadTheDocs themes provide the following blocks: site_meta : Contains meta tags in the document head. htmltitle : Contains the page title in the document head. styles : Contains the link tags for stylesheets. libs : Contains the JavaScript libraries (jQuery, etc) included in the page header. scripts : Contains JavaScript scripts which should execute after a page loads. analytics : Contains the analytics script. extrahead : An empty block in the <head> to insert custom tags/scripts/etc. site_name : Contains the site name in the navigation bar. site_nav : Contains the site navigation in the navigation bar. search_button : Contains the search box in the navigation bar. next_prev : Contains the next and previous buttons in the navigation bar. repo : Contains the repository link in the navigation bar. content : Contains the page content and table of contents for the page. footer : Contains the page footer. You may need to view the source template files to ensure your modifications will work with the structure of the site. See Template Variables for a list of variables you can use within your custom blocks. For a more complete explanation of blocks, consult the Jinja documentation .","title":"Overriding Template Blocks"},{"location":"user-guide/customizing-your-theme/#combining-the-custom_dir-and-template-blocks","text":"Adding a JavaScript library to the custom_dir will make it available, but won't include it in the pages generated by MkDocs. Therefore, a link needs to be added to the library from the HTML. Starting the with directory structure above (truncated): - docs/ - custom_theme/ - js/ - somelib.js - config.yml A link to the custom_theme/js/somelib.js file needs to be added to the template. As somelib.js is a JavaScript library, it would logically go in the libs block. However, a new libs block that only includes the new script will replace the block defined in the parent template and any links to libraries in the parent template will be removed. To avoid breaking the template, a super block can be used with a call to super from within the block: {% extends \"base.html\" %} {% block libs %} {{ super() }} <script src=\"{{ base_url }}/js/somelib.js\"></script> {% endblock %} Note that the base_url template variable was used to ensure that the link is always relative to the current page. Now the generated pages will include links to the template provided libraries as well as the library included in the custom_dir . The same would be required for any additional CSS files included in the custom_dir .","title":"Combining the custom_dir and Template Blocks"},{"location":"user-guide/deploying-your-docs/","text":"Deploying your docs \uf0c1 A basic guide to deploying your docs to various hosting providers GitHub Pages \uf0c1 If you host the source code for a project on GitHub , you can easily use GitHub Pages to host the documentation for your project. There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences, which require a different work flow when deploying. Project Pages \uf0c1 Project Pages sites are simpler as the site files get deployed to a branch within the project repository ( gh-pages by default). After you checkout the primary working branch (usually master ) of the git repository where you maintain the source documentation for your project, run the following command: mkdocs gh-deploy That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command. Organization and User Pages \uf0c1 User and Organization Pages sites are not tied to a specific project, and the site files are deployed to the master branch in a dedicated repository named with the GitHub account name. Therefore, you need working copies of two repositories on our local system. For example, consider the following file structure: my-project/ mkdocs.yml docs/ orgname.github.io/ After making and verifying updates to your project you need to change directories to the orgname.github.io repository and call the mkdocs gh-deploy command from there: cd ../orgname.github.io/ mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master Note that you need to explicitly point to the mkdocs.yml configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the master branch. You may override the default with the remote_branch configuration setting, but if you forget to change directories before running the deploy script, it will commit to the master branch of your project, which you probably don't want. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command. Custom Domains \uf0c1 GitHub Pages includes support for using a Custom Domain for your site. In addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a CNAME file to the root of your docs_dir . The file must contain a single bare domain or subdomain on a single line (see MkDocs' own CNAME file as an example). You may create the file manually, or use GitHub's web interface to set up the custom domain (under Settings / Custom Domain). If you use the web interface, GitHub will create the CNAME file for you and save it to the root of your \"pages\" branch. So that the file does not get removed the next time you deploy, you need to copy the file to your docs_dir . With the file properly included in your docs_dir , MkDocs will include the file in your built site and push it to your \"pages\" branch each time you run the gh-deploy command. If you are having problems getting a custom domain to work, see GitHub's documentation on Troubleshooting custom domains . Read the Docs \uf0c1 Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository. Note To benefit from all of the features offered by Read the Docs, you will need to use the Read the Docs theme which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs. Other Providers \uf0c1 Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp , ssh or scp client to transfer the files. For example, a typical set of commands from the command line might look something like this: mkdocs build scp -r ./site user@host:/path/to/server/root Of course, you will need to replace user with the username you have with your hosting provider and host with the appropriate domain name. Additionally, you will need to adjust the /path/to/server/root to match the configuration of your hosts' file system. See your host's documentation for specifics. You will likely want to search their documentation for \"ftp\" or \"uploading site\". Local Files \uf0c1 Rather than hosting your documentation on a server, you may instead distribute the files directly, which can then be viewed in a browser using the file:// scheme. Note that, due to the security settings of all modern browsers, some things will not work the same and some features may not work at all. In fact, a few settings will need to be customized in very specific ways. site_url : The site_url must be set to an empty string, which instructs MkDocs to build your site so that it will work with the file:// scheme. site_url: \"\" use_directory_urls : Set use_directory_urls to false . Otherwise, internal links between pages will not work properly. use_directory_urls: false search : You will need to either disable the search plugin, or use a third-party search plugin which is specifically designed to work with the file:// scheme. To disable all plugins, set the plugins setting to an empty list. plugins: [] If you have other plugins enabled, simply ensure that search is not included in the list. When writing your documentation, it is imperative that all internal links use relative URLs as documented . Remember, each reader of your documentation will be using a different device and the files will likely be in a different location on that device. If you expect your documentation to be viewed off-line, you may also need to be careful about which themes you choose. Many themes make use of CDNs for various support files, which require a live Internet connection. You will need to choose a theme which includes all support files directly in the theme. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory and distribute it to your readers. Alternatively, you may choose to use a third party tool to convert the HTML files to some other documentation format. 404 Pages \uf0c1 When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.","title":"Deploying Your Docs"},{"location":"user-guide/deploying-your-docs/#deploying-your-docs","text":"A basic guide to deploying your docs to various hosting providers","title":"Deploying your docs"},{"location":"user-guide/deploying-your-docs/#github-pages","text":"If you host the source code for a project on GitHub , you can easily use GitHub Pages to host the documentation for your project. There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences, which require a different work flow when deploying.","title":"GitHub Pages"},{"location":"user-guide/deploying-your-docs/#project-pages","text":"Project Pages sites are simpler as the site files get deployed to a branch within the project repository ( gh-pages by default). After you checkout the primary working branch (usually master ) of the git repository where you maintain the source documentation for your project, run the following command: mkdocs gh-deploy That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command.","title":"Project Pages"},{"location":"user-guide/deploying-your-docs/#organization-and-user-pages","text":"User and Organization Pages sites are not tied to a specific project, and the site files are deployed to the master branch in a dedicated repository named with the GitHub account name. Therefore, you need working copies of two repositories on our local system. For example, consider the following file structure: my-project/ mkdocs.yml docs/ orgname.github.io/ After making and verifying updates to your project you need to change directories to the orgname.github.io repository and call the mkdocs gh-deploy command from there: cd ../orgname.github.io/ mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master Note that you need to explicitly point to the mkdocs.yml configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the master branch. You may override the default with the remote_branch configuration setting, but if you forget to change directories before running the deploy script, it will commit to the master branch of your project, which you probably don't want. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command.","title":"Organization and User Pages"},{"location":"user-guide/deploying-your-docs/#custom-domains","text":"GitHub Pages includes support for using a Custom Domain for your site. In addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a CNAME file to the root of your docs_dir . The file must contain a single bare domain or subdomain on a single line (see MkDocs' own CNAME file as an example). You may create the file manually, or use GitHub's web interface to set up the custom domain (under Settings / Custom Domain). If you use the web interface, GitHub will create the CNAME file for you and save it to the root of your \"pages\" branch. So that the file does not get removed the next time you deploy, you need to copy the file to your docs_dir . With the file properly included in your docs_dir , MkDocs will include the file in your built site and push it to your \"pages\" branch each time you run the gh-deploy command. If you are having problems getting a custom domain to work, see GitHub's documentation on Troubleshooting custom domains .","title":"Custom Domains"},{"location":"user-guide/deploying-your-docs/#read-the-docs","text":"Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository. Note To benefit from all of the features offered by Read the Docs, you will need to use the Read the Docs theme which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs.","title":"Read the Docs"},{"location":"user-guide/deploying-your-docs/#other-providers","text":"Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp , ssh or scp client to transfer the files. For example, a typical set of commands from the command line might look something like this: mkdocs build scp -r ./site user@host:/path/to/server/root Of course, you will need to replace user with the username you have with your hosting provider and host with the appropriate domain name. Additionally, you will need to adjust the /path/to/server/root to match the configuration of your hosts' file system. See your host's documentation for specifics. You will likely want to search their documentation for \"ftp\" or \"uploading site\".","title":"Other Providers"},{"location":"user-guide/deploying-your-docs/#local-files","text":"Rather than hosting your documentation on a server, you may instead distribute the files directly, which can then be viewed in a browser using the file:// scheme. Note that, due to the security settings of all modern browsers, some things will not work the same and some features may not work at all. In fact, a few settings will need to be customized in very specific ways. site_url : The site_url must be set to an empty string, which instructs MkDocs to build your site so that it will work with the file:// scheme. site_url: \"\" use_directory_urls : Set use_directory_urls to false . Otherwise, internal links between pages will not work properly. use_directory_urls: false search : You will need to either disable the search plugin, or use a third-party search plugin which is specifically designed to work with the file:// scheme. To disable all plugins, set the plugins setting to an empty list. plugins: [] If you have other plugins enabled, simply ensure that search is not included in the list. When writing your documentation, it is imperative that all internal links use relative URLs as documented . Remember, each reader of your documentation will be using a different device and the files will likely be in a different location on that device. If you expect your documentation to be viewed off-line, you may also need to be careful about which themes you choose. Many themes make use of CDNs for various support files, which require a live Internet connection. You will need to choose a theme which includes all support files directly in the theme. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory and distribute it to your readers. Alternatively, you may choose to use a third party tool to convert the HTML files to some other documentation format.","title":"Local Files"},{"location":"user-guide/deploying-your-docs/#404-pages","text":"When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.","title":"404 Pages"},{"location":"user-guide/installation/","text":"MkDocs Installation \uf0c1 A detailed guide. Requirements \uf0c1 MkDocs requires a recent version of Python and the the Python package manager, pip , to be installed on your system. You can check if you already have these installed from the command line: $ python --version Python 3.8.2 $ pip --version pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) If you already have those packages installed, you may skip down to Installing MkDocs . Installing Python \uf0c1 Install Python using your package manager of choice, or by downloading an installer appropriate for your system from python.org and running it. Note If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default). Installing pip \uf0c1 If you're using a recent version of Python, the Python package manager, pip , is most likely installed by default. However, you may need to upgrade pip to the lasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py . Then run the following command to install it: python get-pip.py Installing MkDocs \uf0c1 Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay. $ mkdocs --version mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) Note If you would like manpages installed for MkDocs, the click-man tool can generate and install them for you. Simply run the following two commands: pip install click-man click-man --target path/to/man/pages mkdocs See the click-man documentation for an explanation of why manpages are not automatically generated and installed by pip. Note If you are using Windows, some of the above commands may not work out-of-the-box. A quick solution may be to preface every Python command with python -m like this: python -m pip install mkdocs python -m mkdocs For a more permanent solution, you may need to edit your PATH environment variable to include the Scripts directory of your Python installation. Recent versions of Python include a script to do this for you. Navigate to your Python installation directory (for example C:\\Python38\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double clicking on it. Alternatively, you can download the script and run it ( python win_add2path.py ).","title":"Installation"},{"location":"user-guide/installation/#mkdocs-installation","text":"A detailed guide.","title":"MkDocs Installation"},{"location":"user-guide/installation/#requirements","text":"MkDocs requires a recent version of Python and the the Python package manager, pip , to be installed on your system. You can check if you already have these installed from the command line: $ python --version Python 3.8.2 $ pip --version pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) If you already have those packages installed, you may skip down to Installing MkDocs .","title":"Requirements"},{"location":"user-guide/installation/#installing-python","text":"Install Python using your package manager of choice, or by downloading an installer appropriate for your system from python.org and running it. Note If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default).","title":"Installing Python"},{"location":"user-guide/installation/#installing-pip","text":"If you're using a recent version of Python, the Python package manager, pip , is most likely installed by default. However, you may need to upgrade pip to the lasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py . Then run the following command to install it: python get-pip.py","title":"Installing pip"},{"location":"user-guide/installation/#installing-mkdocs","text":"Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay. $ mkdocs --version mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) Note If you would like manpages installed for MkDocs, the click-man tool can generate and install them for you. Simply run the following two commands: pip install click-man click-man --target path/to/man/pages mkdocs See the click-man documentation for an explanation of why manpages are not automatically generated and installed by pip. Note If you are using Windows, some of the above commands may not work out-of-the-box. A quick solution may be to preface every Python command with python -m like this: python -m pip install mkdocs python -m mkdocs For a more permanent solution, you may need to edit your PATH environment variable to include the Scripts directory of your Python installation. Recent versions of Python include a script to do this for you. Navigate to your Python installation directory (for example C:\\Python38\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double clicking on it. Alternatively, you can download the script and run it ( python win_add2path.py ).","title":"Installing MkDocs"},{"location":"user-guide/localizing-your-theme/","text":"Localizing Your Theme \uf0c1 Display your theme in your preferred language. Note Theme localization only translates the text elements of the theme itself (such as \"next\" and \"previous\" links), not the actual content of your documentation. If you wish to create multilingual documentation, you need to combine theme localization as described here with a third-party internationalization/localization plugin. Installation \uf0c1 For theme localization to work, you must use a theme which supports it and enable i18n (internationalization) support by installing mkdocs[i18n] : pip install mkdocs[i18n] Supported locales \uf0c1 In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation for your language. However, a locale may also include a territory (or region or county) code as well. The language and territory must be separated by an underscore. For example, some possible locales for English might include en , en_AU , en_GB , and en_US . For a list of locales supported by the theme you are using, see that theme's documentation. mkdocs readthedocs Warning If you configure a language locale which is not yet supported by the theme that you are using, MkDocs will fall back to the theme's default locale. Usage \uf0c1 To specify the locale that MkDocs should use, set the locale parameter of the theme configuration option to the appropriate code. For example, to build the mkdocs theme in French you would use the following in your mkdocs.yml configuration file: theme: name: mkdocs locale: fr Contributing theme translations \uf0c1 If a theme has not yet been translated into your language, feel free to contribute a translation using the Translation Guide .","title":"Localizing Your Theme"},{"location":"user-guide/localizing-your-theme/#localizing-your-theme","text":"Display your theme in your preferred language. Note Theme localization only translates the text elements of the theme itself (such as \"next\" and \"previous\" links), not the actual content of your documentation. If you wish to create multilingual documentation, you need to combine theme localization as described here with a third-party internationalization/localization plugin.","title":"Localizing Your Theme"},{"location":"user-guide/localizing-your-theme/#installation","text":"For theme localization to work, you must use a theme which supports it and enable i18n (internationalization) support by installing mkdocs[i18n] : pip install mkdocs[i18n]","title":"Installation"},{"location":"user-guide/localizing-your-theme/#supported-locales","text":"In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation for your language. However, a locale may also include a territory (or region or county) code as well. The language and territory must be separated by an underscore. For example, some possible locales for English might include en , en_AU , en_GB , and en_US . For a list of locales supported by the theme you are using, see that theme's documentation. mkdocs readthedocs Warning If you configure a language locale which is not yet supported by the theme that you are using, MkDocs will fall back to the theme's default locale.","title":"Supported locales"},{"location":"user-guide/localizing-your-theme/#usage","text":"To specify the locale that MkDocs should use, set the locale parameter of the theme configuration option to the appropriate code. For example, to build the mkdocs theme in French you would use the following in your mkdocs.yml configuration file: theme: name: mkdocs locale: fr","title":"Usage"},{"location":"user-guide/localizing-your-theme/#contributing-theme-translations","text":"If a theme has not yet been translated into your language, feel free to contribute a translation using the Translation Guide .","title":"Contributing theme translations"},{"location":"user-guide/writing-your-docs/","text":"Writing your docs \uf0c1 How to layout and write your Markdown source files. File layout \uf0c1 Your documentation source should be written as regular Markdown files (see Writing with Markdown below), and placed in the documentation directory . By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml docs/ index.md By convention your project homepage should be named index.md (see Index pages below for details). Any of the following file extensions may be used for your Markdown source files: markdown , mdown , mkdn , mkd , md . All Markdown files included in your documentation directory will be rendered in the built site regardless of any settings. Note Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md ) are ignored by MkDocs, which matches the behavior of most web servers. There is no option to override this behavior. You can also create multi-page documentation, by creating several Markdown files: mkdocs.yml docs/ index.md about.md license.md The file layout you use determines the URLs that are used for the generated pages. Given the above layout, pages would be generated for the following URLs: / /about/ /license/ You can also include your Markdown files in nested directories if that better suits your documentation layout. docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md Source files inside nested directories will cause pages to be generated with nested URLs, like so: / /user-guide/getting-started/ /user-guide/configuration-options/ /license/ Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See how to link to images and media below for details. Index pages \uf0c1 When a directory is requested, by default, most web servers will return an index file (usually named index.html ) contained within that directory if one exists. For that reason, the homepage in all of the examples above has been named index.md , which MkDocs will render to index.html when building the site. Many repository hosting sites provide special treatment for README files by displaying the contents of the README file when browsing the contents of a directory. Therefore, MkDocs will allow you to name your index pages as README.md instead of index.md . In that way, when users are browsing your source code, the repository host can display the index page of that directory as it is a README file. However, when MkDocs renders your site, the file will be renamed to index.html so that the server will serve it as a proper index file. If both an index.md file and a README.md file are found in the same directory, then the index.md file is used and the README.md file is ignored. Configure Pages and Navigation \uf0c1 The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu. If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory . An automatically created navigation configuration will always be sorted alphanumerically by file name (except that index files will always be listed first within a sub-section). You will need to manually define your navigation configuration if you would like your navigation menu sorted differently. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths in the navigation configuration must be relative to the docs_dir configuration option. If that option is set to the default value, docs , the source files for the above configuration would be located at docs/index.md and docs/about.md . The above example will result in two navigation items being created at the top level and with their titles inferred from the contents of the Markdown file or, if no title is defined within the file, of the file name. To override the title in the nav setting add a title right before the filename. nav: - Home: 'index.md' - About: 'about.md' Note that if a title is defined for a page in the navigation, that title will be used throughout the site for that page and will override any title defined within the page itself. Navigation sub-sections can be created by listing related pages together under a section title. For example: nav: - Home: 'index.md' - 'User Guide': - 'Writing your docs': 'writing-your-docs.md' - 'Styling your docs': 'styling-your-docs.md' - About: - 'License': 'license.md' - 'Release Notes': 'release-notes.md' With the above configuration we have three top level items: \"Home\", \"User Guide\" and \"About.\" \"Home\" is a link to the homepage for the site. Under the \"User Guide\" section two pages are listed: \"Writing your docs\" and \"Styling your docs.\" Under the \"About\" section two more pages are listed: \"License\" and \"Release Notes.\" Note that a section cannot have a page assigned to it. Sections are only containers for child pages and sub-sections. You may nest sections as deeply as you like. However, be careful that you don't make it too difficult for your users to navigate through the site navigation by over-complicating the nesting. While sections may mirror your directory structure, they do not have to. Any pages not listed in your navigation configuration will still be rendered and included with the built site, however, they will not be linked from the global navigation and will not be included in the previous and next links. Such pages will be \"hidden\" unless linked to directly. Writing with Markdown \uf0c1 MkDocs pages must be authored in Markdown , a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner. MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation , although there are a few very minor differences . In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions . See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions. MkDocs includes some extensions by default, which are highlighted below. Internal links \uf0c1 MkDocs allows you to interlink your documentation by using regular Markdown links . However, there are a few additional benefits to formatting those links specifically for MkDocs as outlined below. Linking to pages \uf0c1 When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to. Please see the [project license](license.md) for further details. When the MkDocs build runs, these Markdown links will automatically be transformed into an HTML hyperlink to the appropriate HTML page. Warning Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server. If the target documentation file is in another directory you'll need to make sure to include any relative directory path in the link. Please see the [project license](../about/license.md) for further details. The toc extension is used by MkDocs to generate an ID for every header in your Markdown documents. You can use that ID to link to a section within a target document by using an anchor link. The generated HTML will correctly transform the path portion of the link, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details. Note that IDs are created from the text of a header. All text is converted to lowercase and any disallowed characters, including white-space, are converted to dashes. Consecutive dashes are then reduced to a single dash. There are a few configuration settings provided by the toc extension which you can set in your mkdocs.yml configuration file to alter the default behavior: permalink : Generate permanent links at the end of each header. Default: False . When set to True the paragraph symbol (\u00b6 or &para; ) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol ( # ) instead, do: markdown_extensions: - toc: permalink: \"#\" baselevel : Base level for headers. Default: 1 . This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 ( <h2> ), do: markdown_extensions: - toc: baselevel: 2 Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header ( <h2> ) in the HTML output. separator : Word separator. Default: - . Character which replaces white-space in generated IDs. If you prefer underscores, then do: markdown_extensions: - toc: separator: \"_\" Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option. markdown_extensions: - toc: permalink: \"#\" baselevel: 2 separator: \"_\" Linking to images and media \uf0c1 As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media. For example, if your project documentation needed to include a GitHub pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows: mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png To include images in your documentation source files, simply use any of the regular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes. ![Screenshot](img/screenshot.png) *Above: Cupcake indexer in progress* Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor. Linking from raw HTML \uf0c1 Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document. Meta-Data \uf0c1 MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any. In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported: template : The template to use with the current page. By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment. title : The \"title\" to use for the document. MkDocs will attempt to determine the title of a document in the following ways, in order: A title defined in the nav configuration setting for a document. A title defined in the title meta-data key of a document. A level 1 Markdown header on the first line of the document body. Please note that Setext-style headers are not supported. The filename of a document. Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list. YAML Style Meta-Data \uf0c1 YAML style meta-data consists of YAML key/value pairs wrapped in YAML style deliminators to mark the start and/or end of the meta-data. The first line of a document must be --- . The meta-data ends at the first line containing an end deliminator (either --- or ... ). The content between the deliminators is parsed as YAML . --- title: My Document summary: A brief description of my document. authors: - Waylan Limberg - Tom Christie date: 2018-07-10 some_url: https://example.com --- This is the first paragraph of the document. YAML is able to detect data types. Therefore, in the above example, the values of title , summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document. MultiMarkdown Style Meta-Data \uf0c1 MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this: Title: My Document Summary: A brief description of my document. Authors: Waylan Limberg Tom Christie Date: January 23, 2018 blank-value: some_url: https://example.com This is the first paragraph of the document. The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string. The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. Note MkDocs does not support YAML style deliminators ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the deliminators to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Tables \uf0c1 The tables extension adds a basic table syntax to Markdown which is popular across multiple implementations. The syntax is rather simple and is generally only useful for simple tabular data. A simple table looks like this: First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell Content Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | | Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header :----------- |:-------------:| -----------: Left | Center | Right Left | Center | Right Note that table cells cannot contain any block level elements and cannot contain multiple lines of text. They can, however, include inline Markdown as defined in Markdown's syntax rules. Additionally, a table must be surrounded by blank lines. There must be a blank line before and after the table. Fenced code blocks \uf0c1 The fenced code blocks extension adds an alternate method of defining code blocks without indentation. The first line should contain 3 or more backtick ( ` ) characters, and the last line should contain the same number of backtick characters ( ` ): ``` Fenced code blocks are like Standard Markdown\u2019s regular code blocks, except that they\u2019re not indented and instead rely on start and end fence lines to delimit the code block. ``` With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used: ```python def fn(): pass ``` Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.","title":"Writing Your Docs"},{"location":"user-guide/writing-your-docs/#writing-your-docs","text":"How to layout and write your Markdown source files.","title":"Writing your docs"},{"location":"user-guide/writing-your-docs/#file-layout","text":"Your documentation source should be written as regular Markdown files (see Writing with Markdown below), and placed in the documentation directory . By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml docs/ index.md By convention your project homepage should be named index.md (see Index pages below for details). Any of the following file extensions may be used for your Markdown source files: markdown , mdown , mkdn , mkd , md . All Markdown files included in your documentation directory will be rendered in the built site regardless of any settings. Note Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md ) are ignored by MkDocs, which matches the behavior of most web servers. There is no option to override this behavior. You can also create multi-page documentation, by creating several Markdown files: mkdocs.yml docs/ index.md about.md license.md The file layout you use determines the URLs that are used for the generated pages. Given the above layout, pages would be generated for the following URLs: / /about/ /license/ You can also include your Markdown files in nested directories if that better suits your documentation layout. docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md Source files inside nested directories will cause pages to be generated with nested URLs, like so: / /user-guide/getting-started/ /user-guide/configuration-options/ /license/ Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See how to link to images and media below for details.","title":"File layout"},{"location":"user-guide/writing-your-docs/#index-pages","text":"When a directory is requested, by default, most web servers will return an index file (usually named index.html ) contained within that directory if one exists. For that reason, the homepage in all of the examples above has been named index.md , which MkDocs will render to index.html when building the site. Many repository hosting sites provide special treatment for README files by displaying the contents of the README file when browsing the contents of a directory. Therefore, MkDocs will allow you to name your index pages as README.md instead of index.md . In that way, when users are browsing your source code, the repository host can display the index page of that directory as it is a README file. However, when MkDocs renders your site, the file will be renamed to index.html so that the server will serve it as a proper index file. If both an index.md file and a README.md file are found in the same directory, then the index.md file is used and the README.md file is ignored.","title":"Index pages"},{"location":"user-guide/writing-your-docs/#configure-pages-and-navigation","text":"The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu. If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory . An automatically created navigation configuration will always be sorted alphanumerically by file name (except that index files will always be listed first within a sub-section). You will need to manually define your navigation configuration if you would like your navigation menu sorted differently. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths in the navigation configuration must be relative to the docs_dir configuration option. If that option is set to the default value, docs , the source files for the above configuration would be located at docs/index.md and docs/about.md . The above example will result in two navigation items being created at the top level and with their titles inferred from the contents of the Markdown file or, if no title is defined within the file, of the file name. To override the title in the nav setting add a title right before the filename. nav: - Home: 'index.md' - About: 'about.md' Note that if a title is defined for a page in the navigation, that title will be used throughout the site for that page and will override any title defined within the page itself. Navigation sub-sections can be created by listing related pages together under a section title. For example: nav: - Home: 'index.md' - 'User Guide': - 'Writing your docs': 'writing-your-docs.md' - 'Styling your docs': 'styling-your-docs.md' - About: - 'License': 'license.md' - 'Release Notes': 'release-notes.md' With the above configuration we have three top level items: \"Home\", \"User Guide\" and \"About.\" \"Home\" is a link to the homepage for the site. Under the \"User Guide\" section two pages are listed: \"Writing your docs\" and \"Styling your docs.\" Under the \"About\" section two more pages are listed: \"License\" and \"Release Notes.\" Note that a section cannot have a page assigned to it. Sections are only containers for child pages and sub-sections. You may nest sections as deeply as you like. However, be careful that you don't make it too difficult for your users to navigate through the site navigation by over-complicating the nesting. While sections may mirror your directory structure, they do not have to. Any pages not listed in your navigation configuration will still be rendered and included with the built site, however, they will not be linked from the global navigation and will not be included in the previous and next links. Such pages will be \"hidden\" unless linked to directly.","title":"Configure Pages and Navigation"},{"location":"user-guide/writing-your-docs/#writing-with-markdown","text":"MkDocs pages must be authored in Markdown , a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner. MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation , although there are a few very minor differences . In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions . See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions. MkDocs includes some extensions by default, which are highlighted below.","title":"Writing with Markdown"},{"location":"user-guide/writing-your-docs/#internal-links","text":"MkDocs allows you to interlink your documentation by using regular Markdown links . However, there are a few additional benefits to formatting those links specifically for MkDocs as outlined below.","title":"Internal links"},{"location":"user-guide/writing-your-docs/#linking-to-pages","text":"When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to. Please see the [project license](license.md) for further details. When the MkDocs build runs, these Markdown links will automatically be transformed into an HTML hyperlink to the appropriate HTML page. Warning Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server. If the target documentation file is in another directory you'll need to make sure to include any relative directory path in the link. Please see the [project license](../about/license.md) for further details. The toc extension is used by MkDocs to generate an ID for every header in your Markdown documents. You can use that ID to link to a section within a target document by using an anchor link. The generated HTML will correctly transform the path portion of the link, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details. Note that IDs are created from the text of a header. All text is converted to lowercase and any disallowed characters, including white-space, are converted to dashes. Consecutive dashes are then reduced to a single dash. There are a few configuration settings provided by the toc extension which you can set in your mkdocs.yml configuration file to alter the default behavior: permalink : Generate permanent links at the end of each header. Default: False . When set to True the paragraph symbol (\u00b6 or &para; ) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol ( # ) instead, do: markdown_extensions: - toc: permalink: \"#\" baselevel : Base level for headers. Default: 1 . This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 ( <h2> ), do: markdown_extensions: - toc: baselevel: 2 Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header ( <h2> ) in the HTML output. separator : Word separator. Default: - . Character which replaces white-space in generated IDs. If you prefer underscores, then do: markdown_extensions: - toc: separator: \"_\" Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option. markdown_extensions: - toc: permalink: \"#\" baselevel: 2 separator: \"_\"","title":"Linking to pages"},{"location":"user-guide/writing-your-docs/#linking-to-images-and-media","text":"As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media. For example, if your project documentation needed to include a GitHub pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows: mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png To include images in your documentation source files, simply use any of the regular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes. ![Screenshot](img/screenshot.png) *Above: Cupcake indexer in progress* Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor.","title":"Linking to images and media"},{"location":"user-guide/writing-your-docs/#linking-from-raw-html","text":"Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.","title":"Linking from raw HTML"},{"location":"user-guide/writing-your-docs/#meta-data","text":"MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any. In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported: template : The template to use with the current page. By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment. title : The \"title\" to use for the document. MkDocs will attempt to determine the title of a document in the following ways, in order: A title defined in the nav configuration setting for a document. A title defined in the title meta-data key of a document. A level 1 Markdown header on the first line of the document body. Please note that Setext-style headers are not supported. The filename of a document. Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list.","title":"Meta-Data"},{"location":"user-guide/writing-your-docs/#yaml-style-meta-data","text":"YAML style meta-data consists of YAML key/value pairs wrapped in YAML style deliminators to mark the start and/or end of the meta-data. The first line of a document must be --- . The meta-data ends at the first line containing an end deliminator (either --- or ... ). The content between the deliminators is parsed as YAML . --- title: My Document summary: A brief description of my document. authors: - Waylan Limberg - Tom Christie date: 2018-07-10 some_url: https://example.com --- This is the first paragraph of the document. YAML is able to detect data types. Therefore, in the above example, the values of title , summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document.","title":"YAML Style Meta-Data"},{"location":"user-guide/writing-your-docs/#multimarkdown-style-meta-data","text":"MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this: Title: My Document Summary: A brief description of my document. Authors: Waylan Limberg Tom Christie Date: January 23, 2018 blank-value: some_url: https://example.com This is the first paragraph of the document. The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string. The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. Note MkDocs does not support YAML style deliminators ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the deliminators to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data.","title":"MultiMarkdown Style Meta-Data"},{"location":"user-guide/writing-your-docs/#tables","text":"The tables extension adds a basic table syntax to Markdown which is popular across multiple implementations. The syntax is rather simple and is generally only useful for simple tabular data. A simple table looks like this: First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell Content Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | | Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header :----------- |:-------------:| -----------: Left | Center | Right Left | Center | Right Note that table cells cannot contain any block level elements and cannot contain multiple lines of text. They can, however, include inline Markdown as defined in Markdown's syntax rules. Additionally, a table must be surrounded by blank lines. There must be a blank line before and after the table.","title":"Tables"},{"location":"user-guide/writing-your-docs/#fenced-code-blocks","text":"The fenced code blocks extension adds an alternate method of defining code blocks without indentation. The first line should contain 3 or more backtick ( ` ) characters, and the last line should contain the same number of backtick characters ( ` ): ``` Fenced code blocks are like Standard Markdown\u2019s regular code blocks, except that they\u2019re not indented and instead rely on start and end fence lines to delimit the code block. ``` With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used: ```python def fn(): pass ``` Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.","title":"Fenced code blocks"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"MkDocs \uf0c1 Project documentation with Markdown. MkDocs is a fast , simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial , then check the User Guide for more information. Getting Started User Guide Features Great themes available There's a stack of good looking themes available for MkDocs. Choose between the built in themes: mkdocs and readthedocs , select one of the third-party themes listed on the MkDocs Themes wiki page, or build your own . Easy to customize Get your project documentation looking just the way you want it by customizing your theme and/or installing some plugins . Modify Markdown's behavior with Markdown extensions . Many configuration options are available. Preview your site as you work The built-in dev-server allows you to preview your documentation as you're writing it. It will even auto-reload and refresh your browser whenever you save your changes. Host anywhere MkDocs builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose.","title":"Home"},{"location":"#mkdocs","text":"Project documentation with Markdown. MkDocs is a fast , simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial , then check the User Guide for more information. Getting Started User Guide","title":"MkDocs"},{"location":"getting-started/","text":"Getting Started with MkDocs \uf0c1 An introductory tutorial! Installation \uf0c1 To install MkDocs, run the following command from the command line: pip install mkdocs For more details, see the Installation Guide . Creating a new project \uf0c1 Getting started is super easy. To create a new project, run the following command from the command line: mkdocs new my-project cd my-project Take a moment to review the initial project that has been created for you. There's a single configuration file named mkdocs.yml , and a folder named docs that will contain your documentation source files ( docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command: $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes. Open the docs/index.md document in your text editor of choice, change the initial heading to MkLorum , and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum site_url: https://example.com/ Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name and site_url configuration options are the only two required options in your configuration file. When you create a new project, the site_url option is assigned the placeholder value: https://example.com . If the final location is known, you can change the setting now to point to it. Or you may choose to leave it alone for now. Just be sure to edit it before you deploy your site to a production server. Adding pages \uf0c1 Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a nav setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md Save your changes and you'll now see a navigation bar with Home and About items on the left as well as Search , Previous , and Next items on the right. Try the menu items and navigate back and forth between pages. Then click on Search . A search dialog will appear, allowing you to search for any text on any page. Notice that the search results include every occurrence of the search term on the site and links directly to the section of the page in which the search term appears. You get all of that with no effort or configuration on your part! Theming our documentation \uf0c1 Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md theme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used. Changing the Favicon Icon \uf0c1 By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create an img subdirectory in the docs directory and copy your custom favicon.ico file to that directory. MkDocs will automatically detect and use that file as your favicon icon. Building the site \uf0c1 That's looking good. You're ready to deploy the first pass of your MkLorum documentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the directory: $ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml Notice that your source documentation has been output as two HTML files named index.html and about/index.html . You also have various other media that's been copied into the site directory as part of the documentation theme. You even have a sitemap.xml file and mkdocs/search_index.json . If you're using source code control such as git you probably don't want to check your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo \"site/\" >> .gitignore If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories. Other Commands and Options \uf0c1 There are various other commands and options available. For a complete list of commands, use the --help flag: mkdocs --help To view a list of options available on a given command, use the --help flag with that command. For example, to get a list of all options available for the build command run the following: mkdocs build --help Deploying \uf0c1 The documentation site that you just built only uses static files so you'll be able to host it from pretty much anywhere. Simply upload the contents of the entire site directory to wherever you're hosting your website from and you're done. For specific instructions on a number of common hosts, see the Deploying your Docs page. Getting help \uf0c1 See the User Guide for more complete documentation of all of MkDocs' features. To get help with MkDocs, please use the GitHub discussions or GitHub issues .","title":"Getting Started"},{"location":"getting-started/#getting-started-with-mkdocs","text":"An introductory tutorial!","title":"Getting Started with MkDocs"},{"location":"getting-started/#installation","text":"To install MkDocs, run the following command from the command line: pip install mkdocs For more details, see the Installation Guide .","title":"Installation"},{"location":"getting-started/#creating-a-new-project","text":"Getting started is super easy. To create a new project, run the following command from the command line: mkdocs new my-project cd my-project Take a moment to review the initial project that has been created for you. There's a single configuration file named mkdocs.yml , and a folder named docs that will contain your documentation source files ( docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command: $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes. Open the docs/index.md document in your text editor of choice, change the initial heading to MkLorum , and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum site_url: https://example.com/ Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name and site_url configuration options are the only two required options in your configuration file. When you create a new project, the site_url option is assigned the placeholder value: https://example.com . If the final location is known, you can change the setting now to point to it. Or you may choose to leave it alone for now. Just be sure to edit it before you deploy your site to a production server.","title":"Creating a new project"},{"location":"getting-started/#adding-pages","text":"Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a nav setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md Save your changes and you'll now see a navigation bar with Home and About items on the left as well as Search , Previous , and Next items on the right. Try the menu items and navigate back and forth between pages. Then click on Search . A search dialog will appear, allowing you to search for any text on any page. Notice that the search results include every occurrence of the search term on the site and links directly to the section of the page in which the search term appears. You get all of that with no effort or configuration on your part!","title":"Adding pages"},{"location":"getting-started/#theming-our-documentation","text":"Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum site_url: https://example.com/ nav: - Home: index.md - About: about.md theme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used.","title":"Theming our documentation"},{"location":"getting-started/#changing-the-favicon-icon","text":"By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create an img subdirectory in the docs directory and copy your custom favicon.ico file to that directory. MkDocs will automatically detect and use that file as your favicon icon.","title":"Changing the Favicon Icon"},{"location":"getting-started/#building-the-site","text":"That's looking good. You're ready to deploy the first pass of your MkLorum documentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the directory: $ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml Notice that your source documentation has been output as two HTML files named index.html and about/index.html . You also have various other media that's been copied into the site directory as part of the documentation theme. You even have a sitemap.xml file and mkdocs/search_index.json . If you're using source code control such as git you probably don't want to check your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo \"site/\" >> .gitignore If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories.","title":"Building the site"},{"location":"getting-started/#other-commands-and-options","text":"There are various other commands and options available. For a complete list of commands, use the --help flag: mkdocs --help To view a list of options available on a given command, use the --help flag with that command. For example, to get a list of all options available for the build command run the following: mkdocs build --help","title":"Other Commands and Options"},{"location":"getting-started/#deploying","text":"The documentation site that you just built only uses static files so you'll be able to host it from pretty much anywhere. Simply upload the contents of the entire site directory to wherever you're hosting your website from and you're done. For specific instructions on a number of common hosts, see the Deploying your Docs page.","title":"Deploying"},{"location":"getting-started/#getting-help","text":"See the User Guide for more complete documentation of all of MkDocs' features. To get help with MkDocs, please use the GitHub discussions or GitHub issues .","title":"Getting help"},{"location":"about/contributing/","text":"Contributing to MkDocs \uf0c1 An introduction to contributing to the MkDocs project. The MkDocs project welcomes, and depends, on contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: Code patches via pull requests Documentation improvements Bug reports and patch reviews For information about available communication channels please refer to the README file in our GitHub repository. Code of Conduct \uf0c1 Everyone interacting in the MkDocs project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct . Reporting an Issue \uf0c1 Please include as much detail as you can. Let us know your platform and MkDocs version. If the problem is visual (for example a theme or design issue) please add a screenshot and if you get an error please include the full error and traceback. Testing the Development Version \uf0c1 If you want to just install and try out the latest development version of MkDocs you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is strongly recommended that you do this within a virtualenv . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz Installing for Development \uf0c1 First you'll need to fork and clone the repository. Once you have a local copy, run the following command. It is strongly recommended that you do this within a virtualenv . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command to the git repository. Running the tests \uf0c1 To run the tests, it is recommended that you use tox . Install Tox using pip by running the command pip install tox . Then the test suite can be run for MkDocs by running the command tox in the root of your MkDocs repository. It will attempt to run the tests against all of the Python versions we support. So don't be concerned if you are missing some and they fail. The rest will be verified by Github Actions when you submit a pull request. Translating themes \uf0c1 To localize a theme to your favorite language, follow the guide on Translating Themes . We welcome translation Pull Requests! Submitting Pull Requests \uf0c1 If you're considering a large code contribution to MkDocs, please prefer to open an issue first to get early feedback on the idea. Once you think the code is ready to be reviewed, push it to your fork and send a pull request. For a change to be accepted it will most likely need to have tests and documentation if it is a new feature. Submitting changes to the builtin themes \uf0c1 When installed with i18n support ( pip install mkdocs[i18n] ), MkDocs allows themes to support being translated into various languages (referred to as locales) if they respect Jinja's i18n extension by wrapping text placeholders with {% trans %} and {% endtrans %} tags. Each time a translatable text placeholder is added, removed or changed in a theme template, the theme's Portable Object Template ( pot ) file needs to be updated by running the extract_messages command. For example, to update the pot file of the mkdocs theme, run the following command: python setup.py extract_messages -t mkdocs The updated pot file should be included in a PR with the updated template. The updated pot file will allow translation contributors to propose the translations needed for their preferred language. See the guide on Translating Themes for details. Note Contributors are not expected to provide translations with their changes to a theme's templates. However, they are expected to include an updated pot file so that everything is ready for translators to do their job.","title":"Contributing"},{"location":"about/contributing/#contributing-to-mkdocs","text":"An introduction to contributing to the MkDocs project. The MkDocs project welcomes, and depends, on contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: Code patches via pull requests Documentation improvements Bug reports and patch reviews For information about available communication channels please refer to the README file in our GitHub repository.","title":"Contributing to MkDocs"},{"location":"about/contributing/#code-of-conduct","text":"Everyone interacting in the MkDocs project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct .","title":"Code of Conduct"},{"location":"about/contributing/#reporting-an-issue","text":"Please include as much detail as you can. Let us know your platform and MkDocs version. If the problem is visual (for example a theme or design issue) please add a screenshot and if you get an error please include the full error and traceback.","title":"Reporting an Issue"},{"location":"about/contributing/#testing-the-development-version","text":"If you want to just install and try out the latest development version of MkDocs you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is strongly recommended that you do this within a virtualenv . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz","title":"Testing the Development Version"},{"location":"about/contributing/#installing-for-development","text":"First you'll need to fork and clone the repository. Once you have a local copy, run the following command. It is strongly recommended that you do this within a virtualenv . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command to the git repository.","title":"Installing for Development"},{"location":"about/contributing/#running-the-tests","text":"To run the tests, it is recommended that you use tox . Install Tox using pip by running the command pip install tox . Then the test suite can be run for MkDocs by running the command tox in the root of your MkDocs repository. It will attempt to run the tests against all of the Python versions we support. So don't be concerned if you are missing some and they fail. The rest will be verified by Github Actions when you submit a pull request.","title":"Running the tests"},{"location":"about/contributing/#translating-themes","text":"To localize a theme to your favorite language, follow the guide on Translating Themes . We welcome translation Pull Requests!","title":"Translating themes"},{"location":"about/contributing/#submitting-pull-requests","text":"If you're considering a large code contribution to MkDocs, please prefer to open an issue first to get early feedback on the idea. Once you think the code is ready to be reviewed, push it to your fork and send a pull request. For a change to be accepted it will most likely need to have tests and documentation if it is a new feature.","title":"Submitting Pull Requests"},{"location":"about/contributing/#submitting-changes-to-the-builtin-themes","text":"When installed with i18n support ( pip install mkdocs[i18n] ), MkDocs allows themes to support being translated into various languages (referred to as locales) if they respect Jinja's i18n extension by wrapping text placeholders with {% trans %} and {% endtrans %} tags. Each time a translatable text placeholder is added, removed or changed in a theme template, the theme's Portable Object Template ( pot ) file needs to be updated by running the extract_messages command. For example, to update the pot file of the mkdocs theme, run the following command: python setup.py extract_messages -t mkdocs The updated pot file should be included in a PR with the updated template. The updated pot file will allow translation contributors to propose the translations needed for their preferred language. See the guide on Translating Themes for details. Note Contributors are not expected to provide translations with their changes to a theme's templates. However, they are expected to include an updated pot file so that everything is ready for translators to do their job.","title":"Submitting changes to the builtin themes"},{"location":"about/license/","text":"License \uf0c1 The legal stuff. Included projects \uf0c1 Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects. MkDocs License (BSD) \uf0c1 Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"License"},{"location":"about/license/#license","text":"The legal stuff.","title":"License"},{"location":"about/license/#included-projects","text":"Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects.","title":"Included projects"},{"location":"about/license/#mkdocs-license-bsd","text":"Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"MkDocs License (BSD)"},{"location":"about/release-notes/","text":"Release Notes \uf0c1 Upgrading \uf0c1 To upgrade MkDocs to the latest version, use pip: pip install -U mkdocs You can determine your currently installed version using mkdocs --version : $ mkdocs --version mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6) Maintenance team \uf0c1 The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan Version 1.2.3 (2021-10-12) \uf0c1 Built-in themes now also support these languages: Simplified Chinese ( #2497 ) Japanese ( #2525 ) Brazilian Portuguese ( #2535 ) Spanish ( #2545 , previously #2396 ) Third-party plugins will take precedence over built-in plugins with the same name ( #2591 ) Bugfix: Fix ability to load translations for some languages: core support ( #2565 ) and search plugin support with fallbacks ( #2602 ) Bugfix (regression in 1.2): Prevent directory traversal in the dev server ( #2604 ) Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a build failure in strict mode ( #2607 ) Bugfix: Correctly print colorful messages in the terminal on Windows ( #2606 ) Bugfix: Python version 3.10 was displayed incorrectly in --version ( #2618 ) Other small improvements; see commit log . Version 1.2.2 (2021-07-18) \uf0c1 Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters ( #2464 ) Bugfix (regression in 1.2): Revert livereload file watching to use polling observer ( #2477 ) This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts. This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage. Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls ( #2490 ) Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server ( #2507 ) Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before. Bugfix: Fix gh_deploy with config-file in the current directory ( #2481 ) Bugfix: Fix reversed breadcrumbs in \"readthedocs\" theme ( #2179 ) Allow \"mkdocs.yaml\" as the file name when '--config' is not passed ( #2478 ) Stop treating \";\" as a special character in URLs: urlparse -> urlsplit ( #2502 ) Improve build performance for sites with many pages (partly already done in 1.2) ( #2407 ) Version 1.2.1 (2021-06-09) \uf0c1 Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes. Version 1.2 (2021-06-04) \uf0c1 Major Additions to Version 1.2 \uf0c1 Support added for Theme Localization ( #2299 ) \uf0c1 The mkdocs and readthedocs themes now support language localization using the theme.locale parameter, which defaults to en (English). The only other supported languages in this release are fr (French) and es (Spanish). For details on using the provided translations, see the user guide . Note that translation will not happen by default. Users must first install the necessary dependencies with the following command: pip install mkdocs[i18n] Translation contributions are welcome and detailed in the Translation Guide . Developers of third party themes may want to review the relevant section of the Theme Development Guide . Contributors who are updating the templates to the built-in themes should review the Contributing Guide . The lang setting of the search plugin now defaults to the language specified in theme.locale . Support added for Environment Variables in the configuration file ( #1954 ) \uf0c1 Environments variables may now be specified in the configuration file with the !ENV tag. The value of the variable will be parsed by the YAML parser and converted to the appropriate type. somekey: !ENV VAR_NAME otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value'] See Environment Variables in the Configuration documentation for details. Support added for Configuration Inheritance ( #2218 ) \uf0c1 A configuration file may now inherit from a parent configuration file. In the primary file set the INHERIT key to the relative path of the parent file. INHERIT: path/to/base.yml The two files will then be deep merged. See Configuration Inheritance for details. Update gh-deploy command ( #2170 ) \uf0c1 The vendored (and modified) copy of ghp_import has been replaced with a dependency on the upstream library. As of version 1.0.0, ghp-import includes a Python API which makes it possible to call directly. MkDocs can now benefit from recent bug fixes and new features, including the following: A .nojekyll file is automatically included when deploying to GitHub Pages. The --shell flag is now available, which reportedly works better on Windows. Git author and committer environment variables should be respected ( #1383 ). Rework auto-reload and HTTP server for mkdocs serve ( #2385 ) \uf0c1 mkdocs serve now uses a new underlying server + file watcher implementation, based on http.server from standard library and watchdog . It provides similar functionality to the previously used livereload library (which is now dropped from dependencies, along with tornado ). This makes reloads more responsive and consistent in terms of timing. Multiple rapid file changes no longer cause the site to repeatedly rebuild (issue #2061 ). Almost every aspect of the server is slightly different, but actual visible changes are minor. The logging outputs are only similar to the old ones. Degradations in behavior are not expected, and should be reported if found. Offset the local site root according to the sub-path of the site_url ( #2424 ) \uf0c1 When using mkdocs serve and having the site_url specified as e.g. http://example.org/sub/path/ , now the root of the locally served site becomes http://127.0.0.1:8000/sub/path/ and all document paths are offset accordingly. A build_error event was added ( #2103 ) \uf0c1 Plugin developers can now use the on_build_error hook to execute code when an exception is raised while building the site. See on_build_error in the Plugins documentation for details. Three new exceptions: BuildError PluginError and Abort ( #2103 ) \uf0c1 MkDocs now has tree new exceptions defined in mkdocs.exceptions : BuildError , PluginError , and Abort : PluginError can be raised from a plugin to stop the build and log an error message without traceback . BuildError should not be used by third-party plugins developers and is reserved for internal use only. Abort is used internally to abort the build and display an error without a traceback. See Handling errors in the Plugins documentation for details. Search Indexing Strategy configuration \uf0c1 Users can now specify which strategy they wish to use when indexing their site for search. A user can select between the following options: full : Adds page title, section headings, and full page text to the search index. sections : Adds page titles and section headings only to the search index. titles : Adds only the page titles to the search index. See Search Indexing in the configuration documentation for details. Backward Incompatible Changes in 1.2 \uf0c1 The site_url configuration option is now required . If it is not set, a warning will be issued. In a future release an error will be raised ( #2189 ). The use_directory_urls configuration option will be forced to false if site_url is set to an empty string. In that case, if use_directory_urls is not explicitly set to false , a warning will be issued ( #2189 ). Note This was reverted in release 1.2.2 The google_analytics configuration option is deprecated as Google appears to be fazing it out in favor of its new Google Analytics 4 property. See the documentation for your theme for alternatives which can be configured as part of your theme configuration. For example, the mkdocs and readthedocs themes have each added a new theme.analytics.gtag configuration option which uses the new Google Analytics 4 property. See Google's documentation on how to Upgrade to a Google Analytics 4 property . Then set theme.analytics.gtag to the \"G-\" ID and delete the google_analytics configuration option which contains a \"UA-\" ID. So long as the old \"UA-\" ID and new \"G-\" ID are properly linked in your Google account, and you are using the \"G-\" ID, the data will be made available in both the old and new formats by Google Analytics. See #2252 . A theme's files are now excluded from the list of watched files by default when using the --livereload server. This new default behavior is what most users need and provides better performance when editing site content. Theme developers can enable the old behavior with the --watch-theme option. ( #2092 ). The mkdocs theme now removes the sidebar when printing a page. This frees up horizontal space for better rendering of content like tables ( #2193 ). The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema() , which ensures that each instance of the configuration is unique ( #2289 ). The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e.: mkdocs.plugins.pluginname ). The on_serve event (which receives the server object and the builder function) is affected by the server rewrite. server is now a mkdocs.livereload.LiveReloadServer instead of livereload.server.Server . The typical action that plugins can do with these is to call server.watch(some_dir, builder) , which basically adds that directory to watched directories, causing the site to be rebuilt on file changes. That still works, but passing any other function to watch is deprecated and shows a warning. This 2nd parameter is already optional, and will accept only this exact builder function just for compatibility. The python method of the plugins.search.prebuild_index configuration option is pending deprecation as of version 1.2. It is expected that in version 1.3 it will raise a warning if used and in version 1.4 it will raise an error. Users are encouraged to use an alternate method to generate a prebuilt index for search. The lunr and lunr[languages] dependencies are no longer installed by default. The dependencies are only needed for the rare user who pre-builds the search index and uses the python option, which is now pending deprecation. If you use this feature, then you will need to manually install lunr and lunr[languages] . A warning is issued if the dependencies are needed but not installed. Other Changes and Additions to Version 1.2 \uf0c1 Bugfix: Properly process navigation child items in _get_by_type when filtering for sections ( #2203 ). Official support for Python 3.9 has been added and support for Python 3.5 has been dropped. Bugfix: Fixes an issue that would result in a partially cut-off navigation item in the ReadTheDocs theme ( #2297 ). Structure Files object now has a remove method to help plugin developers manipulate the Files tree. The corresponding src_paths has become a property to accommodate this possible dynamic behavior. See #2305 . Updated highlight.js to 10.5.0. See #2313 . Bugfix: Search plugin now works with Japanese language. See #2178 . Documentation has been refactored ( #1629 ). Restore styling of tables in the readthedocs theme ( #2028 ). Ensure site_url ends with a slash ( #1785 ). Correct documentation of pages template context variable ( #1736 ). The lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding 2.3.9 version ( #2306 ). Color is now used in log messages to identify errors, warnings and debug messages. Bugfix: Identify homepage when use_directory_urls is False ( #2362 ). Version 1.1.2 (2020-05-14) \uf0c1 Bugfix: Normalize IP addresses and change unsupported address error to a warning ( #2108 ). Version 1.1.1 (2020-05-12) \uf0c1 Bugfix: Allow compressed sitemap to be deterministic by supporting the SOURCE_DATE_EPOCH environment variable ( #2100 ). Bugfix: Use README.md as index.html even if use_directory_urls is false ( #2081 ). Bugfix: Ignore links which start with a backslash ( #1680 ). Bugfix: Pass builder to the on_serve event so that it can be passed to server.watch by plugins ( #1952 ). Bugfix: Use lunr[languages]==0.5.8 to avoid nltk incompatibilities ( #2062 ). Bugfix: Ensure wheel is Python 3 only ( #2021 ). Bugfix: Clean up dev_addr validation and disallow 0.0.0.0 ( #2022 ). Add support for min_search_length parameter for search plugin ( #2014 ). Bugfix: readthedocs theme code colors ( #2027 ). Version 1.1 (2020-02-22) \uf0c1 Major Additions to Version 1.1 \uf0c1 Support for Lunr.py as prebuild_index engine \uf0c1 Mkdocs now supports pre-building indices using Lunr.py , a pure Python implementation of Lunr.js, allowing the user to avoid installing a NodeJS environment if so desired. For more information please read the prebuild_index documentation . readthedocs theme updated with upstream ( #588 and #1374 ) \uf0c1 The readthedocs theme now more closely matches the upstream Sphinx theme (version 0.4.1). A number of new theme configuration settings were added which mirror the upstream configuration options. See the theme documentation for details. Update mkdocs theme to Bootswatch 4.1.3 ( #1563 ) \uf0c1 The mkdocs theme now supports all the features of Bootswatch 4.1 . Additionally, 2 filenames were changed in this update. If you are using a theme which inherits from the mkdocs theme, the theme developer may need to update these filenames as follows. css/bootstrap-custom.min.css => css/bootstrap.min.css js/bootstrap-3.0.3.min.js => js/bootstrap.min.js Improved configuration support on the command line ( #1401 ) \uf0c1 The build , serve , and gh-deploy subcommands now support flags to control whether directory URLs should be created: --use-directory-urls / --no-directory-urls . In addition, the gh-deploy subcommand now supports all the configuration options that build and serve do, adding --strict , --theme , --theme-dir , and --site-dir . Updated lunr-languages support ( #1729 ) \uf0c1 The lunr-languages plugin has been updated to 1.4.0, adding support for Arabic ( ar ) and Vietnamese ( vi ) languages. In addition, the Dutch and Japanese language codes have been changed to their standard values: nl and ja , respectively. The old language codes ( du and jp ) remain as aliases but may be removed in a future version of MkDocs. Other Changes and Additions to Version 1.1 \uf0c1 Bugfix: Ensure nested dot files in themes are ignored and document behavior ( #1981 ). Update minimum dependency to Markdown 3.2.1. Updated minimum dependency to Jinja 2.10.1 to address security concerns ( #1780 ). Update to lunr.js 2.3.8 ( #1989 ). Add support for Python 3.8. Drop support for Python 3.4. Drop support for Python 2.7. MkDocs is PY3 only now ( #1926 ). Bugfix: Select appropriate asyncio event loop on Windows for Python 3.8+ ( #1885 ). Bugfix: Ensure nested index pages do not get identified as the homepage ( #1919 ). Bugfix: Properly identify deployment version ( #1879 ). Bugfix: Properly build ValidationError message for custom_dir ( #1849 ). Bugfix: Exclude Markdown files and READMEs from theme ( #1766 ). Bugfix: Account for encoded URLs ( #1670 ). Bugfix: Ensure theme files do not override docs_dir files ( #1671 ). Bugfix: Do not normalize URL fragments ( #1655 ). Bugfix: Skip external URLs in sitemap.xml ( #1742 ). Bugfix: Ensure theme files do not override docs_dir files on Windows ( #1876 ) Add canonical tag to readthedocs theme ( #1669 ). Improved error message for when git is not available. Add support for nav_style theme option for the mkdocs theme ( #1930 ). Bugfix: Long/nested dropdowns now behave more consistently for the mkdocs theme ( #1234 ). Bugfix: Multi-row nav headers in the mkdocs theme no longer obscure the document content ( #716 ). Add support for navigation_depth theme option for the mkdocs theme ( #1970 ). level attribute in page.toc items is now 1-indexed to match the level in <hN> tags ( #1970 ). Version 1.0.4 (2018-09-07) \uf0c1 Bugfix: Ignore absolute links in Markdown ( #1621 ). Version 1.0.3 (2018-08-29) \uf0c1 Bugfix: Warn on relative paths in navigation ( #1604 ). Bugfix: Handle empty theme_config.yml files correctly ( #1602 ). Version 1.0.2 (2018-08-22) \uf0c1 Bugfix: Provide absolute base_url to error templates ( #1598 ). Version 1.0.1 (2018-08-13) \uf0c1 Bugfix: Prevent page reload when [Enter] is pressed in search box ( #1589 ). Bugfix: Avoid calling search until all assets are ready ( #1584 ). Bugfix: Exclude README.md if index.md is present ( #1580 ). Bugfix: Fix readthedocs theme navigation bug with homepage ( #1576 ). Version 1.0 (2018-08-03) \uf0c1 Major Additions to Version 1.0 \uf0c1 Internal Refactor of Pages, Files, and Navigation \uf0c1 Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below. Support for hidden pages. All Markdown pages are now included in the build regardless of whether they are included in the navigation configuration ( #699 ). The navigation can now include links to external sites ( #989 #1373 & #1406 ). Page data (including titles) is properly determined for all pages before any page is rendered ( #1347 ). Automatically populated navigation now sorts index pages to the top. In other words, The index page will be listed as the first child of a directory, while all other documents are sorted alphanumerically by file name after the index page ( #73 & #1042 ). A README.md file is now treated as an index file within a directory and will be rendered to index.html ( #608 ). The URLs for all files are computed once and stored in a files collection. This ensures all internal links are always computed correctly regardless of the configuration. This also allows all internal links to be validated, not just links to other Markdown pages. ( #842 & #872 ). A new url template filter smartly ensures all URLs are relative to the current page ( #1526 ). An on_files plugin event has been added, which could be used to include files not in the docs_dir , exclude files, redefine page URLs (i.e. implement extensionless URLs), or to manipulate files in various other ways. Backward Incompatible Changes \uf0c1 As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below. URLs have changed when use_directory_urls is False \uf0c1 Previously, all Markdown pages would be have their filenames altered to be index pages regardless of how the use_directory_urls setting was configured. However, the path munging is only needed when use_directory_urls is set to True (the default). The path mangling no longer happens when use_directory_urls is set to False , which will result in different URLs for all pages that were not already index files. As this behavior only effects a non-default configuration, and the most common user-case for setting the option to False is for local file system ( file:// ) browsing, its not likely to effect most users. However, if you have use_directory_urls set to False for a MkDocs site hosted on a web server, most of your URLs will now be broken. As you can see below, the new URLs are much more sensible. Markdown file Old URL New URL index.md index.html index.html foo.md foo/index.html foo.html foo/bar.md foo/bar/index.html foo/bar.html Note that there has been no change to URLs or file paths when use_directory_urls is set to True (the default), except that MkDocs more consistently includes an ending slash on all internally generated URLs. The pages configuration setting has been renamed to nav \uf0c1 The pages configuration setting is deprecated and will issue a warning if set in the configuration file. The setting has been renamed nav . To update your configuration, simply rename the setting to nav . In other words, if your configuration looked like this: pages: - Home: index.md - User Guide: user-guide.md Simply edit the configuration as follows: nav: - Home: index.md - User Guide: user-guide.md In the current release, any configuration which includes a pages setting, but no nav setting, the pages configuration will be copied to nav and a warning will be issued. However, in a future release, that may no longer happen. If both pages and nav are defined, the pages setting will be ignored. Template variables and base_url \uf0c1 In previous versions of MkDocs some URLs expected the base_url template variable to be prepended to the URL and others did not. That inconsistency has been removed in that no URLs are modified before being added to the template context. For example, a theme template might have previously included a link to the site_name as: <a href=\"{{ nav.homepage.url }}\">{{ config.site_name }}</a> And MkDocs would magically return a URL for the homepage which was relative to the current page. That \"magic\" has been removed and the url template filter should be used: <a href=\"{{ nav.homepage.url|url }}\">{{ config.site_name }}</a> This change applies to any navigation items and pages, as well as the page.next_page and page.previous_page attributes. For the time being, the extra_javascript and extra_css variables continue to work as previously (without the url template filter), but they have been deprecated and the corresponding configuration values ( config.extra_javascript and config.extra_css respectively) should be used with the filter instead. {% for path in config['extra_css'] %} <link href=\"{{ path|url }}\" rel=\"stylesheet\"> {% endfor %} Note that navigation can now include links to external sites. Obviously, the base_url should not be prepended to these items. However, the url template filter is smart enough to recognize the URL is absolute and does not alter it. Therefore, all navigation items can be passed to the filter and only those that need to will be altered. {% for nav_item in nav %} <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> {% endfor %} Path Based Settings are Relative to Configuration File ( #543 ) \uf0c1 Previously any relative paths in the various configuration options were resolved relative to the current working directory. They are now resolved relative to the configuration file. As the documentation has always encouraged running the various MkDocs commands from the directory that contains the configuration file (project root), this change will not affect most users. However, it will make it much easier to implement automated builds or otherwise run commands from a location other than the project root. Simply use the -f/--config-file option and point it at the configuration file: mkdocs build --config-file /path/to/my/config/file.yml As previously, if no file is specified, MkDocs looks for a file named mkdocs.yml in the current working directory. Added support for YAML Meta-Data ( #1542 ) \uf0c1 Previously, MkDocs only supported MultiMarkdown style meta-data, which does not recognize different data types and is rather limited. MkDocs now also supports YAML style meta-data in Markdown documents. MkDocs relies on the the presence or absence of the deliminators ( --- or ... ) to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. Previously MkDocs would recognize MultiMarkdown style meta-data between the deliminators. Now, if the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Therefore, MultiMarkdown's style meta-data must not include the deliminators. See the MultiMarkdown style meta-data documentation for details. Prior to version 0.17, MkDocs returned all meta-data values as a list of strings (even a single line would return a list of one string). In version 0.17, that behavior was changed to return each value as a single string (multiple lines were joined), which some users found limiting (see #1471 ). That behavior continues for MultiMarkdown style meta-data in the current version. However, YAML style meta-data supports the full range of \"safe\" YAML data types. Therefore, it is recommended that any complex meta-data make use of the YAML style (see the YAML style meta-data documentation for details). In fact, a future version of MkDocs may deprecate support for MultiMarkdown style meta-data. Refactor Search Plugin \uf0c1 The search plugin has been completely refactored to include support for the following features: Use a web worker in the browser with a fallback ( #1396 ). Optionally pre-build search index locally ( #859 & #1061 ). Upgrade to lunr.js 2.x ( #1319 ). Support search in languages other than English ( #826 ). Allow the user to define the word separators ( #867 ). Only run searches for queries of length > 2 ( #1127 ). Remove dependency on require.js ( #1218 ). Compress the search index ( #1128 ). Users can review the configuration options available and theme authors should review how search and themes interact. theme_dir Configuration Option fully Deprecated \uf0c1 As of version 0.17, the custom_dir option replaced the deprecated theme_dir option. If users had set the theme_dir option, MkDocs version 0.17 copied the value to the theme.custom_dir option and a warning was issued. As of version 1.0, the value is no longer copied and an error is raised. Other Changes and Additions to Version 1.0 \uf0c1 Keyboard shortcuts changed to not conflict with commonly used accessibility shortcuts ( #1502 .) User friendly YAML parse errors ( #1543 ). Officially support Python 3.7. A missing theme configuration file now raises an error. Empty extra_css and extra_javascript settings no longer raise a warning. Add highlight.js configuration settings to built-in themes ( #1284 ). Close search modal when result is selected ( #1527 ). Add a level attribute to AnchorLinks ( #1272 ). Add MkDocs version check to gh-deploy script ( #640 ). Improve Markdown extension error messages. ( #782 ). Drop official support for Python 3.3 and set tornado>=5.0 ( #1427 ). Add support for GitLab edit links ( #1435 ). Link to GitHub issues from release notes ( #644 ). Expand {sha} and {version} in gh-deploy commit message ( #1410 ). Compress sitemap.xml ( #1130 ). Defer loading JS scripts ( #1380 ). Add a title attribute to the search input ( #1379 ). Update RespondJS to latest version ( #1398 ). Always load Google Analytics over HTTPS ( #1397 ). Improve scrolling frame rate ( #1394 ). Provide more version info. ( #1393 ). Refactor writing-your-docs.md ( #1392 ). Workaround Safari bug when zooming to < 100% ( #1389 ). Remove addition of clicky class to body and animations. ( #1387 ). Prevent search plugin from re-injecting extra_javascript files ( #1388 ). Refactor copy_media_files util function for more flexibility ( #1370 ). Remove PyPI Deployment Docs ( #1360 ). Update links to Python-Markdown library ( #1360 ). Document how to generate manpages for MkDocs commands ( #686 ). Version 0.17.5 (2018-07-06) \uf0c1 Bugfix: Fix Python 3.7 and PEP 479 incompatibility ( #1518 ). Version 0.17.4 (2018-06-08) \uf0c1 Bugfix: Add multi-level nesting support to sitemap.xml ( #1482 ). Version 0.17.3 (2018-03-07) \uf0c1 Bugfix: Set dependency tornado>=4.1,<5.0 due to changes in 5.0 ( #1428 ). Version 0.17.2 (2017-11-15) \uf0c1 Bugfix: Correct extra_* config setting regressions ( #1335 & #1336 ). Version 0.17.1 (2017-10-30) \uf0c1 Bugfix: Support repo_url with missing ending slash. ( #1321 ). Bugfix: Add length support to mkdocs.toc.TableOfContext ( #1325 ). Bugfix: Add some theme specific settings to the search plugin for third party themes ( #1316 ). Bugfix: Override site_url with dev_addr on local server ( #1317 ). Version 0.17.0 (2017-10-19) \uf0c1 Major Additions to Version 0.17.0 \uf0c1 Plugin API. ( #206 ) \uf0c1 A new Plugin API has been added to MkDocs which allows users to define their own custom behaviors. See the included documentation for a full explanation of the API. The previously built-in search functionality has been removed and wrapped in a plugin (named \"search\") with no changes in behavior. When MkDocs builds, the search index is now written to search/search_index.json instead of mkdocs/search_index.json . If no plugins setting is defined in the config, then the search plugin will be included by default. See the configuration documentation for information on overriding the default. Theme Customization. ( #1164 ) \uf0c1 Support had been added to provide theme specific customizations. Theme authors can define default options as documented in Theme Configuration . A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. The theme configuration is defined in a configuration file named mkdocs_theme.yml which should be placed at the root of your template files. A warning will be raised if no configuration file is found and an error will be raised in a future release. Users can override those defaults under the theme configuration option of their mkdocs.yml configuration file, which now accepts nested options. One such nested option is the custom_dir option, which replaces the now deprecated theme_dir option. If users had previously set the theme_dir option, a warning will be issued, with an error expected in a future release. If a configuration previously defined a theme_dir like this: theme: mkdocs theme_dir: custom Then the configuration should be adjusted as follows: theme: name: mkdocs custom_dir: custom See the theme configuration option documentation for details. Previously deprecated Template variables removed. ( #1168 ) \uf0c1 Page Template \uf0c1 The primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html continued to work if no main.html template existed, but it raised a deprecation warning. In version 1.0, a build will fail if no main.html template exists. Context Variables \uf0c1 Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names issued a warning in version 0.16, but have been removed in version 1.0. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico Auto-Populated extra_css and extra_javascript Fully Deprecated. ( #986 ) \uf0c1 In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. On version 0.16 this behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and JavaScript files will not be included in the HTML templates, however, a warning will be issued. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward. Other Changes and Additions to Version 0.17.0 \uf0c1 Add \"edit Link\" support to MkDocs theme ( #1129 ) Open files with utf-8-sig to account for BOM ( #1186 ) Symbolic links are now followed consistently ( #1134 ) Support for keyboard navigation shortcuts added to included themes ( #1095 ) Some refactoring and improvements to config_options ( #1296 ) Officially added support for Python 3.6 ( #1296 ) 404 Error page added to readthedocs theme ( #1296 )) Internal refactor of Markdown processing ( #713 ) Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch themes ( #1168 ) The legacy pages config is no longer supported ( #1168 ) The deprecated json command has been removed ( #481 ) Support for Python 2.6 has been dropped ( #165 ) File permissions are no longer copied during build ( #1292 ) Support query and fragment strings in edit_uri ( #1224 & #1273 ) Version 0.16.3 (2017-04-04) \uf0c1 Fix error raised by autoscrolling in the readthedocs theme ( #1177 ) Fix a few documentation typos ( #1181 & #1185 ) Fix a regression to livereload server introduced in 0.16.2 ( #1174 ) Version 0.16.2 (2017-03-13) \uf0c1 System root ( / ) is not a valid path for site_dir or docs_dir ( #1161 ) Refactor readthedocs theme navigation ( #1155 & #1156 ) Add support to dev server to serve custom error pages ( #1040 ) Ensure nav.homepage.url is not blank on error pages ( #1131 ) Increase livereload dependency to 2.5.1 ( #1106 ) Version 0.16.1 (2016-12-22) \uf0c1 Ensure scrollspy behavior does not affect nav bar ( #1094 ) Only \"load\" a theme when it is explicitly requested by the user ( #1105 ) Version 0.16 (2016-11-04) \uf0c1 Major Additions to Version 0.16.0 \uf0c1 Template variables refactored. ( #874 ) \uf0c1 Page Context \uf0c1 Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Global Context \uf0c1 Additionally, a number of global variables have been altered and/or deprecated and user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if nav|length>1 %} instead. Previously, the global variable include_next_prev was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if page.next_page or page.previous_page %} instead. Previously the global variable page_description was altered programmatically based on whether the current page was the homepage. Now it simply maps to config['site_description'] . Use {% if page.is_homepage %} in the template to conditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is being deprecated. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use nav.homepage.url instead. The global variable favicon maps to the configuration setting site_favicon . Both the template variable and the configuration setting are being deprecated and will issue a warning but continue to work for version 0.16, and may be removed in a future version. Use {{ base_url }}/img/favicon.ico in your template instead. Users can simply save a copy of their custom favicon icon to img/favicon.ico in either their docs_dir or theme_dir . A number of variables map directly to similarly named variables in the config . Those variables are being deprecated and will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use config.var_name instead, where var_name is the name of one of the configuration variables. Below is a summary of all of the changes made to the global context: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico Increased Template Customization. ( #607 ) \uf0c1 The built-in themes have been updated by having each of their many parts wrapped in template blocks which allow each individual block to be easily overridden using the theme_dir config setting. Without any new settings, you can use a different analytics service, replace the default search function, or alter the behavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html will continue to work if no main.html template exists, but it is deprecated and will raise a warning. In version 1.0, a build will fail if no main.html template exists. Any custom and third party templates should be updated accordingly. The easiest way for a third party theme to be updated would be to simply add a main.html file which only contains the following line: {% extends \"base.html\" %} That way, the theme contains the main.html entry point, and also supports overriding blocks in the same manner as the built-in themes. Third party themes are encouraged to wrap the various pieces of their templates in blocks in order to support such customization. Auto-Populated extra_css and extra_javascript Deprecated. ( #986 ) \uf0c1 In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. This behavior is deprecated and a warning will be issued. In the next release, the auto-populate feature will stop working and any unlisted CSS and JavaScript files will not be included in the HTML templates. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward. Support for dirty builds. ( #990 ) \uf0c1 For large sites the build time required to create the pages can become problematic, thus a \"dirty\" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. This mode may be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages. Stricter Directory Validation \uf0c1 Previously, a warning was issued if the site_dir was a child directory of the docs_dir . This now raises an error. Additionally, an error is now raised if the docs_dir is set to the directory which contains your config file rather than a child directory. You will need to rearrange you directory structure to better conform with the documented layout . Other Changes and Additions to Version 0.16.0 \uf0c1 Bugfix: Support gh-deploy command on Windows with Python 3 ( #722 ) Bugfix: Include .woff2 font files in Python package build ( #894 ) Various updates and improvements to Documentation Home Page/Tutorial ( #870 ) Bugfix: Support livereload for config file changes ( #735 ) Bugfix: Non-media template files are no longer copied with media files ( #807 ) Add a flag (-e/--theme-dir) to specify theme directory with the commands mkdocs build and mkdocs serve ( #832 ) Fixed issues with Unicode file names under Windows and Python 2. ( #833 ) Improved the styling of in-line code in the MkDocs theme. ( #718 ) Bugfix: convert variables to JSON when being passed to JavaScript ( #850 ) Updated the ReadTheDocs theme to match the upstream font sizes and colors more closely. ( #857 ) Fixes an issue with permalink markers showing when the mouse was far above them ( #843 ) Bugfix: Handle periods in directory name when automatically creating the pages config. ( #728 ) Update searching to Lunr 0.7, which comes with some performance enhancements for larger documents ( #859 ) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\" builds ( #938 ) Follow links when copying media files ( #869 ). Change \"Edit on...\" links to point directly to the file in the source repository, rather than to the root of the repository ( #975 ), configurable via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI ( #738 ). Add a --force flag to the gh-deploy command to force the push to the repository ( #973 ). Improve alignment for current selected menu item in readthedocs theme ( #888 ). http://user.github.io/repo => https://user.github.io/repo/ ( #1029 ). Improve installation instructions ( #1028 ). Account for wide tables and consistently wrap inline code spans ( #834 ). Bugfix: Use absolute URLs in nav & media links from error templates ( #77 ). Version 0.15.3 (2016-02-18) \uf0c1 Improve the error message the given theme can't be found. Fix an issue with relative symlinks ( #639 ) Version 0.15.2 (2016-02-08) \uf0c1 Fix an incorrect warning that states external themes will be removed from MkDocs . Version 0.15.1 (2016-01-30) \uf0c1 Lower the minimum supported Click version to 3.3 for package maintainers. ( #763 ) Version 0.15.0 (2016-01-21) \uf0c1 Major Additions to Version 0.15.0 \uf0c1 Add support for installable themes \uf0c1 MkDocs now supports themes that are distributed via Python packages. With this addition, the Bootstrap and Bootswatch themes have been moved to external git repositories and python packages. See their individual documentation for more details about these specific themes. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that they will be installable with pip: pip install mkdocs-bootstrap and pip install mkdocs-bootswatch See the documentation for Customizing Your Theme for more information about using and customizing themes and Custom themes for creating and distributing new themes Other Changes and Additions to Version 0.15.0 \uf0c1 Fix issues when using absolute links to Markdown files. ( #628 ) Deprecate support of Python 2.6, pending removal in 1.0.0. ( #165 ) Add official support for Python version 3.5. Add support for site_description and site_author to the ReadTheDocs theme. ( #631 ) Update FontAwesome to 4.5.0. ( #789 ) Increase IE support with X-UA-Compatible. ( #785 ) Added support for Python's -m flag. ( #706 ) Bugfix: Ensure consistent ordering of auto-populated pages. ( #638 ) Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long for the page. ( #204 ) Bugfix: Add all ancestors to the page attribute ancestors rather than just the initial one. ( #693 ) Bugfix: Include HTML in the build output again. ( #691 ) Bugfix: Provide filename to Read the Docs. ( #721 and RTD #1480 ) Bugfix: Silence Click's unicode_literals warning. ( #708 ) Version 0.14.0 (2015-06-09) \uf0c1 Improve Unicode handling by ensuring that all config strings are loaded as Unicode. ( #592 ) Remove dependency on the six library. ( #583 ) Remove dependency on the ghp-import library. ( #547 ) Add --quiet and --verbose options to all sub-commands. ( #579 ) Add short options ( -a ) to most command line options. ( #579 ) Add copyright footer for readthedocs theme. ( #568 ) If the requested port in mkdocs serve is already in use, don't show the user a full stack trace. ( #596 ) Bugfix: Fix a JavaScript encoding problem when searching with spaces. ( #586 ) Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root. ( #578 ) Bugfix: Handle (pass-through instead of dropping) HTML entities while parsing TOC. ( #612 ) Bugfix: Default extra_templates to an empty list, don't automatically discover them. ( #616 ) Version 0.13.3 (2015-06-02) \uf0c1 Bugfix: Reduce validation error to a warning if the site_dir is within the docs_dir as this shouldn't cause any problems with building but will inconvenience users building multiple times. ( #580 ) Version 0.13.2 (2015-05-30) \uf0c1 Bugfix: Ensure all errors and warnings are logged before exiting. ( #536 ) Bugfix: Fix compatibility issues with ReadTheDocs. ( #554 ) Version 0.13.1 (2015-05-27) \uf0c1 Bugfix: Fix a problem with minimal configurations which only contain a list of paths in the pages config. ( #562 ) Version 0.13.0 (2015-05-26) \uf0c1 Deprecations to Version 0.13.0 \uf0c1 Deprecate the JSON command \uf0c1 In this release the mkdocs json command has been marked as deprecated and when used a deprecation warning will be shown. It will be removed in a future release of MkDocs, version 1.0 at the latest. The mkdocs json command provided a convenient way for users to output the documentation contents as JSON files but with the additions of search to MkDocs this functionality is duplicated. A new index with all the contents from a MkDocs build is created in the site_dir , so with the default value for the site_dir It can be found in site/mkdocs/search_index.json . This new file is created on every MkDocs build (with mkdocs build ) and no configuration is needed to enable it. Change the pages configuration \uf0c1 Provide a new way to define pages, and specifically nested pages , in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0. Warn users about the removal of builtin themes \uf0c1 All themes other than mkdocs and readthedocs will be moved into external packages in a future release of MkDocs. This will enable them to be more easily supported and updates outside MkDocs releases. Major Additions to Version 0.13.0 \uf0c1 Search \uf0c1 Support for search has now been added to MkDocs. This is based on the JavaScript library lunr.js . It has been added to both the mkdocs and readthedocs themes. See the custom theme documentation on supporting search for adding it to your own themes. New Command Line Interface \uf0c1 The command line interface for MkDocs has been re-written with the Python library Click . This means that MkDocs now has an easier to use interface with better help output. This change is partially backwards incompatible as while undocumented it was possible to pass any configuration option to the different commands. Now only a small subset of the configuration options can be passed to the commands. To see in full commands and available arguments use mkdocs --help and mkdocs build --help to have them displayed. Support Extra HTML and XML files \uf0c1 Like the extra_javascript and extra_css configuration options, a new option named extra_templates has been added. This will automatically be populated with any .html or .xml files in the project docs directory. Users can place static HTML and XML files and they will be copied over, or they can also use Jinja2 syntax and take advantage of the global variables . By default MkDocs will use this approach to create a sitemap for the documentation. Other Changes and Additions to Version 0.13.0 \uf0c1 Add support for Markdown extension configuration options . ( #435 ) MkDocs now ships Python wheels . ( #486 ) Only include the build date and MkDocs version on the homepage. ( #490 ) Generate sitemaps for documentation builds. ( #436 ) Add a clearer way to define nested pages in the configuration. ( #482 ) Add an extra config option for passing arbitrary variables to the template. ( #510 ) Add --no-livereload to mkdocs serve for a simpler development server. ( #511 ) Add copyright display support to all themes ( #549 ) Add support for custom commit messages in a mkdocs gh-deploy ( #516 ) Bugfix: Fix linking to media within the same directory as a markdown file called index.md ( #535 ) Bugfix: Fix errors with Unicode filenames ( #542 ). Version 0.12.2 (2015-04-22) \uf0c1 Bugfix: Fix a regression where there would be an error if some child titles were missing but others were provided in the pages config. ( #464 ) Version 0.12.1 (2015-04-14) \uf0c1 Bugfix: Fixed a CSS bug in the table of contents on some browsers where the bottom item was not clickable. Version 0.12.0 (2015-04-14) \uf0c1 Display the current MkDocs version in the CLI output. ( #258 ) Check for CNAME file when using gh-deploy. ( #285 ) Add the homepage back to the navigation on all themes. ( #271 ) Add a strict more for local link checking. ( #279 ) Add Google analytics support to all themes. ( #333 ) Add build date and MkDocs version to the ReadTheDocs and MkDocs theme outputs. ( #382 ) Standardize highlighting across all themes and add missing languages. ( #387 ) Add a verbose flag. (-v) to show more details about what the build. ( #147 ) Add the option to specify a remote branch when deploying to GitHub. This enables deploying to GitHub pages on personal and repo sites. ( #354 ) Add favicon support to the ReadTheDocs theme HTML. ( #422 ) Automatically refresh the browser when files are edited. ( #163 ) Bugfix: Never re-write URLs in code blocks. ( #240 ) Bugfix: Don't copy dotfiles when copying media from the docs_dir . ( #254 ) Bugfix: Fix the rendering of tables in the ReadTheDocs theme. ( #106 ) Bugfix: Add padding to the bottom of all bootstrap themes. ( #255 ) Bugfix: Fix issues with nested Markdown pages and the automatic pages configuration. ( #276 ) Bugfix: Fix a URL parsing error with GitHub enterprise. ( #284 ) Bugfix: Don't error if the mkdocs.yml is completely empty. ( #288 ) Bugfix: Fix a number of problems with relative URLs and Markdown files. ( #292 ) Bugfix: Don't stop the build if a page can't be found, continue with other pages. ( #150 ) Bugfix: Remove the site_name from the page title, this needs to be added manually. ( #299 ) Bugfix: Fix an issue with table of contents cutting off Markdown. ( #294 ) Bugfix: Fix hostname for BitBucket. ( #339 ) Bugfix: Ensure all links end with a slash. ( #344 ) Bugfix: Fix repo links in the readthedocs theme. ( #365 ) Bugfix: Include jQuery locally to avoid problems using MkDocs offline. ( #143 ) Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. ( #384 ) Bugfix: Remove inline CSS in the ReadTheDocs theme. ( #393 ) Bugfix: Fix problems with the child titles due to the order the pages config was processed. ( #395 ) Bugfix: Don't error during live reload when the theme doesn't exist. ( #373 ) Bugfix: Fix problems with the Meta extension when it may not exist. ( #398 ) Bugfix: Wrap long inline code otherwise they will run off the screen. ( #313 ) Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to fix problems with titles containing code. ( #367 ) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden under the navigation. ( #7 ) Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. ( #295 ) Bugfix: Fix an error when passing in a specific config file with mkdocs serve . ( #341 ) Bugfix: Don't overwrite index.md files with the mkdocs new command. ( #412 ) Bugfix: Remove bold and italic from code in the ReadTheDocs theme. ( #411 ) Bugfix: Display images inline in the MkDocs theme. ( #415 ) Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. ( #319 ) Bugfix: Don't delete hidden files when using mkdocs build --clean . ( #346 ) Bugfix: Don't block newer versions of Python-markdown on Python >= 2.7. ( #376 ) Bugfix: Fix encoding issues when opening files across platforms. ( #428 ) Version 0.11.1 (2014-11-20) \uf0c1 Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs theme. ( #233 ) Version 0.11.0 (2014-11-18) \uf0c1 Render 404.html files if they exist for the current theme. ( #194 ) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs and ReadTheDocs themes. ( #225 ) Bugfix: Fix an issue with the google_analytics code. ( #219 ) Bugfix: Remove __pycache__ from the package tar. ( #196 ) Bugfix: Fix markdown links that go to an anchor on the current page. ( #197 ) Bugfix: Don't add prettyprint well CSS classes to all HTML, only add it in the MkDocs theme. ( #183 ) Bugfix: Display section titles in the ReadTheDocs theme. ( #175 ) Bugfix: Use the polling observer in watchdog so rebuilding works on filesystems without inotify. ( #184 ) Bugfix: Improve error output for common configuration related errors. ( #176 ) Version 0.10.0 (2014-10-29) \uf0c1 Added support for Python 3.3 and 3.4. ( #103 ) Configurable Python-Markdown extensions with the config setting markdown_extensions . ( #74 ) Added mkdocs json command to output your rendered documentation as json files. ( #128 ) Added --clean switch to build , json and gh-deploy commands to remove stale files from the output directory. ( #157 ) Support multiple theme directories to allow replacement of individual templates rather than copying the full theme. ( #129 ) Bugfix: Fix <ul> rendering in readthedocs theme. ( #171 ) Bugfix: Improve the readthedocs theme on smaller displays. ( #168 ) Bugfix: Relaxed required python package versions to avoid clashes. ( #104 ) Bugfix: Fix issue rendering the table of contents with some configs. ( #146 ) Bugfix: Fix path for embedded images in sub pages. ( #138 ) Bugfix: Fix use_directory_urls config behavior. ( #63 ) Bugfix: Support extra_javascript and extra_css in all themes. ( #90 ) Bugfix: Fix path-handling under Windows. ( #121 ) Bugfix: Fix the menu generation in the readthedocs theme. ( #110 ) Bugfix: Fix the mkdocs command creation under Windows. ( #122 ) Bugfix: Correctly handle external extra_javascript and extra_css . ( #92 ) Bugfix: Fixed favicon support. ( #87 )","title":"Release Notes"},{"location":"about/release-notes/#release-notes","text":"","title":"Release Notes"},{"location":"about/release-notes/#upgrading","text":"To upgrade MkDocs to the latest version, use pip: pip install -U mkdocs You can determine your currently installed version using mkdocs --version : $ mkdocs --version mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6)","title":"Upgrading"},{"location":"about/release-notes/#maintenance-team","text":"The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan","title":"Maintenance team"},{"location":"about/release-notes/#version-123-2021-10-12","text":"Built-in themes now also support these languages: Simplified Chinese ( #2497 ) Japanese ( #2525 ) Brazilian Portuguese ( #2535 ) Spanish ( #2545 , previously #2396 ) Third-party plugins will take precedence over built-in plugins with the same name ( #2591 ) Bugfix: Fix ability to load translations for some languages: core support ( #2565 ) and search plugin support with fallbacks ( #2602 ) Bugfix (regression in 1.2): Prevent directory traversal in the dev server ( #2604 ) Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a build failure in strict mode ( #2607 ) Bugfix: Correctly print colorful messages in the terminal on Windows ( #2606 ) Bugfix: Python version 3.10 was displayed incorrectly in --version ( #2618 ) Other small improvements; see commit log .","title":"Version 1.2.3 (2021-10-12)"},{"location":"about/release-notes/#version-122-2021-07-18","text":"Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters ( #2464 ) Bugfix (regression in 1.2): Revert livereload file watching to use polling observer ( #2477 ) This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts. This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage. Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls ( #2490 ) Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server ( #2507 ) Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before. Bugfix: Fix gh_deploy with config-file in the current directory ( #2481 ) Bugfix: Fix reversed breadcrumbs in \"readthedocs\" theme ( #2179 ) Allow \"mkdocs.yaml\" as the file name when '--config' is not passed ( #2478 ) Stop treating \";\" as a special character in URLs: urlparse -> urlsplit ( #2502 ) Improve build performance for sites with many pages (partly already done in 1.2) ( #2407 )","title":"Version 1.2.2 (2021-07-18)"},{"location":"about/release-notes/#version-121-2021-06-09","text":"Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes.","title":"Version 1.2.1 (2021-06-09)"},{"location":"about/release-notes/#version-12-2021-06-04","text":"","title":"Version 1.2 (2021-06-04)"},{"location":"about/release-notes/#major-additions-to-version-12","text":"","title":"Major Additions to Version 1.2"},{"location":"about/release-notes/#support-added-for-theme-localization-2299","text":"The mkdocs and readthedocs themes now support language localization using the theme.locale parameter, which defaults to en (English). The only other supported languages in this release are fr (French) and es (Spanish). For details on using the provided translations, see the user guide . Note that translation will not happen by default. Users must first install the necessary dependencies with the following command: pip install mkdocs[i18n] Translation contributions are welcome and detailed in the Translation Guide . Developers of third party themes may want to review the relevant section of the Theme Development Guide . Contributors who are updating the templates to the built-in themes should review the Contributing Guide . The lang setting of the search plugin now defaults to the language specified in theme.locale .","title":"Support added for Theme Localization (#2299)"},{"location":"about/release-notes/#support-added-for-environment-variables-in-the-configuration-file-1954","text":"Environments variables may now be specified in the configuration file with the !ENV tag. The value of the variable will be parsed by the YAML parser and converted to the appropriate type. somekey: !ENV VAR_NAME otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value'] See Environment Variables in the Configuration documentation for details.","title":"Support added for Environment Variables in the configuration file (#1954)"},{"location":"about/release-notes/#support-added-for-configuration-inheritance-2218","text":"A configuration file may now inherit from a parent configuration file. In the primary file set the INHERIT key to the relative path of the parent file. INHERIT: path/to/base.yml The two files will then be deep merged. See Configuration Inheritance for details.","title":"Support added for Configuration Inheritance (#2218)"},{"location":"about/release-notes/#update-gh-deploy-command-2170","text":"The vendored (and modified) copy of ghp_import has been replaced with a dependency on the upstream library. As of version 1.0.0, ghp-import includes a Python API which makes it possible to call directly. MkDocs can now benefit from recent bug fixes and new features, including the following: A .nojekyll file is automatically included when deploying to GitHub Pages. The --shell flag is now available, which reportedly works better on Windows. Git author and committer environment variables should be respected ( #1383 ).","title":"Update gh-deploy command (#2170)"},{"location":"about/release-notes/#rework-auto-reload-and-http-server-for-mkdocs-serve-2385","text":"mkdocs serve now uses a new underlying server + file watcher implementation, based on http.server from standard library and watchdog . It provides similar functionality to the previously used livereload library (which is now dropped from dependencies, along with tornado ). This makes reloads more responsive and consistent in terms of timing. Multiple rapid file changes no longer cause the site to repeatedly rebuild (issue #2061 ). Almost every aspect of the server is slightly different, but actual visible changes are minor. The logging outputs are only similar to the old ones. Degradations in behavior are not expected, and should be reported if found.","title":"Rework auto-reload and HTTP server for mkdocs serve (#2385)"},{"location":"about/release-notes/#offset-the-local-site-root-according-to-the-sub-path-of-the-site_url-2424","text":"When using mkdocs serve and having the site_url specified as e.g. http://example.org/sub/path/ , now the root of the locally served site becomes http://127.0.0.1:8000/sub/path/ and all document paths are offset accordingly.","title":"Offset the local site root according to the sub-path of the site_url (#2424)"},{"location":"about/release-notes/#a-build_error-event-was-added-2103","text":"Plugin developers can now use the on_build_error hook to execute code when an exception is raised while building the site. See on_build_error in the Plugins documentation for details.","title":"A build_error event was added (#2103)"},{"location":"about/release-notes/#three-new-exceptions-builderror-pluginerror-and-abort-2103","text":"MkDocs now has tree new exceptions defined in mkdocs.exceptions : BuildError , PluginError , and Abort : PluginError can be raised from a plugin to stop the build and log an error message without traceback . BuildError should not be used by third-party plugins developers and is reserved for internal use only. Abort is used internally to abort the build and display an error without a traceback. See Handling errors in the Plugins documentation for details.","title":"Three new exceptions: BuildError PluginError and Abort (#2103)"},{"location":"about/release-notes/#search-indexing-strategy-configuration","text":"Users can now specify which strategy they wish to use when indexing their site for search. A user can select between the following options: full : Adds page title, section headings, and full page text to the search index. sections : Adds page titles and section headings only to the search index. titles : Adds only the page titles to the search index. See Search Indexing in the configuration documentation for details.","title":"Search Indexing Strategy configuration"},{"location":"about/release-notes/#backward-incompatible-changes-in-12","text":"The site_url configuration option is now required . If it is not set, a warning will be issued. In a future release an error will be raised ( #2189 ). The use_directory_urls configuration option will be forced to false if site_url is set to an empty string. In that case, if use_directory_urls is not explicitly set to false , a warning will be issued ( #2189 ). Note This was reverted in release 1.2.2 The google_analytics configuration option is deprecated as Google appears to be fazing it out in favor of its new Google Analytics 4 property. See the documentation for your theme for alternatives which can be configured as part of your theme configuration. For example, the mkdocs and readthedocs themes have each added a new theme.analytics.gtag configuration option which uses the new Google Analytics 4 property. See Google's documentation on how to Upgrade to a Google Analytics 4 property . Then set theme.analytics.gtag to the \"G-\" ID and delete the google_analytics configuration option which contains a \"UA-\" ID. So long as the old \"UA-\" ID and new \"G-\" ID are properly linked in your Google account, and you are using the \"G-\" ID, the data will be made available in both the old and new formats by Google Analytics. See #2252 . A theme's files are now excluded from the list of watched files by default when using the --livereload server. This new default behavior is what most users need and provides better performance when editing site content. Theme developers can enable the old behavior with the --watch-theme option. ( #2092 ). The mkdocs theme now removes the sidebar when printing a page. This frees up horizontal space for better rendering of content like tables ( #2193 ). The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema() , which ensures that each instance of the configuration is unique ( #2289 ). The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e.: mkdocs.plugins.pluginname ). The on_serve event (which receives the server object and the builder function) is affected by the server rewrite. server is now a mkdocs.livereload.LiveReloadServer instead of livereload.server.Server . The typical action that plugins can do with these is to call server.watch(some_dir, builder) , which basically adds that directory to watched directories, causing the site to be rebuilt on file changes. That still works, but passing any other function to watch is deprecated and shows a warning. This 2nd parameter is already optional, and will accept only this exact builder function just for compatibility. The python method of the plugins.search.prebuild_index configuration option is pending deprecation as of version 1.2. It is expected that in version 1.3 it will raise a warning if used and in version 1.4 it will raise an error. Users are encouraged to use an alternate method to generate a prebuilt index for search. The lunr and lunr[languages] dependencies are no longer installed by default. The dependencies are only needed for the rare user who pre-builds the search index and uses the python option, which is now pending deprecation. If you use this feature, then you will need to manually install lunr and lunr[languages] . A warning is issued if the dependencies are needed but not installed.","title":"Backward Incompatible Changes in 1.2"},{"location":"about/release-notes/#other-changes-and-additions-to-version-12","text":"Bugfix: Properly process navigation child items in _get_by_type when filtering for sections ( #2203 ). Official support for Python 3.9 has been added and support for Python 3.5 has been dropped. Bugfix: Fixes an issue that would result in a partially cut-off navigation item in the ReadTheDocs theme ( #2297 ). Structure Files object now has a remove method to help plugin developers manipulate the Files tree. The corresponding src_paths has become a property to accommodate this possible dynamic behavior. See #2305 . Updated highlight.js to 10.5.0. See #2313 . Bugfix: Search plugin now works with Japanese language. See #2178 . Documentation has been refactored ( #1629 ). Restore styling of tables in the readthedocs theme ( #2028 ). Ensure site_url ends with a slash ( #1785 ). Correct documentation of pages template context variable ( #1736 ). The lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding 2.3.9 version ( #2306 ). Color is now used in log messages to identify errors, warnings and debug messages. Bugfix: Identify homepage when use_directory_urls is False ( #2362 ).","title":"Other Changes and Additions to Version 1.2"},{"location":"about/release-notes/#version-112-2020-05-14","text":"Bugfix: Normalize IP addresses and change unsupported address error to a warning ( #2108 ).","title":"Version 1.1.2 (2020-05-14)"},{"location":"about/release-notes/#version-111-2020-05-12","text":"Bugfix: Allow compressed sitemap to be deterministic by supporting the SOURCE_DATE_EPOCH environment variable ( #2100 ). Bugfix: Use README.md as index.html even if use_directory_urls is false ( #2081 ). Bugfix: Ignore links which start with a backslash ( #1680 ). Bugfix: Pass builder to the on_serve event so that it can be passed to server.watch by plugins ( #1952 ). Bugfix: Use lunr[languages]==0.5.8 to avoid nltk incompatibilities ( #2062 ). Bugfix: Ensure wheel is Python 3 only ( #2021 ). Bugfix: Clean up dev_addr validation and disallow 0.0.0.0 ( #2022 ). Add support for min_search_length parameter for search plugin ( #2014 ). Bugfix: readthedocs theme code colors ( #2027 ).","title":"Version 1.1.1 (2020-05-12)"},{"location":"about/release-notes/#version-11-2020-02-22","text":"","title":"Version 1.1 (2020-02-22)"},{"location":"about/release-notes/#major-additions-to-version-11","text":"","title":"Major Additions to Version 1.1"},{"location":"about/release-notes/#support-for-lunrpy-as-prebuild_index-engine","text":"Mkdocs now supports pre-building indices using Lunr.py , a pure Python implementation of Lunr.js, allowing the user to avoid installing a NodeJS environment if so desired. For more information please read the prebuild_index documentation .","title":"Support for Lunr.py as prebuild_index engine"},{"location":"about/release-notes/#readthedocs-theme-updated-with-upstream-588-and-1374","text":"The readthedocs theme now more closely matches the upstream Sphinx theme (version 0.4.1). A number of new theme configuration settings were added which mirror the upstream configuration options. See the theme documentation for details.","title":"readthedocs theme updated with upstream (#588 and #1374)"},{"location":"about/release-notes/#update-mkdocs-theme-to-bootswatch-413-1563","text":"The mkdocs theme now supports all the features of Bootswatch 4.1 . Additionally, 2 filenames were changed in this update. If you are using a theme which inherits from the mkdocs theme, the theme developer may need to update these filenames as follows. css/bootstrap-custom.min.css => css/bootstrap.min.css js/bootstrap-3.0.3.min.js => js/bootstrap.min.js","title":"Update mkdocs theme to Bootswatch 4.1.3 (#1563)"},{"location":"about/release-notes/#improved-configuration-support-on-the-command-line-1401","text":"The build , serve , and gh-deploy subcommands now support flags to control whether directory URLs should be created: --use-directory-urls / --no-directory-urls . In addition, the gh-deploy subcommand now supports all the configuration options that build and serve do, adding --strict , --theme , --theme-dir , and --site-dir .","title":"Improved configuration support on the command line (#1401)"},{"location":"about/release-notes/#updated-lunr-languages-support-1729","text":"The lunr-languages plugin has been updated to 1.4.0, adding support for Arabic ( ar ) and Vietnamese ( vi ) languages. In addition, the Dutch and Japanese language codes have been changed to their standard values: nl and ja , respectively. The old language codes ( du and jp ) remain as aliases but may be removed in a future version of MkDocs.","title":"Updated lunr-languages support (#1729)"},{"location":"about/release-notes/#other-changes-and-additions-to-version-11","text":"Bugfix: Ensure nested dot files in themes are ignored and document behavior ( #1981 ). Update minimum dependency to Markdown 3.2.1. Updated minimum dependency to Jinja 2.10.1 to address security concerns ( #1780 ). Update to lunr.js 2.3.8 ( #1989 ). Add support for Python 3.8. Drop support for Python 3.4. Drop support for Python 2.7. MkDocs is PY3 only now ( #1926 ). Bugfix: Select appropriate asyncio event loop on Windows for Python 3.8+ ( #1885 ). Bugfix: Ensure nested index pages do not get identified as the homepage ( #1919 ). Bugfix: Properly identify deployment version ( #1879 ). Bugfix: Properly build ValidationError message for custom_dir ( #1849 ). Bugfix: Exclude Markdown files and READMEs from theme ( #1766 ). Bugfix: Account for encoded URLs ( #1670 ). Bugfix: Ensure theme files do not override docs_dir files ( #1671 ). Bugfix: Do not normalize URL fragments ( #1655 ). Bugfix: Skip external URLs in sitemap.xml ( #1742 ). Bugfix: Ensure theme files do not override docs_dir files on Windows ( #1876 ) Add canonical tag to readthedocs theme ( #1669 ). Improved error message for when git is not available. Add support for nav_style theme option for the mkdocs theme ( #1930 ). Bugfix: Long/nested dropdowns now behave more consistently for the mkdocs theme ( #1234 ). Bugfix: Multi-row nav headers in the mkdocs theme no longer obscure the document content ( #716 ). Add support for navigation_depth theme option for the mkdocs theme ( #1970 ). level attribute in page.toc items is now 1-indexed to match the level in <hN> tags ( #1970 ).","title":"Other Changes and Additions to Version 1.1"},{"location":"about/release-notes/#version-104-2018-09-07","text":"Bugfix: Ignore absolute links in Markdown ( #1621 ).","title":"Version 1.0.4 (2018-09-07)"},{"location":"about/release-notes/#version-103-2018-08-29","text":"Bugfix: Warn on relative paths in navigation ( #1604 ). Bugfix: Handle empty theme_config.yml files correctly ( #1602 ).","title":"Version 1.0.3 (2018-08-29)"},{"location":"about/release-notes/#version-102-2018-08-22","text":"Bugfix: Provide absolute base_url to error templates ( #1598 ).","title":"Version 1.0.2 (2018-08-22)"},{"location":"about/release-notes/#version-101-2018-08-13","text":"Bugfix: Prevent page reload when [Enter] is pressed in search box ( #1589 ). Bugfix: Avoid calling search until all assets are ready ( #1584 ). Bugfix: Exclude README.md if index.md is present ( #1580 ). Bugfix: Fix readthedocs theme navigation bug with homepage ( #1576 ).","title":"Version 1.0.1 (2018-08-13)"},{"location":"about/release-notes/#version-10-2018-08-03","text":"","title":"Version 1.0 (2018-08-03)"},{"location":"about/release-notes/#major-additions-to-version-10","text":"","title":"Major Additions to Version 1.0"},{"location":"about/release-notes/#internal-refactor-of-pages-files-and-navigation","text":"Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below. Support for hidden pages. All Markdown pages are now included in the build regardless of whether they are included in the navigation configuration ( #699 ). The navigation can now include links to external sites ( #989 #1373 & #1406 ). Page data (including titles) is properly determined for all pages before any page is rendered ( #1347 ). Automatically populated navigation now sorts index pages to the top. In other words, The index page will be listed as the first child of a directory, while all other documents are sorted alphanumerically by file name after the index page ( #73 & #1042 ). A README.md file is now treated as an index file within a directory and will be rendered to index.html ( #608 ). The URLs for all files are computed once and stored in a files collection. This ensures all internal links are always computed correctly regardless of the configuration. This also allows all internal links to be validated, not just links to other Markdown pages. ( #842 & #872 ). A new url template filter smartly ensures all URLs are relative to the current page ( #1526 ). An on_files plugin event has been added, which could be used to include files not in the docs_dir , exclude files, redefine page URLs (i.e. implement extensionless URLs), or to manipulate files in various other ways.","title":"Internal Refactor of Pages, Files, and Navigation"},{"location":"about/release-notes/#backward-incompatible-changes","text":"As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below.","title":"Backward Incompatible Changes"},{"location":"about/release-notes/#urls-have-changed-when-use_directory_urls-is-false","text":"Previously, all Markdown pages would be have their filenames altered to be index pages regardless of how the use_directory_urls setting was configured. However, the path munging is only needed when use_directory_urls is set to True (the default). The path mangling no longer happens when use_directory_urls is set to False , which will result in different URLs for all pages that were not already index files. As this behavior only effects a non-default configuration, and the most common user-case for setting the option to False is for local file system ( file:// ) browsing, its not likely to effect most users. However, if you have use_directory_urls set to False for a MkDocs site hosted on a web server, most of your URLs will now be broken. As you can see below, the new URLs are much more sensible. Markdown file Old URL New URL index.md index.html index.html foo.md foo/index.html foo.html foo/bar.md foo/bar/index.html foo/bar.html Note that there has been no change to URLs or file paths when use_directory_urls is set to True (the default), except that MkDocs more consistently includes an ending slash on all internally generated URLs.","title":"URLs have changed when use_directory_urls is False"},{"location":"about/release-notes/#the-pages-configuration-setting-has-been-renamed-to-nav","text":"The pages configuration setting is deprecated and will issue a warning if set in the configuration file. The setting has been renamed nav . To update your configuration, simply rename the setting to nav . In other words, if your configuration looked like this: pages: - Home: index.md - User Guide: user-guide.md Simply edit the configuration as follows: nav: - Home: index.md - User Guide: user-guide.md In the current release, any configuration which includes a pages setting, but no nav setting, the pages configuration will be copied to nav and a warning will be issued. However, in a future release, that may no longer happen. If both pages and nav are defined, the pages setting will be ignored.","title":"The pages configuration setting has been renamed to nav"},{"location":"about/release-notes/#template-variables-and-base_url","text":"In previous versions of MkDocs some URLs expected the base_url template variable to be prepended to the URL and others did not. That inconsistency has been removed in that no URLs are modified before being added to the template context. For example, a theme template might have previously included a link to the site_name as: <a href=\"{{ nav.homepage.url }}\">{{ config.site_name }}</a> And MkDocs would magically return a URL for the homepage which was relative to the current page. That \"magic\" has been removed and the url template filter should be used: <a href=\"{{ nav.homepage.url|url }}\">{{ config.site_name }}</a> This change applies to any navigation items and pages, as well as the page.next_page and page.previous_page attributes. For the time being, the extra_javascript and extra_css variables continue to work as previously (without the url template filter), but they have been deprecated and the corresponding configuration values ( config.extra_javascript and config.extra_css respectively) should be used with the filter instead. {% for path in config['extra_css'] %} <link href=\"{{ path|url }}\" rel=\"stylesheet\"> {% endfor %} Note that navigation can now include links to external sites. Obviously, the base_url should not be prepended to these items. However, the url template filter is smart enough to recognize the URL is absolute and does not alter it. Therefore, all navigation items can be passed to the filter and only those that need to will be altered. {% for nav_item in nav %} <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> {% endfor %}","title":"Template variables and base_url"},{"location":"about/release-notes/#path-based-settings-are-relative-to-configuration-file-543","text":"Previously any relative paths in the various configuration options were resolved relative to the current working directory. They are now resolved relative to the configuration file. As the documentation has always encouraged running the various MkDocs commands from the directory that contains the configuration file (project root), this change will not affect most users. However, it will make it much easier to implement automated builds or otherwise run commands from a location other than the project root. Simply use the -f/--config-file option and point it at the configuration file: mkdocs build --config-file /path/to/my/config/file.yml As previously, if no file is specified, MkDocs looks for a file named mkdocs.yml in the current working directory.","title":"Path Based Settings are Relative to Configuration File (#543)"},{"location":"about/release-notes/#added-support-for-yaml-meta-data-1542","text":"Previously, MkDocs only supported MultiMarkdown style meta-data, which does not recognize different data types and is rather limited. MkDocs now also supports YAML style meta-data in Markdown documents. MkDocs relies on the the presence or absence of the deliminators ( --- or ... ) to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. Previously MkDocs would recognize MultiMarkdown style meta-data between the deliminators. Now, if the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Therefore, MultiMarkdown's style meta-data must not include the deliminators. See the MultiMarkdown style meta-data documentation for details. Prior to version 0.17, MkDocs returned all meta-data values as a list of strings (even a single line would return a list of one string). In version 0.17, that behavior was changed to return each value as a single string (multiple lines were joined), which some users found limiting (see #1471 ). That behavior continues for MultiMarkdown style meta-data in the current version. However, YAML style meta-data supports the full range of \"safe\" YAML data types. Therefore, it is recommended that any complex meta-data make use of the YAML style (see the YAML style meta-data documentation for details). In fact, a future version of MkDocs may deprecate support for MultiMarkdown style meta-data.","title":"Added support for YAML Meta-Data (#1542)"},{"location":"about/release-notes/#refactor-search-plugin","text":"The search plugin has been completely refactored to include support for the following features: Use a web worker in the browser with a fallback ( #1396 ). Optionally pre-build search index locally ( #859 & #1061 ). Upgrade to lunr.js 2.x ( #1319 ). Support search in languages other than English ( #826 ). Allow the user to define the word separators ( #867 ). Only run searches for queries of length > 2 ( #1127 ). Remove dependency on require.js ( #1218 ). Compress the search index ( #1128 ). Users can review the configuration options available and theme authors should review how search and themes interact.","title":"Refactor Search Plugin"},{"location":"about/release-notes/#theme_dir-configuration-option-fully-deprecated","text":"As of version 0.17, the custom_dir option replaced the deprecated theme_dir option. If users had set the theme_dir option, MkDocs version 0.17 copied the value to the theme.custom_dir option and a warning was issued. As of version 1.0, the value is no longer copied and an error is raised.","title":"theme_dir Configuration Option fully Deprecated"},{"location":"about/release-notes/#other-changes-and-additions-to-version-10","text":"Keyboard shortcuts changed to not conflict with commonly used accessibility shortcuts ( #1502 .) User friendly YAML parse errors ( #1543 ). Officially support Python 3.7. A missing theme configuration file now raises an error. Empty extra_css and extra_javascript settings no longer raise a warning. Add highlight.js configuration settings to built-in themes ( #1284 ). Close search modal when result is selected ( #1527 ). Add a level attribute to AnchorLinks ( #1272 ). Add MkDocs version check to gh-deploy script ( #640 ). Improve Markdown extension error messages. ( #782 ). Drop official support for Python 3.3 and set tornado>=5.0 ( #1427 ). Add support for GitLab edit links ( #1435 ). Link to GitHub issues from release notes ( #644 ). Expand {sha} and {version} in gh-deploy commit message ( #1410 ). Compress sitemap.xml ( #1130 ). Defer loading JS scripts ( #1380 ). Add a title attribute to the search input ( #1379 ). Update RespondJS to latest version ( #1398 ). Always load Google Analytics over HTTPS ( #1397 ). Improve scrolling frame rate ( #1394 ). Provide more version info. ( #1393 ). Refactor writing-your-docs.md ( #1392 ). Workaround Safari bug when zooming to < 100% ( #1389 ). Remove addition of clicky class to body and animations. ( #1387 ). Prevent search plugin from re-injecting extra_javascript files ( #1388 ). Refactor copy_media_files util function for more flexibility ( #1370 ). Remove PyPI Deployment Docs ( #1360 ). Update links to Python-Markdown library ( #1360 ). Document how to generate manpages for MkDocs commands ( #686 ).","title":"Other Changes and Additions to Version 1.0"},{"location":"about/release-notes/#version-0175-2018-07-06","text":"Bugfix: Fix Python 3.7 and PEP 479 incompatibility ( #1518 ).","title":"Version 0.17.5 (2018-07-06)"},{"location":"about/release-notes/#version-0174-2018-06-08","text":"Bugfix: Add multi-level nesting support to sitemap.xml ( #1482 ).","title":"Version 0.17.4 (2018-06-08)"},{"location":"about/release-notes/#version-0173-2018-03-07","text":"Bugfix: Set dependency tornado>=4.1,<5.0 due to changes in 5.0 ( #1428 ).","title":"Version 0.17.3 (2018-03-07)"},{"location":"about/release-notes/#version-0172-2017-11-15","text":"Bugfix: Correct extra_* config setting regressions ( #1335 & #1336 ).","title":"Version 0.17.2 (2017-11-15)"},{"location":"about/release-notes/#version-0171-2017-10-30","text":"Bugfix: Support repo_url with missing ending slash. ( #1321 ). Bugfix: Add length support to mkdocs.toc.TableOfContext ( #1325 ). Bugfix: Add some theme specific settings to the search plugin for third party themes ( #1316 ). Bugfix: Override site_url with dev_addr on local server ( #1317 ).","title":"Version 0.17.1 (2017-10-30)"},{"location":"about/release-notes/#version-0170-2017-10-19","text":"","title":"Version 0.17.0 (2017-10-19)"},{"location":"about/release-notes/#major-additions-to-version-0170","text":"","title":"Major Additions to Version 0.17.0"},{"location":"about/release-notes/#plugin-api-206","text":"A new Plugin API has been added to MkDocs which allows users to define their own custom behaviors. See the included documentation for a full explanation of the API. The previously built-in search functionality has been removed and wrapped in a plugin (named \"search\") with no changes in behavior. When MkDocs builds, the search index is now written to search/search_index.json instead of mkdocs/search_index.json . If no plugins setting is defined in the config, then the search plugin will be included by default. See the configuration documentation for information on overriding the default.","title":"Plugin API. (#206)"},{"location":"about/release-notes/#theme-customization-1164","text":"Support had been added to provide theme specific customizations. Theme authors can define default options as documented in Theme Configuration . A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. The theme configuration is defined in a configuration file named mkdocs_theme.yml which should be placed at the root of your template files. A warning will be raised if no configuration file is found and an error will be raised in a future release. Users can override those defaults under the theme configuration option of their mkdocs.yml configuration file, which now accepts nested options. One such nested option is the custom_dir option, which replaces the now deprecated theme_dir option. If users had previously set the theme_dir option, a warning will be issued, with an error expected in a future release. If a configuration previously defined a theme_dir like this: theme: mkdocs theme_dir: custom Then the configuration should be adjusted as follows: theme: name: mkdocs custom_dir: custom See the theme configuration option documentation for details.","title":"Theme Customization. (#1164)"},{"location":"about/release-notes/#previously-deprecated-template-variables-removed-1168","text":"","title":"Previously deprecated Template variables removed. (#1168)"},{"location":"about/release-notes/#page-template","text":"The primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html continued to work if no main.html template existed, but it raised a deprecation warning. In version 1.0, a build will fail if no main.html template exists.","title":"Page Template"},{"location":"about/release-notes/#context-variables","text":"Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names issued a warning in version 0.16, but have been removed in version 1.0. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico","title":"Context Variables"},{"location":"about/release-notes/#auto-populated-extra_css-and-extra_javascript-fully-deprecated-986","text":"In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. On version 0.16 this behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and JavaScript files will not be included in the HTML templates, however, a warning will be issued. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.","title":"Auto-Populated extra_css and extra_javascript Fully Deprecated. (#986)"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0170","text":"Add \"edit Link\" support to MkDocs theme ( #1129 ) Open files with utf-8-sig to account for BOM ( #1186 ) Symbolic links are now followed consistently ( #1134 ) Support for keyboard navigation shortcuts added to included themes ( #1095 ) Some refactoring and improvements to config_options ( #1296 ) Officially added support for Python 3.6 ( #1296 ) 404 Error page added to readthedocs theme ( #1296 )) Internal refactor of Markdown processing ( #713 ) Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch themes ( #1168 ) The legacy pages config is no longer supported ( #1168 ) The deprecated json command has been removed ( #481 ) Support for Python 2.6 has been dropped ( #165 ) File permissions are no longer copied during build ( #1292 ) Support query and fragment strings in edit_uri ( #1224 & #1273 )","title":"Other Changes and Additions to Version 0.17.0"},{"location":"about/release-notes/#version-0163-2017-04-04","text":"Fix error raised by autoscrolling in the readthedocs theme ( #1177 ) Fix a few documentation typos ( #1181 & #1185 ) Fix a regression to livereload server introduced in 0.16.2 ( #1174 )","title":"Version 0.16.3 (2017-04-04)"},{"location":"about/release-notes/#version-0162-2017-03-13","text":"System root ( / ) is not a valid path for site_dir or docs_dir ( #1161 ) Refactor readthedocs theme navigation ( #1155 & #1156 ) Add support to dev server to serve custom error pages ( #1040 ) Ensure nav.homepage.url is not blank on error pages ( #1131 ) Increase livereload dependency to 2.5.1 ( #1106 )","title":"Version 0.16.2 (2017-03-13)"},{"location":"about/release-notes/#version-0161-2016-12-22","text":"Ensure scrollspy behavior does not affect nav bar ( #1094 ) Only \"load\" a theme when it is explicitly requested by the user ( #1105 )","title":"Version 0.16.1 (2016-12-22)"},{"location":"about/release-notes/#version-016-2016-11-04","text":"","title":"Version 0.16 (2016-11-04)"},{"location":"about/release-notes/#major-additions-to-version-0160","text":"","title":"Major Additions to Version 0.16.0"},{"location":"about/release-notes/#template-variables-refactored-874","text":"","title":"Template variables refactored. (#874)"},{"location":"about/release-notes/#page-context","text":"Page specific variable names in the template context have been refactored as defined in Custom Themes . The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version. Any of the following old page variables should be updated to the new ones in user created and third-party templates: Old Variable Name New Variable Name current_page page page_title page.title content page.content toc page.toc meta page.meta canonical_url page.canonical_url previous_page page.previous_page next_page page.next_page","title":"Page Context"},{"location":"about/release-notes/#global-context","text":"Additionally, a number of global variables have been altered and/or deprecated and user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if nav|length>1 %} instead. Previously, the global variable include_next_prev was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if page.next_page or page.previous_page %} instead. Previously the global variable page_description was altered programmatically based on whether the current page was the homepage. Now it simply maps to config['site_description'] . Use {% if page.is_homepage %} in the template to conditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is being deprecated. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use nav.homepage.url instead. The global variable favicon maps to the configuration setting site_favicon . Both the template variable and the configuration setting are being deprecated and will issue a warning but continue to work for version 0.16, and may be removed in a future version. Use {{ base_url }}/img/favicon.ico in your template instead. Users can simply save a copy of their custom favicon icon to img/favicon.ico in either their docs_dir or theme_dir . A number of variables map directly to similarly named variables in the config . Those variables are being deprecated and will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use config.var_name instead, where var_name is the name of one of the configuration variables. Below is a summary of all of the changes made to the global context: Old Variable Name New Variable Name or Expression current_page page include_nav nav|length>1 include_next_prev (page.next_page or page.previous_page) site_name config.site_name site_author config.site_author page_description config.site_description repo_url config.repo_url repo_name config.repo_name site_url config.site_url copyright config.copyright google_analytics config.google_analytics homepage_url nav.homepage.url favicon {{ base_url }}/img/favicon.ico","title":"Global Context"},{"location":"about/release-notes/#increased-template-customization-607","text":"The built-in themes have been updated by having each of their many parts wrapped in template blocks which allow each individual block to be easily overridden using the theme_dir config setting. Without any new settings, you can use a different analytics service, replace the default search function, or alter the behavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been changed from base.html to main.html . This allows base.html to continue to exist while allowing users to override main.html and extend base.html . For version 0.16, base.html will continue to work if no main.html template exists, but it is deprecated and will raise a warning. In version 1.0, a build will fail if no main.html template exists. Any custom and third party templates should be updated accordingly. The easiest way for a third party theme to be updated would be to simply add a main.html file which only contains the following line: {% extends \"base.html\" %} That way, the theme contains the main.html entry point, and also supports overriding blocks in the same manner as the built-in themes. Third party themes are encouraged to wrap the various pieces of their templates in blocks in order to support such customization.","title":"Increased Template Customization. (#607)"},{"location":"about/release-notes/#auto-populated-extra_css-and-extra_javascript-deprecated-986","text":"In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. This behavior is deprecated and a warning will be issued. In the next release, the auto-populate feature will stop working and any unlisted CSS and JavaScript files will not be included in the HTML templates. In other words, they will still be copied to the site-dir , but they will not have any effect on the theme if they are not explicitly listed. All CSS and JavaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.","title":"Auto-Populated extra_css and extra_javascript Deprecated. (#986)"},{"location":"about/release-notes/#support-for-dirty-builds-990","text":"For large sites the build time required to create the pages can become problematic, thus a \"dirty\" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. This mode may be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages.","title":"Support for dirty builds. (#990)"},{"location":"about/release-notes/#stricter-directory-validation","text":"Previously, a warning was issued if the site_dir was a child directory of the docs_dir . This now raises an error. Additionally, an error is now raised if the docs_dir is set to the directory which contains your config file rather than a child directory. You will need to rearrange you directory structure to better conform with the documented layout .","title":"Stricter Directory Validation"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0160","text":"Bugfix: Support gh-deploy command on Windows with Python 3 ( #722 ) Bugfix: Include .woff2 font files in Python package build ( #894 ) Various updates and improvements to Documentation Home Page/Tutorial ( #870 ) Bugfix: Support livereload for config file changes ( #735 ) Bugfix: Non-media template files are no longer copied with media files ( #807 ) Add a flag (-e/--theme-dir) to specify theme directory with the commands mkdocs build and mkdocs serve ( #832 ) Fixed issues with Unicode file names under Windows and Python 2. ( #833 ) Improved the styling of in-line code in the MkDocs theme. ( #718 ) Bugfix: convert variables to JSON when being passed to JavaScript ( #850 ) Updated the ReadTheDocs theme to match the upstream font sizes and colors more closely. ( #857 ) Fixes an issue with permalink markers showing when the mouse was far above them ( #843 ) Bugfix: Handle periods in directory name when automatically creating the pages config. ( #728 ) Update searching to Lunr 0.7, which comes with some performance enhancements for larger documents ( #859 ) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\" builds ( #938 ) Follow links when copying media files ( #869 ). Change \"Edit on...\" links to point directly to the file in the source repository, rather than to the root of the repository ( #975 ), configurable via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI ( #738 ). Add a --force flag to the gh-deploy command to force the push to the repository ( #973 ). Improve alignment for current selected menu item in readthedocs theme ( #888 ). http://user.github.io/repo => https://user.github.io/repo/ ( #1029 ). Improve installation instructions ( #1028 ). Account for wide tables and consistently wrap inline code spans ( #834 ). Bugfix: Use absolute URLs in nav & media links from error templates ( #77 ).","title":"Other Changes and Additions to Version 0.16.0"},{"location":"about/release-notes/#version-0153-2016-02-18","text":"Improve the error message the given theme can't be found. Fix an issue with relative symlinks ( #639 )","title":"Version 0.15.3 (2016-02-18)"},{"location":"about/release-notes/#version-0152-2016-02-08","text":"Fix an incorrect warning that states external themes will be removed from MkDocs .","title":"Version 0.15.2 (2016-02-08)"},{"location":"about/release-notes/#version-0151-2016-01-30","text":"Lower the minimum supported Click version to 3.3 for package maintainers. ( #763 )","title":"Version 0.15.1 (2016-01-30)"},{"location":"about/release-notes/#version-0150-2016-01-21","text":"","title":"Version 0.15.0 (2016-01-21)"},{"location":"about/release-notes/#major-additions-to-version-0150","text":"","title":"Major Additions to Version 0.15.0"},{"location":"about/release-notes/#add-support-for-installable-themes","text":"MkDocs now supports themes that are distributed via Python packages. With this addition, the Bootstrap and Bootswatch themes have been moved to external git repositories and python packages. See their individual documentation for more details about these specific themes. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that they will be installable with pip: pip install mkdocs-bootstrap and pip install mkdocs-bootswatch See the documentation for Customizing Your Theme for more information about using and customizing themes and Custom themes for creating and distributing new themes","title":"Add support for installable themes"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0150","text":"Fix issues when using absolute links to Markdown files. ( #628 ) Deprecate support of Python 2.6, pending removal in 1.0.0. ( #165 ) Add official support for Python version 3.5. Add support for site_description and site_author to the ReadTheDocs theme. ( #631 ) Update FontAwesome to 4.5.0. ( #789 ) Increase IE support with X-UA-Compatible. ( #785 ) Added support for Python's -m flag. ( #706 ) Bugfix: Ensure consistent ordering of auto-populated pages. ( #638 ) Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long for the page. ( #204 ) Bugfix: Add all ancestors to the page attribute ancestors rather than just the initial one. ( #693 ) Bugfix: Include HTML in the build output again. ( #691 ) Bugfix: Provide filename to Read the Docs. ( #721 and RTD #1480 ) Bugfix: Silence Click's unicode_literals warning. ( #708 )","title":"Other Changes and Additions to Version 0.15.0"},{"location":"about/release-notes/#version-0140-2015-06-09","text":"Improve Unicode handling by ensuring that all config strings are loaded as Unicode. ( #592 ) Remove dependency on the six library. ( #583 ) Remove dependency on the ghp-import library. ( #547 ) Add --quiet and --verbose options to all sub-commands. ( #579 ) Add short options ( -a ) to most command line options. ( #579 ) Add copyright footer for readthedocs theme. ( #568 ) If the requested port in mkdocs serve is already in use, don't show the user a full stack trace. ( #596 ) Bugfix: Fix a JavaScript encoding problem when searching with spaces. ( #586 ) Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root. ( #578 ) Bugfix: Handle (pass-through instead of dropping) HTML entities while parsing TOC. ( #612 ) Bugfix: Default extra_templates to an empty list, don't automatically discover them. ( #616 )","title":"Version 0.14.0 (2015-06-09)"},{"location":"about/release-notes/#version-0133-2015-06-02","text":"Bugfix: Reduce validation error to a warning if the site_dir is within the docs_dir as this shouldn't cause any problems with building but will inconvenience users building multiple times. ( #580 )","title":"Version 0.13.3 (2015-06-02)"},{"location":"about/release-notes/#version-0132-2015-05-30","text":"Bugfix: Ensure all errors and warnings are logged before exiting. ( #536 ) Bugfix: Fix compatibility issues with ReadTheDocs. ( #554 )","title":"Version 0.13.2 (2015-05-30)"},{"location":"about/release-notes/#version-0131-2015-05-27","text":"Bugfix: Fix a problem with minimal configurations which only contain a list of paths in the pages config. ( #562 )","title":"Version 0.13.1 (2015-05-27)"},{"location":"about/release-notes/#version-0130-2015-05-26","text":"","title":"Version 0.13.0 (2015-05-26)"},{"location":"about/release-notes/#deprecations-to-version-0130","text":"","title":"Deprecations to Version 0.13.0"},{"location":"about/release-notes/#deprecate-the-json-command","text":"In this release the mkdocs json command has been marked as deprecated and when used a deprecation warning will be shown. It will be removed in a future release of MkDocs, version 1.0 at the latest. The mkdocs json command provided a convenient way for users to output the documentation contents as JSON files but with the additions of search to MkDocs this functionality is duplicated. A new index with all the contents from a MkDocs build is created in the site_dir , so with the default value for the site_dir It can be found in site/mkdocs/search_index.json . This new file is created on every MkDocs build (with mkdocs build ) and no configuration is needed to enable it.","title":"Deprecate the JSON command"},{"location":"about/release-notes/#change-the-pages-configuration","text":"Provide a new way to define pages, and specifically nested pages , in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0.","title":"Change the pages configuration"},{"location":"about/release-notes/#warn-users-about-the-removal-of-builtin-themes","text":"All themes other than mkdocs and readthedocs will be moved into external packages in a future release of MkDocs. This will enable them to be more easily supported and updates outside MkDocs releases.","title":"Warn users about the removal of builtin themes"},{"location":"about/release-notes/#major-additions-to-version-0130","text":"","title":"Major Additions to Version 0.13.0"},{"location":"about/release-notes/#search","text":"Support for search has now been added to MkDocs. This is based on the JavaScript library lunr.js . It has been added to both the mkdocs and readthedocs themes. See the custom theme documentation on supporting search for adding it to your own themes.","title":"Search"},{"location":"about/release-notes/#new-command-line-interface","text":"The command line interface for MkDocs has been re-written with the Python library Click . This means that MkDocs now has an easier to use interface with better help output. This change is partially backwards incompatible as while undocumented it was possible to pass any configuration option to the different commands. Now only a small subset of the configuration options can be passed to the commands. To see in full commands and available arguments use mkdocs --help and mkdocs build --help to have them displayed.","title":"New Command Line Interface"},{"location":"about/release-notes/#support-extra-html-and-xml-files","text":"Like the extra_javascript and extra_css configuration options, a new option named extra_templates has been added. This will automatically be populated with any .html or .xml files in the project docs directory. Users can place static HTML and XML files and they will be copied over, or they can also use Jinja2 syntax and take advantage of the global variables . By default MkDocs will use this approach to create a sitemap for the documentation.","title":"Support Extra HTML and XML files"},{"location":"about/release-notes/#other-changes-and-additions-to-version-0130","text":"Add support for Markdown extension configuration options . ( #435 ) MkDocs now ships Python wheels . ( #486 ) Only include the build date and MkDocs version on the homepage. ( #490 ) Generate sitemaps for documentation builds. ( #436 ) Add a clearer way to define nested pages in the configuration. ( #482 ) Add an extra config option for passing arbitrary variables to the template. ( #510 ) Add --no-livereload to mkdocs serve for a simpler development server. ( #511 ) Add copyright display support to all themes ( #549 ) Add support for custom commit messages in a mkdocs gh-deploy ( #516 ) Bugfix: Fix linking to media within the same directory as a markdown file called index.md ( #535 ) Bugfix: Fix errors with Unicode filenames ( #542 ).","title":"Other Changes and Additions to Version 0.13.0"},{"location":"about/release-notes/#version-0122-2015-04-22","text":"Bugfix: Fix a regression where there would be an error if some child titles were missing but others were provided in the pages config. ( #464 )","title":"Version 0.12.2 (2015-04-22)"},{"location":"about/release-notes/#version-0121-2015-04-14","text":"Bugfix: Fixed a CSS bug in the table of contents on some browsers where the bottom item was not clickable.","title":"Version 0.12.1 (2015-04-14)"},{"location":"about/release-notes/#version-0120-2015-04-14","text":"Display the current MkDocs version in the CLI output. ( #258 ) Check for CNAME file when using gh-deploy. ( #285 ) Add the homepage back to the navigation on all themes. ( #271 ) Add a strict more for local link checking. ( #279 ) Add Google analytics support to all themes. ( #333 ) Add build date and MkDocs version to the ReadTheDocs and MkDocs theme outputs. ( #382 ) Standardize highlighting across all themes and add missing languages. ( #387 ) Add a verbose flag. (-v) to show more details about what the build. ( #147 ) Add the option to specify a remote branch when deploying to GitHub. This enables deploying to GitHub pages on personal and repo sites. ( #354 ) Add favicon support to the ReadTheDocs theme HTML. ( #422 ) Automatically refresh the browser when files are edited. ( #163 ) Bugfix: Never re-write URLs in code blocks. ( #240 ) Bugfix: Don't copy dotfiles when copying media from the docs_dir . ( #254 ) Bugfix: Fix the rendering of tables in the ReadTheDocs theme. ( #106 ) Bugfix: Add padding to the bottom of all bootstrap themes. ( #255 ) Bugfix: Fix issues with nested Markdown pages and the automatic pages configuration. ( #276 ) Bugfix: Fix a URL parsing error with GitHub enterprise. ( #284 ) Bugfix: Don't error if the mkdocs.yml is completely empty. ( #288 ) Bugfix: Fix a number of problems with relative URLs and Markdown files. ( #292 ) Bugfix: Don't stop the build if a page can't be found, continue with other pages. ( #150 ) Bugfix: Remove the site_name from the page title, this needs to be added manually. ( #299 ) Bugfix: Fix an issue with table of contents cutting off Markdown. ( #294 ) Bugfix: Fix hostname for BitBucket. ( #339 ) Bugfix: Ensure all links end with a slash. ( #344 ) Bugfix: Fix repo links in the readthedocs theme. ( #365 ) Bugfix: Include jQuery locally to avoid problems using MkDocs offline. ( #143 ) Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. ( #384 ) Bugfix: Remove inline CSS in the ReadTheDocs theme. ( #393 ) Bugfix: Fix problems with the child titles due to the order the pages config was processed. ( #395 ) Bugfix: Don't error during live reload when the theme doesn't exist. ( #373 ) Bugfix: Fix problems with the Meta extension when it may not exist. ( #398 ) Bugfix: Wrap long inline code otherwise they will run off the screen. ( #313 ) Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to fix problems with titles containing code. ( #367 ) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden under the navigation. ( #7 ) Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. ( #295 ) Bugfix: Fix an error when passing in a specific config file with mkdocs serve . ( #341 ) Bugfix: Don't overwrite index.md files with the mkdocs new command. ( #412 ) Bugfix: Remove bold and italic from code in the ReadTheDocs theme. ( #411 ) Bugfix: Display images inline in the MkDocs theme. ( #415 ) Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. ( #319 ) Bugfix: Don't delete hidden files when using mkdocs build --clean . ( #346 ) Bugfix: Don't block newer versions of Python-markdown on Python >= 2.7. ( #376 ) Bugfix: Fix encoding issues when opening files across platforms. ( #428 )","title":"Version 0.12.0 (2015-04-14)"},{"location":"about/release-notes/#version-0111-2014-11-20","text":"Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs theme. ( #233 )","title":"Version 0.11.1 (2014-11-20)"},{"location":"about/release-notes/#version-0110-2014-11-18","text":"Render 404.html files if they exist for the current theme. ( #194 ) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs and ReadTheDocs themes. ( #225 ) Bugfix: Fix an issue with the google_analytics code. ( #219 ) Bugfix: Remove __pycache__ from the package tar. ( #196 ) Bugfix: Fix markdown links that go to an anchor on the current page. ( #197 ) Bugfix: Don't add prettyprint well CSS classes to all HTML, only add it in the MkDocs theme. ( #183 ) Bugfix: Display section titles in the ReadTheDocs theme. ( #175 ) Bugfix: Use the polling observer in watchdog so rebuilding works on filesystems without inotify. ( #184 ) Bugfix: Improve error output for common configuration related errors. ( #176 )","title":"Version 0.11.0 (2014-11-18)"},{"location":"about/release-notes/#version-0100-2014-10-29","text":"Added support for Python 3.3 and 3.4. ( #103 ) Configurable Python-Markdown extensions with the config setting markdown_extensions . ( #74 ) Added mkdocs json command to output your rendered documentation as json files. ( #128 ) Added --clean switch to build , json and gh-deploy commands to remove stale files from the output directory. ( #157 ) Support multiple theme directories to allow replacement of individual templates rather than copying the full theme. ( #129 ) Bugfix: Fix <ul> rendering in readthedocs theme. ( #171 ) Bugfix: Improve the readthedocs theme on smaller displays. ( #168 ) Bugfix: Relaxed required python package versions to avoid clashes. ( #104 ) Bugfix: Fix issue rendering the table of contents with some configs. ( #146 ) Bugfix: Fix path for embedded images in sub pages. ( #138 ) Bugfix: Fix use_directory_urls config behavior. ( #63 ) Bugfix: Support extra_javascript and extra_css in all themes. ( #90 ) Bugfix: Fix path-handling under Windows. ( #121 ) Bugfix: Fix the menu generation in the readthedocs theme. ( #110 ) Bugfix: Fix the mkdocs command creation under Windows. ( #122 ) Bugfix: Correctly handle external extra_javascript and extra_css . ( #92 ) Bugfix: Fixed favicon support. ( #87 )","title":"Version 0.10.0 (2014-10-29)"},{"location":"dev-guide/","text":"Developer Guide \uf0c1 Extending MkDocs The MkDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the Contributing Guide for information on contributing to MkDocs itself. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Themes Plugins","title":"Overview"},{"location":"dev-guide/#developer-guide","text":"Extending MkDocs The MkDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the Contributing Guide for information on contributing to MkDocs itself. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Themes Plugins","title":"Developer Guide"},{"location":"dev-guide/plugins/","text":"MkDocs Plugins \uf0c1 A Guide to installing, using and creating MkDocs Plugins Installing Plugins \uf0c1 Before a plugin can be used, it must be installed on the system. If you are using a plugin which comes with MkDocs, then it was installed when you installed MkDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using pip : pip install mkdocs-foo-plugin Once a plugin has been successfully installed, it is ready to use. It just needs to be enabled in the configuration file. The MkDocs Plugins wiki page has a growing list of plugins that you can install and use. Using Plugins \uf0c1 The plugins configuration option should contain a list of plugins to use when building the site. Each \"plugin\" must be a string name assigned to the plugin (see the documentation for a given plugin to determine its \"name\"). A plugin listed here must already be installed . plugins: - search Some plugins may 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 plugin supports. Note that a colon ( : ) must follow the plugin name and then on a new line the option name and value must be indented and separated by a colon. If you would like to define multiple options for a single plugin, each option must be defined on a separate line. plugins: - search: lang: en foo: bar For information regarding the configuration options available for a given plugin, see that plugin's documentation. For a list of default plugins and how to override them, see the configuration documentation. Developing Plugins \uf0c1 Like MkDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is possible to define multiple plugins in the same module. At a minimum, a MkDocs Plugin must consist of a BasePlugin subclass and an entry point which points to it. BasePlugin \uf0c1 A subclass of mkdocs.plugins.BasePlugin should define the behavior of the plugin. The class generally consists of actions to perform on specific events in the build process as well as a configuration scheme for the plugin. All BasePlugin subclasses contain the following attributes: config_scheme \uf0c1 A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of mkdocs.config.config_options.BaseConfigOption or any of its subclasses. For example, the following config_scheme defines three configuration options: foo , which accepts a string; bar , which accepts an integer; and baz , which accepts a boolean value. class MyPlugin(mkdocs.plugins.BasePlugin): config_scheme = ( ('foo', mkdocs.config.config_options.Type(str, default='a default value')), ('bar', mkdocs.config.config_options.Type(int, default=0)), ('baz', mkdocs.config.config_options.Type(bool, default=True)) ) When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes provided in mkdocs.config.config_options or a third party subclass defined in the plugin. Any settings provided by the user which fail validation or are not defined in the config_scheme will raise a mkdocs.config.base.ValidationError . config \uf0c1 A dictionary of configuration options for the plugin, which is populated by the load_config method after configuration validation has completed. Use this attribute to access options provided by the user. def on_pre_build(self, config): if self.config['bool_option']: # implement \"bool_option\" functionality here... All BasePlugin subclasses contain the following method(s): load_config(options) \uf0c1 Loads configuration from a dictionary of options. Returns a tuple of (errors, warnings) . This method is called by MkDocs during configuration validation and should not need to be called by the plugin. on_<event_name>() \uf0c1 Optional methods which define the behavior for specific events . The plugin should define its behavior within these methods. Replace <event_name> with the actual name of the event. For example, the pre_build event would be defined in the on_pre_build method. Most events accept one positional argument and various keyword arguments. It is generally expected that the positional argument would be modified (or replaced) by the plugin and returned. If nothing is returned (the method returns None ), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as **kwargs . In the event that additional keywords are provided to an event in a future version of MkDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to the theme config: class MyPlugin(BasePlugin): def on_config(self, config, **kwargs): config['theme'].static_templates.add('my_template.html') return config Events \uf0c1 There are three kinds of events: Global Events , Page Events and Template Events . Global Events \uf0c1 Global events are called once per build at either the beginning or end of the build process. Any changes made in these events will have a global effect on the entire site. on_serve \uf0c1 The serve event is only called when the serve command is used during development. It is passed the Server instance which can be modified before it is activated. For example, additional files or directories could be added to the list of \"watched\" files for auto-reloading. Parameters: server: livereload.Server instance config: global configuration object builder: a callable which gets passed to each call to server.watch Returns: livereload.Server instance on_config \uf0c1 The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here. Parameters: config: global configuration object Returns: global configuration object on_pre_build \uf0c1 The pre_build event does not alter any variables. Use this event to call pre-build scripts. Parameters: config: global configuration object on_files \uf0c1 The files event is called after the files collection is populated from the docs_dir . Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data. Parameters: files: global files collection config: global configuration object Returns: global files collection on_nav \uf0c1 The nav event is called after the site navigation is created and can be used to alter the site navigation. Parameters: nav: global navigation object config: global configuration object files: global files collection Returns: global navigation object on_env \uf0c1 The env event is called after the Jinja template environment is created and can be used to alter the Jinja environment . Parameters: env: global Jinja environment config: global configuration object files: global files collection Returns: global Jinja Environment on_post_build \uf0c1 The post_build event does not alter any variables. Use this event to call post-build scripts. Parameters: config: global configuration object on_build_error \uf0c1 The build_error event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See Handling Errors for more details. Parameters: error: exception raised Template Events \uf0c1 Template events are called once for each non-page template. Each template event will be called for each template defined in the extra_templates config setting as well as any static_templates defined in the theme. All template events are called after the env event and before any page events . on_pre_template \uf0c1 The pre_template event is called immediately after the subject template is loaded and can be used to alter the template. Parameters: template : a Jinja2 Template object template_name : string filename of template config: global configuration object Returns: a Jinja2 Template object on_template_context \uf0c1 The template_context event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only. Parameters: context : dict of template context variables template_name : string filename of template config: global configuration object Returns: dict of template context variables on_post_template \uf0c1 The post_template event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc. Parameters: output_content : output of rendered template as string template_name : string filename of template config: global configuration object Returns: output of rendered template as string Page Events \uf0c1 Page events are called once for each Markdown page included in the site. All page events are called after the post_template event and before the post_build event. on_pre_page \uf0c1 The pre_page event is called before any actions are taken on the subject page and can be used to alter the Page instance. Parameters: page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: mkdocs.nav.Page instance on_page_read_source \uf0c1 The on_page_read_source event can replace the default mechanism to read the contents of a page's source from the filesystem. Parameters: page: mkdocs.nav.Page instance config: global configuration object Returns: The raw source for a page as unicode string. If None is returned, the default loading from a file will be performed. on_page_markdown \uf0c1 The page_markdown event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as page.meta at this point. Parameters: markdown: Markdown source text of page as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: Markdown source text of page as string on_page_content \uf0c1 The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page. Parameters: html: HTML rendered from Markdown source as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: HTML rendered from Markdown source as string on_page_context \uf0c1 The page_context event is called after the context for a page is created and can be used to alter the context for that specific page only. Parameters: context : dict of template context variables page: mkdocs.nav.Page instance config: global configuration object nav: global navigation object Returns: dict of template context variables on_post_page \uf0c1 The post_page event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc. Parameters: output: output of rendered template as string page: mkdocs.nav.Page instance config: global configuration object Returns: output of rendered template as string Handling Errors \uf0c1 MkDocs defines four error types: mkdocs.exceptions.MkDocsException \uf0c1 The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead. mkdocs.exceptions.ConfigurationError \uf0c1 This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's config_scheme . mkdocs.exceptions.BuildError \uf0c1 This error may be raised by MkDocs during the build process. Plugins should not raise this error. mkdocs.exceptions.PluginError \uf0c1 A subclass of mkdocs.exceptions.BuildError which can be raised by plugin events. Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error message. Therefore, MkDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. Therefore, you might want to catch any exceptions within your plugin and raise a PluginError , passing in your own custom-crafted message, so that the build process is aborted with a helpful message. The on_build_error event will be triggered for any exception. For example: from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin class MyPlugin(BasePlugin): def on_post_page(self, output, page, config, **kwargs): try: # some code that could throw a KeyError ... except KeyError as error: raise PluginError(str(error)) def on_build_error(self, error): # some code to clean things up ... Entry Point \uf0c1 Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_points . Add the following to your setup.py script: entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself ( from path.to.some_plugin import SomePluginClass ) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry point. entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] } Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.","title":"Plugins"},{"location":"dev-guide/plugins/#mkdocs-plugins","text":"A Guide to installing, using and creating MkDocs Plugins","title":"MkDocs Plugins"},{"location":"dev-guide/plugins/#installing-plugins","text":"Before a plugin can be used, it must be installed on the system. If you are using a plugin which comes with MkDocs, then it was installed when you installed MkDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using pip : pip install mkdocs-foo-plugin Once a plugin has been successfully installed, it is ready to use. It just needs to be enabled in the configuration file. The MkDocs Plugins wiki page has a growing list of plugins that you can install and use.","title":"Installing Plugins"},{"location":"dev-guide/plugins/#using-plugins","text":"The plugins configuration option should contain a list of plugins to use when building the site. Each \"plugin\" must be a string name assigned to the plugin (see the documentation for a given plugin to determine its \"name\"). A plugin listed here must already be installed . plugins: - search Some plugins may 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 plugin supports. Note that a colon ( : ) must follow the plugin name and then on a new line the option name and value must be indented and separated by a colon. If you would like to define multiple options for a single plugin, each option must be defined on a separate line. plugins: - search: lang: en foo: bar For information regarding the configuration options available for a given plugin, see that plugin's documentation. For a list of default plugins and how to override them, see the configuration documentation.","title":"Using Plugins"},{"location":"dev-guide/plugins/#developing-plugins","text":"Like MkDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is possible to define multiple plugins in the same module. At a minimum, a MkDocs Plugin must consist of a BasePlugin subclass and an entry point which points to it.","title":"Developing Plugins"},{"location":"dev-guide/plugins/#baseplugin","text":"A subclass of mkdocs.plugins.BasePlugin should define the behavior of the plugin. The class generally consists of actions to perform on specific events in the build process as well as a configuration scheme for the plugin. All BasePlugin subclasses contain the following attributes:","title":"BasePlugin"},{"location":"dev-guide/plugins/#config_scheme","text":"A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of mkdocs.config.config_options.BaseConfigOption or any of its subclasses. For example, the following config_scheme defines three configuration options: foo , which accepts a string; bar , which accepts an integer; and baz , which accepts a boolean value. class MyPlugin(mkdocs.plugins.BasePlugin): config_scheme = ( ('foo', mkdocs.config.config_options.Type(str, default='a default value')), ('bar', mkdocs.config.config_options.Type(int, default=0)), ('baz', mkdocs.config.config_options.Type(bool, default=True)) ) When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes provided in mkdocs.config.config_options or a third party subclass defined in the plugin. Any settings provided by the user which fail validation or are not defined in the config_scheme will raise a mkdocs.config.base.ValidationError .","title":"config_scheme"},{"location":"dev-guide/plugins/#config","text":"A dictionary of configuration options for the plugin, which is populated by the load_config method after configuration validation has completed. Use this attribute to access options provided by the user. def on_pre_build(self, config): if self.config['bool_option']: # implement \"bool_option\" functionality here... All BasePlugin subclasses contain the following method(s):","title":"config"},{"location":"dev-guide/plugins/#load_configoptions","text":"Loads configuration from a dictionary of options. Returns a tuple of (errors, warnings) . This method is called by MkDocs during configuration validation and should not need to be called by the plugin.","title":"load_config(options)"},{"location":"dev-guide/plugins/#on_event_name","text":"Optional methods which define the behavior for specific events . The plugin should define its behavior within these methods. Replace <event_name> with the actual name of the event. For example, the pre_build event would be defined in the on_pre_build method. Most events accept one positional argument and various keyword arguments. It is generally expected that the positional argument would be modified (or replaced) by the plugin and returned. If nothing is returned (the method returns None ), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as **kwargs . In the event that additional keywords are provided to an event in a future version of MkDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to the theme config: class MyPlugin(BasePlugin): def on_config(self, config, **kwargs): config['theme'].static_templates.add('my_template.html') return config","title":"on_&lt;event_name&gt;()"},{"location":"dev-guide/plugins/#events","text":"There are three kinds of events: Global Events , Page Events and Template Events .","title":"Events"},{"location":"dev-guide/plugins/#global-events","text":"Global events are called once per build at either the beginning or end of the build process. Any changes made in these events will have a global effect on the entire site.","title":"Global Events"},{"location":"dev-guide/plugins/#on_serve","text":"The serve event is only called when the serve command is used during development. It is passed the Server instance which can be modified before it is activated. For example, additional files or directories could be added to the list of \"watched\" files for auto-reloading. Parameters: server: livereload.Server instance config: global configuration object builder: a callable which gets passed to each call to server.watch Returns: livereload.Server instance","title":"on_serve"},{"location":"dev-guide/plugins/#on_config","text":"The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here. Parameters: config: global configuration object Returns: global configuration object","title":"on_config"},{"location":"dev-guide/plugins/#on_pre_build","text":"The pre_build event does not alter any variables. Use this event to call pre-build scripts. Parameters: config: global configuration object","title":"on_pre_build"},{"location":"dev-guide/plugins/#on_files","text":"The files event is called after the files collection is populated from the docs_dir . Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data. Parameters: files: global files collection config: global configuration object Returns: global files collection","title":"on_files"},{"location":"dev-guide/plugins/#on_nav","text":"The nav event is called after the site navigation is created and can be used to alter the site navigation. Parameters: nav: global navigation object config: global configuration object files: global files collection Returns: global navigation object","title":"on_nav"},{"location":"dev-guide/plugins/#on_env","text":"The env event is called after the Jinja template environment is created and can be used to alter the Jinja environment . Parameters: env: global Jinja environment config: global configuration object files: global files collection Returns: global Jinja Environment","title":"on_env"},{"location":"dev-guide/plugins/#on_post_build","text":"The post_build event does not alter any variables. Use this event to call post-build scripts. Parameters: config: global configuration object","title":"on_post_build"},{"location":"dev-guide/plugins/#on_build_error","text":"The build_error event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See Handling Errors for more details. Parameters: error: exception raised","title":"on_build_error"},{"location":"dev-guide/plugins/#template-events","text":"Template events are called once for each non-page template. Each template event will be called for each template defined in the extra_templates config setting as well as any static_templates defined in the theme. All template events are called after the env event and before any page events .","title":"Template Events"},{"location":"dev-guide/plugins/#on_pre_template","text":"The pre_template event is called immediately after the subject template is loaded and can be used to alter the template. Parameters: template : a Jinja2 Template object template_name : string filename of template config: global configuration object Returns: a Jinja2 Template object","title":"on_pre_template"},{"location":"dev-guide/plugins/#on_template_context","text":"The template_context event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only. Parameters: context : dict of template context variables template_name : string filename of template config: global configuration object Returns: dict of template context variables","title":"on_template_context"},{"location":"dev-guide/plugins/#on_post_template","text":"The post_template event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc. Parameters: output_content : output of rendered template as string template_name : string filename of template config: global configuration object Returns: output of rendered template as string","title":"on_post_template"},{"location":"dev-guide/plugins/#page-events","text":"Page events are called once for each Markdown page included in the site. All page events are called after the post_template event and before the post_build event.","title":"Page Events"},{"location":"dev-guide/plugins/#on_pre_page","text":"The pre_page event is called before any actions are taken on the subject page and can be used to alter the Page instance. Parameters: page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: mkdocs.nav.Page instance","title":"on_pre_page"},{"location":"dev-guide/plugins/#on_page_read_source","text":"The on_page_read_source event can replace the default mechanism to read the contents of a page's source from the filesystem. Parameters: page: mkdocs.nav.Page instance config: global configuration object Returns: The raw source for a page as unicode string. If None is returned, the default loading from a file will be performed.","title":"on_page_read_source"},{"location":"dev-guide/plugins/#on_page_markdown","text":"The page_markdown event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as page.meta at this point. Parameters: markdown: Markdown source text of page as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: Markdown source text of page as string","title":"on_page_markdown"},{"location":"dev-guide/plugins/#on_page_content","text":"The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page. Parameters: html: HTML rendered from Markdown source as string page: mkdocs.nav.Page instance config: global configuration object files: global files collection Returns: HTML rendered from Markdown source as string","title":"on_page_content"},{"location":"dev-guide/plugins/#on_page_context","text":"The page_context event is called after the context for a page is created and can be used to alter the context for that specific page only. Parameters: context : dict of template context variables page: mkdocs.nav.Page instance config: global configuration object nav: global navigation object Returns: dict of template context variables","title":"on_page_context"},{"location":"dev-guide/plugins/#on_post_page","text":"The post_page event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc. Parameters: output: output of rendered template as string page: mkdocs.nav.Page instance config: global configuration object Returns: output of rendered template as string","title":"on_post_page"},{"location":"dev-guide/plugins/#handling-errors","text":"MkDocs defines four error types:","title":"Handling Errors"},{"location":"dev-guide/plugins/#mkdocsexceptionsmkdocsexception","text":"The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead.","title":"mkdocs.exceptions.MkDocsException"},{"location":"dev-guide/plugins/#mkdocsexceptionsconfigurationerror","text":"This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's config_scheme .","title":"mkdocs.exceptions.ConfigurationError"},{"location":"dev-guide/plugins/#mkdocsexceptionsbuilderror","text":"This error may be raised by MkDocs during the build process. Plugins should not raise this error.","title":"mkdocs.exceptions.BuildError"},{"location":"dev-guide/plugins/#mkdocsexceptionspluginerror","text":"A subclass of mkdocs.exceptions.BuildError which can be raised by plugin events. Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error message. Therefore, MkDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. Therefore, you might want to catch any exceptions within your plugin and raise a PluginError , passing in your own custom-crafted message, so that the build process is aborted with a helpful message. The on_build_error event will be triggered for any exception. For example: from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin class MyPlugin(BasePlugin): def on_post_page(self, output, page, config, **kwargs): try: # some code that could throw a KeyError ... except KeyError as error: raise PluginError(str(error)) def on_build_error(self, error): # some code to clean things up ...","title":"mkdocs.exceptions.PluginError"},{"location":"dev-guide/plugins/#entry-point","text":"Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_points . Add the following to your setup.py script: entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself ( from path.to.some_plugin import SomePluginClass ) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry point. entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] } Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.","title":"Entry Point"},{"location":"dev-guide/themes/","text":"Developing Themes \uf0c1 A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage. Creating a custom theme \uf0c1 The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \"mkdocs\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme. Basic theme \uf0c1 The simplest main.html file is the following: <!DOCTYPE html> <html> <head> <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title> </head> <body> {{ page.content }} </body> </html> The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency. Theme Files \uf0c1 There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file. Template Files \uf0c1 Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension. Theme Meta Files \uf0c1 The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files. Dot Files \uf0c1 Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt Documentation Files \uf0c1 All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored. Template Variables \uf0c1 Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html. Global Context \uf0c1 The following variables are available globally on any template. config \uf0c1 The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics nav \uf0c1 The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes: nav.homepage \uf0c1 The page object for the homepage of the site. nav.pages \uf0c1 A flat list of all page objects contained in the navigation. This list is not necessarily a complete list of all site pages as it does not contain pages which are not included in the navigation. This list does match the list and order of pages used for all \"next page\" and \"previous page\" links. For a list of all pages, use the pages template variable. Nav Example \uf0c1 Following is a basic usage example which outputs the first and second level navigation as a nested list. {% if nav|length>1 %} <ul> {% for nav_item in nav %} {% if nav_item.children %} <li>{{ nav_item.title }} <ul> {% for nav_item in nav_item.children %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endfor %} </ul> </li> {% else %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endif %} {% endfor %} </ul> {% endif %} base_url \uf0c1 The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url . mkdocs_version \uf0c1 Contains the current MkDocs version. build_date_utc \uf0c1 A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated. pages \uf0c1 A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page . page \uf0c1 In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes: page.title \uf0c1 Contains the Title for the current page. page.content \uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. page.toc \uf0c1 An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink which contains the following attributes: AnchorLink.title : The text of the item. AnchorLink.url : The hash fragment of a URL pointing to the item. AnchorLink.level : The zero-based level of the item. AnchorLink.children : An iterable of any child items. The following example would display the top two levels of the Table of Contents for a page. <ul> {% for toc_item in page.toc %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% for toc_item in toc_item.children %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% endfor %} {% endfor %} </ul> page.meta \uf0c1 A mapping of the metadata included at the top of the markdown page. In this example we define a source property above the page title. source: generics.py mixins.py # Page title Content... A template can access this metadata for the page with the meta.source variable. This could then be used to link to source files related to the documentation page. {% for filename in page.meta.source %} <a class=\"github\" href=\"https://github.com/.../{{ filename }}\"> <span class=\"label label-info\">{{ filename }}</span> </a> {% endfor %} page.url \uf0c1 The URL of the page relative to the MkDocs site_dir . It is expected that this be used with the url filter to ensure the URL is relative to the current page. <a href=\"{{ page.url|url }}\">{{ page.title }}</a> page.abs_url \uf0c1 The absolute URL of the page from the server root as determined by the value assigned to the site_url configuration setting. The value includes any subdirectory included in the site_url , but not the domain. base_url should not be used with this variable. For example, if site_url: https://example.com/ , then the value of page.abs_url for the page foo.md would be /foo/ . However, if site_url: https://example.com/bar/ , then the value of page.abs_url for the page foo.md would be /bar/foo/ . page.canonical_url \uf0c1 The full, canonical URL to the current page as determined by the value assigned to the site_url configuration setting. The value includes the domain and any subdirectory included in the site_url . base_url should not be used with this variable. page.edit_url \uf0c1 The full URL to the source page in the source repository. Typically used to provide a link to edit the source page. base_url should not be used with this variable. page.is_homepage \uf0c1 Evaluates to True for the homepage of the site and False for all other pages. This can be used in conjunction with other attributes of the page object to alter the behavior. For example, to display a different title on the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }} page.previous_page \uf0c1 The page object for the previous page or None . The value will be None if the current page is the first item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page . page.next_page \uf0c1 The page object for the next page or None . The value will be None if the current page is the last item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page . page.parent \uf0c1 The immediate parent of the page in the site navigation . None if the page is at the top level. page.children \uf0c1 Pages do not contain children and the attribute is always None . page.active \uf0c1 When True , indicates that this page is the currently viewed page. Defaults to False . page.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for page objects. page.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always True for page objects. page.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for page objects. Navigation Objects \uf0c1 Navigation objects contained in the nav template variable may be one of section objects, page objects, and link objects. While section objects may contain nested navigation objects, pages and links do not. Page objects are the full page object as used for the current page with all of the same attributes available. Section and Link objects contain a subset of those attributes as defined below: Section \uf0c1 A section navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain URLs and are not links of any kind. However, by default, MkDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. The following attributes are available on section objects: section.title \uf0c1 The title of the section. section.parent \uf0c1 The immediate parent of the section or None if the section is at the top level. section.children \uf0c1 An iterable of all child navigation objects. Children may include nested sections, pages and links. section.active \uf0c1 When True , indicates that a child page of this section is the current page and can be used to highlight the section as the currently viewed section. Defaults to False . section.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always True for section objects. section.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for section objects. section.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for section objects. Link \uf0c1 A link navigation object contains a link which does not point to an internal MkDocs page. The following attributes are available on link objects: link.title \uf0c1 The title of the link. This would generally be used as the label of the link. link.url \uf0c1 The URL that the link points to. The URL should always be an absolute URLs and should not need to have base_url prepended. link.parent \uf0c1 The immediate parent of the link. None if the link is at the top level. link.children \uf0c1 Links do not contain children and the attribute is always None . link.active \uf0c1 External links cannot be \"active\" and the attribute is always False . link.is_section \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for link objects. link.is_page \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for link objects. link.is_link \uf0c1 Indicates that the navigation object is a \"link\" object. Always True for link objects. Extra Context \uf0c1 Additional variables can be passed to the template with the extra configuration option. This is a set of key value pairs that can make custom templates far more flexible. For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following extra configuration: extra: version: 0.13.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - https://www.mkdocs.org/ And then displayed with this HTML in the custom theme. {{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %} Template Filters \uf0c1 In addition to Jinja's default filters , the following custom filters are available to use in MkDocs templates: url \uf0c1 Normalizes a URL. Absolute URLs are passed through unaltered. If the URL is relative and the template context includes a page object, then the URL is returned relative to the page object. Otherwise, the URL is returned with base_url prepended. <a href=\"{{ page.url|url }}\">{{ page.title }}</a> tojson \uf0c1 Safety convert a Python object to a value in a JavaScript script. <script> var mkdocs_page_name = {{ page.title|tojson|safe }}; </script> Search and themes \uf0c1 As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. <script>var base_url = '{{ base_url }}';</script> With properly configured settings, the following HTML in a template will add a full search implementation to your theme. <h1 id=\"search\">Search Results</h1> <form action=\"search.html\"> <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" > </form> <div id=\"mkdocs-search-results\"> Sorry, page not found. </div> The JavaScript in the plugin works by looking for the specific ID's used in the above HTML. The form input for the user to type the search query must be identified with id=\"mkdocs-search-query\" and the div where the results will be placed must be identified with id=\"mkdocs-search-results\" . The plugin supports the following options being set in the theme's configuration file , mkdocs_theme.yml : include_search_page \uf0c1 Determines whether the search plugin expects the theme to provide a dedicated search page via a template located at search/search.html . When include_search_page is set to true , the search template will be built and available at search/search.html . This method is used by the readthedocs theme. When include_search_page is set to false or not defined, it is expected that the theme provide some other mechanisms for displaying search results. For example, the mkdocs theme displays results on any page via a modal. search_index_only \uf0c1 Determines whether the search plugin should only generate a search index or a complete search solution. When search_index_only is set to false , then the search plugin modifies the Jinja environment by adding its own templates directory (with a lower precedence than the theme) and adds its scripts to the extra_javascript config setting. When search_index_only is set to true or not defined, the search plugin makes no modifications to the Jinja environment. A complete solution using the provided index file is the responsibility of the theme. The search index is written to a JSON file at search/search_index.json in the site_dir . The JSON object contained within the file may contain up to three objects. { config: {...}, data: [...], index: {...} } If present, the config object contains the key/value pairs of config options defined for the plugin in the user's mkdocs.yml config file under plugings.search . The config object was new in MkDocs version 1.0 . The data object contains a list of document objects. Each document object is made up of a location (URL), a title , and text which can be used to create a search index and/or display search results. If present, the index object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the prebuild_index config option. Themes should expect the index to not be present, but can choose to use the index when it is available. The index object was new in MkDocs version 1.0 . Packaging Themes \uf0c1 MkDocs makes use of Python packaging to distribute themes. This comes with a few requirements. To see an example of a package containing one theme, see the MkDocs Bootstrap theme and to see a package that contains many themes, see the MkDocs Bootswatch theme . Note It is not strictly necessary to package a theme, as the entire theme can be contained in the custom_dir . If you have created a \"one-off theme,\" that should be sufficient. However, if you intend to distribute your theme for others to use, packaging the theme has some advantages. By packaging your theme, your users can more easily install it, they can rely on a default configuration being defined, and they can then take advantage of the custom_dir to make tweaks to your theme to better suit their needs. Package Layout \uf0c1 The following layout is recommended for themes. Two files at the top level directory called MANIFEST.in and setup.py beside the theme directory which contains an empty __init__.py file, a theme configuration file ( mkdocs-theme.yml ), and your template and media files. . |-- MANIFEST.in |-- theme_name | |-- __init__.py | |-- mkdocs-theme.yml | |-- main.html | |-- styles.css `-- setup.py The MANIFEST.in file should contain the following contents but with theme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff recursive-exclude * __pycache__ recursive-exclude * *.py[co] The setup.py should include the following text with the modifications described below. from setuptools import setup, find_packages VERSION = '0.0.1' setup( name=\"mkdocs-themename\", version=VERSION, url='', license='', description='', author='', author_email='', packages=find_packages(), include_package_data=True, entry_points={ 'mkdocs.themes': [ 'themename = theme_name', ] }, zip_safe=False ) Fill in the URL, license, description, author and author email address. The name should follow the convention mkdocs-themename (like mkdocs-bootstrap and mkdocs-bootswatch ), starting with MkDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to change is the entry_points. This is how MkDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. The directory you created at the start of this section with the main.html file should contain all of the other theme files. The minimum requirement is that it includes a main.html for the theme. It must also include a __init__.py file which should be empty, this file tells Python that the directory is a package. Theme Configuration \uf0c1 A packaged theme is required to include a configuration file named mkdocs_theme.yml which is placed in the root of your template files. The file should contain default configuration options for the theme. However, if the theme offers no configuration options, the file is still required and can be left blank. A theme which is not packaged does not need a mkdocs_theme.yml file as that file is not loaded from theme.custom_dir . The theme author is free to define any arbitrary options deemed necessary and those options will be made available in the templates to control behavior. For example, a theme might want to make a sidebar optional and include the following in the mkdocs_theme.yml file: show_sidebar: true Then in a template, that config option could be referenced: {% if config.theme.show_sidebar %} <div id=\"sidebar\">...</div> {% endif %} And the user could override the default in their project's mkdocs.yml config file: theme: name: themename show_sidebar: false In addition to arbitrary options defined by the theme, MkDocs defines a few special options which alters its behavior: locale \uf0c1 This option mirrors the theme config option of the same name. If this value is not defined in the mkdocs_theme.yml file and the user does not set it in mkdocs.yml then it will default to en (English). The value is expected to match the language used in the text provided by the theme (such a \"next\" and \"previous\" links) and should be used as the value of the <html> tag's lang attribute. See Supporting theme localization/ translation for more information. Note that during configuration validation, the provided string is converted to a Locale object. The object contains Locale.language and Locale.territory attributes and will resolve as a string from within a template. Therefore, the following will work fine: <html lang=\"{ config.theme.locale }\"> If the locale was set to fr_CA (Canadian French), then the above template would render as: <html lang=\"fr_CA\"> If you did not want the territory attribute to be included, then reference the language attribute directly: <html lang=\"{ config.theme.locale.language }\"> That would render as: <html lang=\"fr\"> static_templates \uf0c1 This option mirrors the theme config option of the same name and allows some defaults to be set by the theme. Note that while the user can add templates to this list, the user cannot remove templates included in the theme's config. extends \uf0c1 Defines a parent theme that this theme inherits from. The value should be the string name of the parent theme. Normal Jinja inheritance rules apply. Plugins may also define some options which allow the theme to inform a plugin about which set of plugin options it expects. See the documentation for any plugins you may wish to support in your theme. Distributing Themes \uf0c1 With the above changes, your theme should now be ready to install. This can be done with pip, using pip install . if you are still in the same directory as the setup.py. Most Python packages, including MkDocs, are distributed on PyPI. To do this, you should run the following command. python setup.py register If you don't have an account setup, you should be prompted to create one. For a much more detailed guide, see the official Python packaging documentation for Packaging and Distributing Projects . Supporting theme Localization/Translation \uf0c1 While the built-in themes provide support for localization/translation of templates, custom themes and third-party themes may choose not to. Regardless, the locale setting of the theme configuration option is always present and is relied upon by other parts of the system. Therefore, it is recommended that all third-party themes use the same setting for designating a language regardless of the system they use for translation. In that way, users will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the same commands utilized by MkDocs. Enabling the Localization/Translation commands \uf0c1 MkDocs includes some helper commands which are light wrappers around pybabel's commands . To use the commands on your own theme, add the following to your theme's setup.py script: from mkdocs.commands.setup import babel_cmdclass setup( ... cmdclass=babel_cmdclass ) Note that cmdclass=babel_cmdclass was added an a parameter passed to the setup function. Warning As pybabel is not installed by default and most users will not have pybabel installed, theme developers and/or translators should make sure to have installed the necessary dependencies (using pip install mkdocs[i18n] ) in order for the commands to be available for use. Using the Localization/Translation commands \uf0c1 Since the translation commands are embedded in the setup.py script of your custom theme they should be called from the root of your theme's working tree as follows: python setup.py <command_name> [OPTIONS] Each command provides a detailed list of options available with the -h/--help option. For an overview of the workflow used by MkDocs to translate the built-in themes, see the appropriate section of the Contributing Guide and the Translation Guide . Default values for many of the options to the commands can be defined in a setup.cfg file. Create a section using the command name as the section name, and the long option name as the key. See MkDocs' own setup.cfg file for an example. A summary of changes/additions to the behavior and options of the upstream pybabel commands are summarized below. compile_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value of the -d/--directory option. The --directory option is set to {theme_dir}/locales . If a directory is passed to the --directory option, then the theme option is ignored. extract_messages \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the --input-dirs and --output-file options. The --input-dirs option is set to the theme directory and --output-file is set to {theme_dir}/{domain}.pot . If a path is provided to either option, then the theme option is ignored for that option. The --domain option has been added to this command and can be used to override the domain used for the output-file based on the theme . Defaults to messages . The -F/--mapping-file option defaults to the mapping file used by MkDocs' built-in themes. However, if that mapping file does not meet your theme's needs to can override it by providing your own and passing the path of that file into the option. init_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option. update_catalog \uf0c1 The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option. Example custom theme Localization/Translation workflow \uf0c1 Note If your theme inherits from an existing theme which already provides translation catalogs, your theme's translations will be merged with the parent theme's translations during a MkDocs build. This means that you only need to concentrate on the added translations. Yet, you will still benefit from the translations of the parent theme. At the same time, you may override any of parent theme's translations! Let's suppose that you're working on your own fork of the mkdocs-basic-theme and want to add translations to it. You would first modify the setup.py like this: --- a/setup.py +++ b/setup.py @@ -1,4 +1,5 @@ from setuptools import setup, find_packages +from mkdocs.commands.setup import babel_cmdclass VERSION = '1.1' @@ -18,5 +19,6 @@ setup( 'basictheme = basic_theme', ] }, - zip_safe=False + zip_safe=False, + cmdclass=babel_cmdclass ) Next, you would edit the templates by wrapping text in your HTML sources with {% trans %} and {% endtrans %} as follows: --- a/basic_theme/base.html +++ b/basic_theme/base.html @@ -88,7 +88,7 @@ <body> - <h1>This is an example theme for MkDocs.</h1> + <h1>{% trans %}This is an example theme for MkDocs.{% endtrans %}</h1> <p> It is designed to be read by looking at the theme HTML which is heavily Then you would follow the Translation Guide as usual to get your translations running. Packaging Translations with your theme \uf0c1 While the Portable Object Template ( pot ) file created by the extract_messages command and the Portable Object ( po ) files created by the init_catalog and update_catalog commands are useful for creating and editing translations, they are not used by MkDocs directly and do not need to be included in a packaged release of a theme. When MkDocs builds a site with translations, it only makes use of the binary mo files(s) for the specified locale. Therefore, when packaging a theme , you would need to make the following addition to your MANIFEST.in file: recursive-include theme_name *.mo Then, before building your Python package, you will want to ensure that the binary mo file for each locale is up-to-date by running the compile_catalog command for each locale. MkDocs expects the binary mo files to be located at locales/<locale>/LC_MESSAGES/messages.mo , which the compile_catalog command automatically does for you. See Testing theme translations for details. Note As outlined in our Translation Guide , the MkDocs project has chosen to include the pot and po files in our code repository, but not the mo files. This requires us to always run compile_catalog before packaging a new release regardless of whether any changes were made to a translation or not. However, you may chose an alternate workflow for your theme. At a minimum, you need to ensure that up-to-date mo files are included at the correct location in each release. However, you may use a different process for generating those mo files if you chose to do so.","title":"Themes"},{"location":"dev-guide/themes/#developing-themes","text":"A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage.","title":"Developing Themes"},{"location":"dev-guide/themes/#creating-a-custom-theme","text":"The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \"mkdocs\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme.","title":"Creating a custom theme"},{"location":"dev-guide/themes/#basic-theme","text":"The simplest main.html file is the following: <!DOCTYPE html> <html> <head> <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title> </head> <body> {{ page.content }} </body> </html> The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency.","title":"Basic theme"},{"location":"dev-guide/themes/#theme-files","text":"There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file.","title":"Theme Files"},{"location":"dev-guide/themes/#template-files","text":"Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension.","title":"Template Files"},{"location":"dev-guide/themes/#theme-meta-files","text":"The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files.","title":"Theme Meta Files"},{"location":"dev-guide/themes/#dot-files","text":"Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt","title":"Dot Files"},{"location":"dev-guide/themes/#documentation-files","text":"All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored.","title":"Documentation Files"},{"location":"dev-guide/themes/#template-variables","text":"Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html.","title":"Template Variables"},{"location":"dev-guide/themes/#global-context","text":"The following variables are available globally on any template.","title":"Global Context"},{"location":"dev-guide/themes/#config","text":"The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics","title":"config"},{"location":"dev-guide/themes/#nav","text":"The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes:","title":"nav"},{"location":"dev-guide/themes/#navhomepage","text":"The page object for the homepage of the site.","title":"nav.homepage"},{"location":"dev-guide/themes/#navpages","text":"A flat list of all page objects contained in the navigation. This list is not necessarily a complete list of all site pages as it does not contain pages which are not included in the navigation. This list does match the list and order of pages used for all \"next page\" and \"previous page\" links. For a list of all pages, use the pages template variable.","title":"nav.pages"},{"location":"dev-guide/themes/#nav-example","text":"Following is a basic usage example which outputs the first and second level navigation as a nested list. {% if nav|length>1 %} <ul> {% for nav_item in nav %} {% if nav_item.children %} <li>{{ nav_item.title }} <ul> {% for nav_item in nav_item.children %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endfor %} </ul> </li> {% else %} <li class=\"{% if nav_item.active%}current{% endif %}\"> <a href=\"{{ nav_item.url|url }}\">{{ nav_item.title }}</a> </li> {% endif %} {% endfor %} </ul> {% endif %}","title":"Nav Example"},{"location":"dev-guide/themes/#base_url","text":"The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url .","title":"base_url"},{"location":"dev-guide/themes/#mkdocs_version","text":"Contains the current MkDocs version.","title":"mkdocs_version"},{"location":"dev-guide/themes/#build_date_utc","text":"A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated.","title":"build_date_utc"},{"location":"dev-guide/themes/#pages","text":"A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page .","title":"pages"},{"location":"dev-guide/themes/#page","text":"In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes:","title":"page"},{"location":"dev-guide/themes/#pagetitle","text":"Contains the Title for the current page.","title":"page.title"},{"location":"dev-guide/themes/#pagecontent","text":"The rendered Markdown as HTML, this is the contents of the documentation.","title":"page.content"},{"location":"dev-guide/themes/#pagetoc","text":"An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink which contains the following attributes: AnchorLink.title : The text of the item. AnchorLink.url : The hash fragment of a URL pointing to the item. AnchorLink.level : The zero-based level of the item. AnchorLink.children : An iterable of any child items. The following example would display the top two levels of the Table of Contents for a page. <ul> {% for toc_item in page.toc %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% for toc_item in toc_item.children %} <li><a href=\"{{ toc_item.url }}\">{{ toc_item.title }}</a></li> {% endfor %} {% endfor %} </ul>","title":"page.toc"},{"location":"dev-guide/themes/#pagemeta","text":"A mapping of the metadata included at the top of the markdown page. In this example we define a source property above the page title. source: generics.py mixins.py # Page title Content... A template can access this metadata for the page with the meta.source variable. This could then be used to link to source files related to the documentation page. {% for filename in page.meta.source %} <a class=\"github\" href=\"https://github.com/.../{{ filename }}\"> <span class=\"label label-info\">{{ filename }}</span> </a> {% endfor %}","title":"page.meta"},{"location":"dev-guide/themes/#pageurl","text":"The URL of the page relative to the MkDocs site_dir . It is expected that this be used with the url filter to ensure the URL is relative to the current page. <a href=\"{{ page.url|url }}\">{{ page.title }}</a>","title":"page.url"},{"location":"dev-guide/themes/#pageabs_url","text":"The absolute URL of the page from the server root as determined by the value assigned to the site_url configuration setting. The value includes any subdirectory included in the site_url , but not the domain. base_url should not be used with this variable. For example, if site_url: https://example.com/ , then the value of page.abs_url for the page foo.md would be /foo/ . However, if site_url: https://example.com/bar/ , then the value of page.abs_url for the page foo.md would be /bar/foo/ .","title":"page.abs_url"},{"location":"dev-guide/themes/#pagecanonical_url","text":"The full, canonical URL to the current page as determined by the value assigned to the site_url configuration setting. The value includes the domain and any subdirectory included in the site_url . base_url should not be used with this variable.","title":"page.canonical_url"},{"location":"dev-guide/themes/#pageedit_url","text":"The full URL to the source page in the source repository. Typically used to provide a link to edit the source page. base_url should not be used with this variable.","title":"page.edit_url"},{"location":"dev-guide/themes/#pageis_homepage","text":"Evaluates to True for the homepage of the site and False for all other pages. This can be used in conjunction with other attributes of the page object to alter the behavior. For example, to display a different title on the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}","title":"page.is_homepage"},{"location":"dev-guide/themes/#pageprevious_page","text":"The page object for the previous page or None . The value will be None if the current page is the first item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page .","title":"page.previous_page"},{"location":"dev-guide/themes/#pagenext_page","text":"The page object for the next page or None . The value will be None if the current page is the last item in the site navigation or if the current page is not included in the navigation at all. When the value is a page object, the usage is the same as for page .","title":"page.next_page"},{"location":"dev-guide/themes/#pageparent","text":"The immediate parent of the page in the site navigation . None if the page is at the top level.","title":"page.parent"},{"location":"dev-guide/themes/#pagechildren","text":"Pages do not contain children and the attribute is always None .","title":"page.children"},{"location":"dev-guide/themes/#pageactive","text":"When True , indicates that this page is the currently viewed page. Defaults to False .","title":"page.active"},{"location":"dev-guide/themes/#pageis_section","text":"Indicates that the navigation object is a \"section\" object. Always False for page objects.","title":"page.is_section"},{"location":"dev-guide/themes/#pageis_page","text":"Indicates that the navigation object is a \"page\" object. Always True for page objects.","title":"page.is_page"},{"location":"dev-guide/themes/#pageis_link","text":"Indicates that the navigation object is a \"link\" object. Always False for page objects.","title":"page.is_link"},{"location":"dev-guide/themes/#navigation-objects","text":"Navigation objects contained in the nav template variable may be one of section objects, page objects, and link objects. While section objects may contain nested navigation objects, pages and links do not. Page objects are the full page object as used for the current page with all of the same attributes available. Section and Link objects contain a subset of those attributes as defined below:","title":"Navigation Objects"},{"location":"dev-guide/themes/#section","text":"A section navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain URLs and are not links of any kind. However, by default, MkDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. The following attributes are available on section objects:","title":"Section"},{"location":"dev-guide/themes/#sectiontitle","text":"The title of the section.","title":"section.title"},{"location":"dev-guide/themes/#sectionparent","text":"The immediate parent of the section or None if the section is at the top level.","title":"section.parent"},{"location":"dev-guide/themes/#sectionchildren","text":"An iterable of all child navigation objects. Children may include nested sections, pages and links.","title":"section.children"},{"location":"dev-guide/themes/#sectionactive","text":"When True , indicates that a child page of this section is the current page and can be used to highlight the section as the currently viewed section. Defaults to False .","title":"section.active"},{"location":"dev-guide/themes/#sectionis_section","text":"Indicates that the navigation object is a \"section\" object. Always True for section objects.","title":"section.is_section"},{"location":"dev-guide/themes/#sectionis_page","text":"Indicates that the navigation object is a \"page\" object. Always False for section objects.","title":"section.is_page"},{"location":"dev-guide/themes/#sectionis_link","text":"Indicates that the navigation object is a \"link\" object. Always False for section objects.","title":"section.is_link"},{"location":"dev-guide/themes/#link","text":"A link navigation object contains a link which does not point to an internal MkDocs page. The following attributes are available on link objects:","title":"Link"},{"location":"dev-guide/themes/#linktitle","text":"The title of the link. This would generally be used as the label of the link.","title":"link.title"},{"location":"dev-guide/themes/#linkurl","text":"The URL that the link points to. The URL should always be an absolute URLs and should not need to have base_url prepended.","title":"link.url"},{"location":"dev-guide/themes/#linkparent","text":"The immediate parent of the link. None if the link is at the top level.","title":"link.parent"},{"location":"dev-guide/themes/#linkchildren","text":"Links do not contain children and the attribute is always None .","title":"link.children"},{"location":"dev-guide/themes/#linkactive","text":"External links cannot be \"active\" and the attribute is always False .","title":"link.active"},{"location":"dev-guide/themes/#linkis_section","text":"Indicates that the navigation object is a \"section\" object. Always False for link objects.","title":"link.is_section"},{"location":"dev-guide/themes/#linkis_page","text":"Indicates that the navigation object is a \"page\" object. Always False for link objects.","title":"link.is_page"},{"location":"dev-guide/themes/#linkis_link","text":"Indicates that the navigation object is a \"link\" object. Always True for link objects.","title":"link.is_link"},{"location":"dev-guide/themes/#extra-context","text":"Additional variables can be passed to the template with the extra configuration option. This is a set of key value pairs that can make custom templates far more flexible. For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following extra configuration: extra: version: 0.13.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - https://www.mkdocs.org/ And then displayed with this HTML in the custom theme. {{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %}","title":"Extra Context"},{"location":"dev-guide/themes/#template-filters","text":"In addition to Jinja's default filters , the following custom filters are available to use in MkDocs templates:","title":"Template Filters"},{"location":"dev-guide/themes/#url","text":"Normalizes a URL. Absolute URLs are passed through unaltered. If the URL is relative and the template context includes a page object, then the URL is returned relative to the page object. Otherwise, the URL is returned with base_url prepended. <a href=\"{{ page.url|url }}\">{{ page.title }}</a>","title":"url"},{"location":"dev-guide/themes/#tojson","text":"Safety convert a Python object to a value in a JavaScript script. <script> var mkdocs_page_name = {{ page.title|tojson|safe }}; </script>","title":"tojson"},{"location":"dev-guide/themes/#search-and-themes","text":"As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. <script>var base_url = '{{ base_url }}';</script> With properly configured settings, the following HTML in a template will add a full search implementation to your theme. <h1 id=\"search\">Search Results</h1> <form action=\"search.html\"> <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" > </form> <div id=\"mkdocs-search-results\"> Sorry, page not found. </div> The JavaScript in the plugin works by looking for the specific ID's used in the above HTML. The form input for the user to type the search query must be identified with id=\"mkdocs-search-query\" and the div where the results will be placed must be identified with id=\"mkdocs-search-results\" . The plugin supports the following options being set in the theme's configuration file , mkdocs_theme.yml :","title":"Search and themes"},{"location":"dev-guide/themes/#include_search_page","text":"Determines whether the search plugin expects the theme to provide a dedicated search page via a template located at search/search.html . When include_search_page is set to true , the search template will be built and available at search/search.html . This method is used by the readthedocs theme. When include_search_page is set to false or not defined, it is expected that the theme provide some other mechanisms for displaying search results. For example, the mkdocs theme displays results on any page via a modal.","title":"include_search_page"},{"location":"dev-guide/themes/#search_index_only","text":"Determines whether the search plugin should only generate a search index or a complete search solution. When search_index_only is set to false , then the search plugin modifies the Jinja environment by adding its own templates directory (with a lower precedence than the theme) and adds its scripts to the extra_javascript config setting. When search_index_only is set to true or not defined, the search plugin makes no modifications to the Jinja environment. A complete solution using the provided index file is the responsibility of the theme. The search index is written to a JSON file at search/search_index.json in the site_dir . The JSON object contained within the file may contain up to three objects. { config: {...}, data: [...], index: {...} } If present, the config object contains the key/value pairs of config options defined for the plugin in the user's mkdocs.yml config file under plugings.search . The config object was new in MkDocs version 1.0 . The data object contains a list of document objects. Each document object is made up of a location (URL), a title , and text which can be used to create a search index and/or display search results. If present, the index object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the prebuild_index config option. Themes should expect the index to not be present, but can choose to use the index when it is available. The index object was new in MkDocs version 1.0 .","title":"search_index_only"},{"location":"dev-guide/themes/#packaging-themes","text":"MkDocs makes use of Python packaging to distribute themes. This comes with a few requirements. To see an example of a package containing one theme, see the MkDocs Bootstrap theme and to see a package that contains many themes, see the MkDocs Bootswatch theme . Note It is not strictly necessary to package a theme, as the entire theme can be contained in the custom_dir . If you have created a \"one-off theme,\" that should be sufficient. However, if you intend to distribute your theme for others to use, packaging the theme has some advantages. By packaging your theme, your users can more easily install it, they can rely on a default configuration being defined, and they can then take advantage of the custom_dir to make tweaks to your theme to better suit their needs.","title":"Packaging Themes"},{"location":"dev-guide/themes/#package-layout","text":"The following layout is recommended for themes. Two files at the top level directory called MANIFEST.in and setup.py beside the theme directory which contains an empty __init__.py file, a theme configuration file ( mkdocs-theme.yml ), and your template and media files. . |-- MANIFEST.in |-- theme_name | |-- __init__.py | |-- mkdocs-theme.yml | |-- main.html | |-- styles.css `-- setup.py The MANIFEST.in file should contain the following contents but with theme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff recursive-exclude * __pycache__ recursive-exclude * *.py[co] The setup.py should include the following text with the modifications described below. from setuptools import setup, find_packages VERSION = '0.0.1' setup( name=\"mkdocs-themename\", version=VERSION, url='', license='', description='', author='', author_email='', packages=find_packages(), include_package_data=True, entry_points={ 'mkdocs.themes': [ 'themename = theme_name', ] }, zip_safe=False ) Fill in the URL, license, description, author and author email address. The name should follow the convention mkdocs-themename (like mkdocs-bootstrap and mkdocs-bootswatch ), starting with MkDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to change is the entry_points. This is how MkDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. The directory you created at the start of this section with the main.html file should contain all of the other theme files. The minimum requirement is that it includes a main.html for the theme. It must also include a __init__.py file which should be empty, this file tells Python that the directory is a package.","title":"Package Layout"},{"location":"dev-guide/themes/#theme-configuration","text":"A packaged theme is required to include a configuration file named mkdocs_theme.yml which is placed in the root of your template files. The file should contain default configuration options for the theme. However, if the theme offers no configuration options, the file is still required and can be left blank. A theme which is not packaged does not need a mkdocs_theme.yml file as that file is not loaded from theme.custom_dir . The theme author is free to define any arbitrary options deemed necessary and those options will be made available in the templates to control behavior. For example, a theme might want to make a sidebar optional and include the following in the mkdocs_theme.yml file: show_sidebar: true Then in a template, that config option could be referenced: {% if config.theme.show_sidebar %} <div id=\"sidebar\">...</div> {% endif %} And the user could override the default in their project's mkdocs.yml config file: theme: name: themename show_sidebar: false In addition to arbitrary options defined by the theme, MkDocs defines a few special options which alters its behavior:","title":"Theme Configuration"},{"location":"dev-guide/themes/#locale","text":"This option mirrors the theme config option of the same name. If this value is not defined in the mkdocs_theme.yml file and the user does not set it in mkdocs.yml then it will default to en (English). The value is expected to match the language used in the text provided by the theme (such a \"next\" and \"previous\" links) and should be used as the value of the <html> tag's lang attribute. See Supporting theme localization/ translation for more information. Note that during configuration validation, the provided string is converted to a Locale object. The object contains Locale.language and Locale.territory attributes and will resolve as a string from within a template. Therefore, the following will work fine: <html lang=\"{ config.theme.locale }\"> If the locale was set to fr_CA (Canadian French), then the above template would render as: <html lang=\"fr_CA\"> If you did not want the territory attribute to be included, then reference the language attribute directly: <html lang=\"{ config.theme.locale.language }\"> That would render as: <html lang=\"fr\">","title":"locale"},{"location":"dev-guide/themes/#static_templates","text":"This option mirrors the theme config option of the same name and allows some defaults to be set by the theme. Note that while the user can add templates to this list, the user cannot remove templates included in the theme's config.","title":"static_templates"},{"location":"dev-guide/themes/#extends","text":"Defines a parent theme that this theme inherits from. The value should be the string name of the parent theme. Normal Jinja inheritance rules apply. Plugins may also define some options which allow the theme to inform a plugin about which set of plugin options it expects. See the documentation for any plugins you may wish to support in your theme.","title":"extends"},{"location":"dev-guide/themes/#distributing-themes","text":"With the above changes, your theme should now be ready to install. This can be done with pip, using pip install . if you are still in the same directory as the setup.py. Most Python packages, including MkDocs, are distributed on PyPI. To do this, you should run the following command. python setup.py register If you don't have an account setup, you should be prompted to create one. For a much more detailed guide, see the official Python packaging documentation for Packaging and Distributing Projects .","title":"Distributing Themes"},{"location":"dev-guide/themes/#supporting-theme-localizationtranslation","text":"While the built-in themes provide support for localization/translation of templates, custom themes and third-party themes may choose not to. Regardless, the locale setting of the theme configuration option is always present and is relied upon by other parts of the system. Therefore, it is recommended that all third-party themes use the same setting for designating a language regardless of the system they use for translation. In that way, users will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the same commands utilized by MkDocs.","title":"Supporting theme Localization/Translation"},{"location":"dev-guide/themes/#enabling-the-localizationtranslation-commands","text":"MkDocs includes some helper commands which are light wrappers around pybabel's commands . To use the commands on your own theme, add the following to your theme's setup.py script: from mkdocs.commands.setup import babel_cmdclass setup( ... cmdclass=babel_cmdclass ) Note that cmdclass=babel_cmdclass was added an a parameter passed to the setup function. Warning As pybabel is not installed by default and most users will not have pybabel installed, theme developers and/or translators should make sure to have installed the necessary dependencies (using pip install mkdocs[i18n] ) in order for the commands to be available for use.","title":"Enabling the Localization/Translation commands"},{"location":"dev-guide/themes/#using-the-localizationtranslation-commands","text":"Since the translation commands are embedded in the setup.py script of your custom theme they should be called from the root of your theme's working tree as follows: python setup.py <command_name> [OPTIONS] Each command provides a detailed list of options available with the -h/--help option. For an overview of the workflow used by MkDocs to translate the built-in themes, see the appropriate section of the Contributing Guide and the Translation Guide . Default values for many of the options to the commands can be defined in a setup.cfg file. Create a section using the command name as the section name, and the long option name as the key. See MkDocs' own setup.cfg file for an example. A summary of changes/additions to the behavior and options of the upstream pybabel commands are summarized below.","title":"Using the Localization/Translation commands"},{"location":"dev-guide/themes/#compile_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value of the -d/--directory option. The --directory option is set to {theme_dir}/locales . If a directory is passed to the --directory option, then the theme option is ignored.","title":"compile_catalog"},{"location":"dev-guide/themes/#extract_messages","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the --input-dirs and --output-file options. The --input-dirs option is set to the theme directory and --output-file is set to {theme_dir}/{domain}.pot . If a path is provided to either option, then the theme option is ignored for that option. The --domain option has been added to this command and can be used to override the domain used for the output-file based on the theme . Defaults to messages . The -F/--mapping-file option defaults to the mapping file used by MkDocs' built-in themes. However, if that mapping file does not meet your theme's needs to can override it by providing your own and passing the path of that file into the option.","title":"extract_messages"},{"location":"dev-guide/themes/#init_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option.","title":"init_catalog"},{"location":"dev-guide/themes/#update_catalog","text":"The -t/--theme option has been added to this command. The theme specified must be a theme defined as a entry point in the same setup.py script. Other themes will not be recognized. If only one theme has been defined as an entry point, then that theme will be used as the default if none is specified by this option. If more than one theme is defined as entry points, then no default is set and a theme must be specified by this option. The command only operates on one theme at a time. Therefore, the command needs to be run once for each theme included in a package. When a theme is specified, the directory of that theme as defined in the entry point is used to define a default value for the -i/--input-file and -d/--output-dir options. The --input-file option is set to {theme_dir}/{domain}.pot ( domain defaults to messages ) and --output-dir is set to {theme_dir}/locales . If a path is provided to either option, then the theme option is ignored for that option.","title":"update_catalog"},{"location":"dev-guide/themes/#example-custom-theme-localizationtranslation-workflow","text":"Note If your theme inherits from an existing theme which already provides translation catalogs, your theme's translations will be merged with the parent theme's translations during a MkDocs build. This means that you only need to concentrate on the added translations. Yet, you will still benefit from the translations of the parent theme. At the same time, you may override any of parent theme's translations! Let's suppose that you're working on your own fork of the mkdocs-basic-theme and want to add translations to it. You would first modify the setup.py like this: --- a/setup.py +++ b/setup.py @@ -1,4 +1,5 @@ from setuptools import setup, find_packages +from mkdocs.commands.setup import babel_cmdclass VERSION = '1.1' @@ -18,5 +19,6 @@ setup( 'basictheme = basic_theme', ] }, - zip_safe=False + zip_safe=False, + cmdclass=babel_cmdclass ) Next, you would edit the templates by wrapping text in your HTML sources with {% trans %} and {% endtrans %} as follows: --- a/basic_theme/base.html +++ b/basic_theme/base.html @@ -88,7 +88,7 @@ <body> - <h1>This is an example theme for MkDocs.</h1> + <h1>{% trans %}This is an example theme for MkDocs.{% endtrans %}</h1> <p> It is designed to be read by looking at the theme HTML which is heavily Then you would follow the Translation Guide as usual to get your translations running.","title":"Example custom theme Localization/Translation workflow"},{"location":"dev-guide/themes/#packaging-translations-with-your-theme","text":"While the Portable Object Template ( pot ) file created by the extract_messages command and the Portable Object ( po ) files created by the init_catalog and update_catalog commands are useful for creating and editing translations, they are not used by MkDocs directly and do not need to be included in a packaged release of a theme. When MkDocs builds a site with translations, it only makes use of the binary mo files(s) for the specified locale. Therefore, when packaging a theme , you would need to make the following addition to your MANIFEST.in file: recursive-include theme_name *.mo Then, before building your Python package, you will want to ensure that the binary mo file for each locale is up-to-date by running the compile_catalog command for each locale. MkDocs expects the binary mo files to be located at locales/<locale>/LC_MESSAGES/messages.mo , which the compile_catalog command automatically does for you. See Testing theme translations for details. Note As outlined in our Translation Guide , the MkDocs project has chosen to include the pot and po files in our code repository, but not the mo files. This requires us to always run compile_catalog before packaging a new release regardless of whether any changes were made to a translation or not. However, you may chose an alternate workflow for your theme. At a minimum, you need to ensure that up-to-date mo files are included at the correct location in each release. However, you may use a different process for generating those mo files if you chose to do so.","title":"Packaging Translations with your theme"},{"location":"dev-guide/translations/","text":"Translations \uf0c1 Theme localization guide. The built-in themes that are included with MkDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the Contributing Guide . To enable a specific translation see the documentation about the specific theme you are using in the User Guide . For translations of third-party themes, please see the documentation for those themes. For a third-party theme to make use of MkDocs' translation tools and methods, that theme must be properly configured to make use of those tools. Note Translations only apply to text contained within a theme's template, such as \"next\" and \"previous\" links. The Markdown content of a page is not translated. If you wish to create multilingual documentation, you need to combine theme localization with a third-party internationalization/localization plugin. Localization tooling prerequisites \uf0c1 Theme localization makes use of the babel project for generation and compilation of localization files. Custom commands are available from the MkDocs' setup.py script as described below to assist with the process of updating and contributing translations. You will need to be working from the git working tree on your local machine to make use of the helper scripts. See the Contributing Guide for direction on how to Install for Development and Submit a Pull Request . The instructions in this document assume that you are working from a properly configured development environment. Make sure translation requirements are installed in your environment: pip install mkdocs[i18n] Adding language translations to themes \uf0c1 If your favorite language locale is not yet supported on one (or both) of the built-in themes ( mkdocs and readthedocs ), you can easily contribute a translation by following the steps below. Here is a quick summary of what you'll need to do: Initialize new localization catalogs for your language (if a translation for your locale already exists, follow the instructions for updating theme localization files instead). Add a translation for every text placeholder in the localized catalogs. Locally serve and test the translated themes for your language. Update the documentation about supported translations for each translated theme. Contribute your translation through a Pull Request. Note Translation locales are usually identified using the ISO-639-1 (2-letter) language codes. While territory/region/county codes are also supported, location specific translations should only be added after the general language translation has been completed and the regional dialect requires use of a term which differs from the general language translation. Initializing the localization catalogs \uf0c1 The templates for each theme contain text placeholders that have been extracted into a Portable Object Template ( messages.pot ) file, which is present in each theme's folder. Initializing a catalog consists of running a command which will create a directory structure for your desired language and prepare a Portable Object ( messages.po ) file derived from the pot file of the theme. Use the init_catalog command on each theme ( -t <theme> ) and provide the appropriate language code ( -l <language> ). For example, to add a translation for the Spanish es language to the mkdocs theme, run the following command: python setup.py init_catalog -t mkdocs -l es The above command will create the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u2514\u2500\u2500 messages.po You can now move on to the next step and add a translation for every text placeholder in the localized catalog. Updating a theme translation \uf0c1 If a theme's messages.pot template file has been updated since the messages.po was last updated for your locale, follow the steps below to update the theme's messages.po file: Update the theme's translation catalog to refresh the translatable text placeholders of each theme. Translate the newly added translatable text placeholders on every messages.po catalog file language you can. Locally serve and test the translated themes for your language. Contribute your translation through a Pull Request. Updating the translation catalogs \uf0c1 This step should be completed after a theme template have been updated for each language that you are comfortable contributing a translation for. To update the fr translation catalog of the mkdocs theme, use the following command: python setup.py update_catalog -t mkdocs -l fr You can now move on to the next step and add a translation for every updated text placeholder in the localized catalog. Translating the MkDocs themes \uf0c1 Now that your localized messages.po files are ready, all you need to do is add a translation in each msgstr item for each msgid item in the file. msgid \"Next\" msgstr \"Siguiente\" Warning Do not modify the msgid as it is common to all translations. Just add its translation in the msgstr item. Once you have finished translating all of the terms listed in the po file, you'll want to test your localized theme . Testing theme translations \uf0c1 To test a theme with translations, you need to first compile the messages.po files of your theme into messages.mo files. The following command will compile the es translation for the mkdocs theme. python setup.py compile_catalog -t mkdocs -l es The above command results in the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u251c\u2500\u2500 messages.mo \u2502 \u2514\u2500\u2500 messages.po Note that the compiled messages.mo file was generated based on the messages.po file that you just edited. Then modify the mkdocs.yml file at the root of the project to test the new and/or updated locale: theme: name: mkdocs locale: es Finally, run mkdocs serve to check out your new localized version of the theme. Note The build and release process takes care of compiling and distributing all locales to end users so you only have to worry about contributing the actual text translation messages.po files (the rest is ignored by git). After you have finished testing your work, be sure to undo the change to the locale setting in the mkdocs.yml file before submitting your changes. Updating theme documentation \uf0c1 Update the lists of supported translations for each translated theme located at Choosing your theme ( docs/user-guide/choosing-your-theme.md ), in their locale options. Contributing translations \uf0c1 It is now time for you to contribute your nice work to the project. Thank you!","title":"Translations"},{"location":"dev-guide/translations/#translations","text":"Theme localization guide. The built-in themes that are included with MkDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the Contributing Guide . To enable a specific translation see the documentation about the specific theme you are using in the User Guide . For translations of third-party themes, please see the documentation for those themes. For a third-party theme to make use of MkDocs' translation tools and methods, that theme must be properly configured to make use of those tools. Note Translations only apply to text contained within a theme's template, such as \"next\" and \"previous\" links. The Markdown content of a page is not translated. If you wish to create multilingual documentation, you need to combine theme localization with a third-party internationalization/localization plugin.","title":"Translations"},{"location":"dev-guide/translations/#localization-tooling-prerequisites","text":"Theme localization makes use of the babel project for generation and compilation of localization files. Custom commands are available from the MkDocs' setup.py script as described below to assist with the process of updating and contributing translations. You will need to be working from the git working tree on your local machine to make use of the helper scripts. See the Contributing Guide for direction on how to Install for Development and Submit a Pull Request . The instructions in this document assume that you are working from a properly configured development environment. Make sure translation requirements are installed in your environment: pip install mkdocs[i18n]","title":"Localization tooling prerequisites"},{"location":"dev-guide/translations/#adding-language-translations-to-themes","text":"If your favorite language locale is not yet supported on one (or both) of the built-in themes ( mkdocs and readthedocs ), you can easily contribute a translation by following the steps below. Here is a quick summary of what you'll need to do: Initialize new localization catalogs for your language (if a translation for your locale already exists, follow the instructions for updating theme localization files instead). Add a translation for every text placeholder in the localized catalogs. Locally serve and test the translated themes for your language. Update the documentation about supported translations for each translated theme. Contribute your translation through a Pull Request. Note Translation locales are usually identified using the ISO-639-1 (2-letter) language codes. While territory/region/county codes are also supported, location specific translations should only be added after the general language translation has been completed and the regional dialect requires use of a term which differs from the general language translation.","title":"Adding language translations to themes"},{"location":"dev-guide/translations/#initializing-the-localization-catalogs","text":"The templates for each theme contain text placeholders that have been extracted into a Portable Object Template ( messages.pot ) file, which is present in each theme's folder. Initializing a catalog consists of running a command which will create a directory structure for your desired language and prepare a Portable Object ( messages.po ) file derived from the pot file of the theme. Use the init_catalog command on each theme ( -t <theme> ) and provide the appropriate language code ( -l <language> ). For example, to add a translation for the Spanish es language to the mkdocs theme, run the following command: python setup.py init_catalog -t mkdocs -l es The above command will create the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u2514\u2500\u2500 messages.po You can now move on to the next step and add a translation for every text placeholder in the localized catalog.","title":"Initializing the localization catalogs"},{"location":"dev-guide/translations/#updating-a-theme-translation","text":"If a theme's messages.pot template file has been updated since the messages.po was last updated for your locale, follow the steps below to update the theme's messages.po file: Update the theme's translation catalog to refresh the translatable text placeholders of each theme. Translate the newly added translatable text placeholders on every messages.po catalog file language you can. Locally serve and test the translated themes for your language. Contribute your translation through a Pull Request.","title":"Updating a theme translation"},{"location":"dev-guide/translations/#updating-the-translation-catalogs","text":"This step should be completed after a theme template have been updated for each language that you are comfortable contributing a translation for. To update the fr translation catalog of the mkdocs theme, use the following command: python setup.py update_catalog -t mkdocs -l fr You can now move on to the next step and add a translation for every updated text placeholder in the localized catalog.","title":"Updating the translation catalogs"},{"location":"dev-guide/translations/#translating-the-mkdocs-themes","text":"Now that your localized messages.po files are ready, all you need to do is add a translation in each msgstr item for each msgid item in the file. msgid \"Next\" msgstr \"Siguiente\" Warning Do not modify the msgid as it is common to all translations. Just add its translation in the msgstr item. Once you have finished translating all of the terms listed in the po file, you'll want to test your localized theme .","title":"Translating the MkDocs themes"},{"location":"dev-guide/translations/#testing-theme-translations","text":"To test a theme with translations, you need to first compile the messages.po files of your theme into messages.mo files. The following command will compile the es translation for the mkdocs theme. python setup.py compile_catalog -t mkdocs -l es The above command results in the following file structure: mkdocs/themes/mkdocs/locales \u251c\u2500\u2500 es \u2502 \u2514\u2500\u2500 LC_MESSAGES \u2502 \u251c\u2500\u2500 messages.mo \u2502 \u2514\u2500\u2500 messages.po Note that the compiled messages.mo file was generated based on the messages.po file that you just edited. Then modify the mkdocs.yml file at the root of the project to test the new and/or updated locale: theme: name: mkdocs locale: es Finally, run mkdocs serve to check out your new localized version of the theme. Note The build and release process takes care of compiling and distributing all locales to end users so you only have to worry about contributing the actual text translation messages.po files (the rest is ignored by git). After you have finished testing your work, be sure to undo the change to the locale setting in the mkdocs.yml file before submitting your changes.","title":"Testing theme translations"},{"location":"dev-guide/translations/#updating-theme-documentation","text":"Update the lists of supported translations for each translated theme located at Choosing your theme ( docs/user-guide/choosing-your-theme.md ), in their locale options.","title":"Updating theme documentation"},{"location":"dev-guide/translations/#contributing-translations","text":"It is now time for you to contribute your nice work to the project. Thank you!","title":"Contributing translations"},{"location":"user-guide/","text":"User Guide \uf0c1 Building Documentation with MkDocs The MkDocs Developer Guide provides documentation for users of MkDocs. See Getting Started for an introductory tutorial. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Installation Writing Your Docs Choosing Your Theme Customizing Your Theme Configuration Deploying Your Docs","title":"Overview"},{"location":"user-guide/#user-guide","text":"Building Documentation with MkDocs The MkDocs Developer Guide provides documentation for users of MkDocs. See Getting Started for an introductory tutorial. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Installation Writing Your Docs Choosing Your Theme Customizing Your Theme Configuration Deploying Your Docs","title":"User Guide"},{"location":"user-guide/choosing-your-theme/","text":"Choosing your Theme \uf0c1 Selecting and configuring a theme. MkDocs includes two built-in themes ( mkdocs and readthedocs ), as documented below. However, many third party themes are available to choose from as well. To choose a theme, set the theme configuration option in your mkdocs.yml config file. theme: name: readthedocs mkdocs \uf0c1 The default theme, which was built as a custom Bootstrap theme, supports most every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides 79 different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: github . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: mkdocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: mkdocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the site. shortcuts : Defines keyboard shortcut keys. theme: name: mkdocs shortcuts: help: 191 # ? next: 78 # n previous: 80 # p search: 83 # s All values must be numeric key codes. It is best to use keys which are available on all keyboards. You may use https://keycode.info/ to determine the key code for a given key. help : Display a help modal which lists the keyboard shortcuts. Default: 191 (?) next : Navigate to the \"next\" page. Default: 78 (n) previous : Navigate to the \"previous\" page. Default: 80 (p) search : Display the search modal. Default: 83 (s) navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 2 . nav_style : This adjusts the visual style for the top navigation bar; by default, this is set to primary (the default), but it can also be set to dark or light . theme: name: mkdocs nav_style: dark locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish ja : Japanese pt_BR : Portuguese (Brazil) zh_CN : Simplified Chinese See the guide on localizing your theme for more information. readthedocs \uf0c1 A clone of the default theme used by the Read the Docs service, which offers the same restricted feature-set as its parent theme. Like its parent theme, only two levels of navigation are supported. In addition to the default theme configuration options , the readthedocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: readthedocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: readthedocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the include_homepage_in_sidebar : Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the nav configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: True . prev_next_buttons_location : One of bottom , top , both , or none . Displays the \u201cNext\u201d and \u201cPrevious\u201d buttons accordingly. Default: bottom . navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 4 . collapse_navigation : Only include the page section headers in the sidebar for the current page. Default: True . titles_only : Only include page titles in the sidebar, excluding all section headers for all pages. Default: False . sticky_navigation : If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: True . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish ja : Japanese pt_BR : Portuguese (Brazil) zh_CN : Simplified Chinese See the guide on localizing your theme for more information. Third Party Themes \uf0c1 A list of third party themes can be found in the MkDocs community wiki . If you have created your own, please feel free to add it to the list.","title":"Choosing Your Theme"},{"location":"user-guide/choosing-your-theme/#choosing-your-theme","text":"Selecting and configuring a theme. MkDocs includes two built-in themes ( mkdocs and readthedocs ), as documented below. However, many third party themes are available to choose from as well. To choose a theme, set the theme configuration option in your mkdocs.yml config file. theme: name: readthedocs","title":"Choosing your Theme"},{"location":"user-guide/choosing-your-theme/#mkdocs","text":"The default theme, which was built as a custom Bootstrap theme, supports most every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides 79 different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: github . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: mkdocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: mkdocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the site. shortcuts : Defines keyboard shortcut keys. theme: name: mkdocs shortcuts: help: 191 # ? next: 78 # n previous: 80 # p search: 83 # s All values must be numeric key codes. It is best to use keys which are available on all keyboards. You may use https://keycode.info/ to determine the key code for a given key. help : Display a help modal which lists the keyboard shortcuts. Default: 191 (?) next : Navigate to the \"next\" page. Default: 78 (n) previous : Navigate to the \"previous\" page. Default: 80 (p) search : Display the search modal. Default: 83 (s) navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 2 . nav_style : This adjusts the visual style for the top navigation bar; by default, this is set to primary (the default), but it can also be set to dark or light . theme: name: mkdocs nav_style: dark locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish ja : Japanese pt_BR : Portuguese (Brazil) zh_CN : Simplified Chinese See the guide on localizing your theme for more information.","title":"mkdocs"},{"location":"user-guide/choosing-your-theme/#readthedocs","text":"A clone of the default theme used by the Read the Docs service, which offers the same restricted feature-set as its parent theme. Like its parent theme, only two levels of navigation are supported. In addition to the default theme configuration options , the readthedocs theme supports the following options: highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_languages : By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. theme: name: readthedocs highlightjs: true hljs_languages: - yaml - rust analytics : Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option. gtag : To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property . theme: name: readthedocs analytics: gtag: G-ABC123 When set to the default ( null ) Google Analytics is disabled for the include_homepage_in_sidebar : Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the nav configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: True . prev_next_buttons_location : One of bottom , top , both , or none . Displays the \u201cNext\u201d and \u201cPrevious\u201d buttons accordingly. Default: bottom . navigation_depth : The maximum depth of the navigation tree in the sidebar. Default: 4 . collapse_navigation : Only include the page section headers in the sidebar for the current page. Default: True . titles_only : Only include page titles in the sidebar, excluding all section headers for all pages. Default: False . sticky_navigation : If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: True . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fallback to the default. The following locales are supported by this theme: en : English (default) fr : French es : Spanish ja : Japanese pt_BR : Portuguese (Brazil) zh_CN : Simplified Chinese See the guide on localizing your theme for more information.","title":"readthedocs"},{"location":"user-guide/choosing-your-theme/#third-party-themes","text":"A list of third party themes can be found in the MkDocs community wiki . If you have created your own, please feel free to add it to the list.","title":"Third Party Themes"},{"location":"user-guide/configuration/","text":"Configuration \uf0c1 Guide to all available configuration settings. Introduction \uf0c1 Project settings are configured by default using a YAML configuration file in the project directory named mkdocs.yml . You can specify another path for it by using the -f / --config-file option (see mkdocs build --help ). As a minimum, this configuration file must contain the site_name and site_url settings. All other settings are optional. Project information \uf0c1 site_name \uf0c1 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 \uf0c1 Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting ( https://example.com/foo/ ). This setting is also used for mkdocs serve : the server will be mounted onto a path taken from the path component of the URL, e.g. some/page.md will be served from http://127.0.0.1:8000/foo/some/page/ to mimic the expected remote layout. default : null repo_url \uf0c1 When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page. repo_url: https://github.com/example/repository/ default : null repo_name \uf0c1 When set, provides the name for the link to your repository on each page. default : 'GitHub' , 'Bitbucket' or 'GitLab' if the repo_url matches those domains, otherwise the hostname from the repo_url . edit_uri \uf0c1 The path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself. MkDocs concatenates repo_url and edit_uri , and appends the input path of the page. When set, and if your theme supports it, provides a link directly to the page in your source repository. This makes it easier to find and edit the source for the page. If repo_url is not set, this option is ignored. On some themes, setting this option may cause an edit link to be used in place of a repository link. Other themes may show both links. The edit_uri supports query ('?') and fragment ('#') characters. For repository hosts that use a query or a fragment to access the files, the edit_uri might be set as follows. (Note the ? and # in the URI...) # Query string example edit_uri: '?query=root/path/docs/' # Hash fragment example edit_uri: '#root/path/docs/' For other repository hosts, simply specify the relative path to the docs directory. # Query string example edit_uri: root/path/docs/ Note On a few known hosts (specifically GitHub, Bitbucket and GitLab), the edit_uri is derived from the 'repo_url' and does not need to be set manually. Simply defining a repo_url will automatically populate the edit_uri configs setting. For example, for a GitHub- or GitLab-hosted repository, the edit_uri would be automatically set as edit/master/docs/ (Note the edit path and master branch). For a Bitbucket-hosted repository, the equivalent edit_uri would be automatically set as src/default/docs/ (note the src path and default branch). To use a different URI than the default (for example a different branch), simply set the edit_uri to your desired string. If you do not want any \"edit URL link\" displayed on your pages, then set edit_uri to an empty string to disable the automatic setting. Warning On GitHub and GitLab, the default \"edit\" path ( edit/master/docs/ ) opens the page in the online editor. This functionality requires that the user have and be logged in to a GitHub/GitLab account. Otherwise, the user will be redirected to a login/signup page. Alternatively, use the \"blob\" path ( blob/master/docs/ ) to open a read-only view, which supports anonymous access. default : edit/master/docs/ for GitHub and GitLab repos or src/default/docs/ for a Bitbucket repo, if repo_url matches those domains, otherwise null site_description \uf0c1 Set the site description. This will add a meta tag to the generated HTML header. default : null site_author \uf0c1 Set the name of the author. This will add a meta tag to the generated HTML header. default : null copyright \uf0c1 Set the copyright information to be included in the documentation by the theme. default : null remote_branch \uf0c1 Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : gh-pages remote_name \uf0c1 Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : origin Documentation layout \uf0c1 nav \uf0c1 This setting is used to determine the format and layout of the global navigation for the site. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths must be relative to the mkdocs.yml configuration file. See the section on configuring pages and navigation for a more detailed breakdown, including how to create sub-sections. Navigation items may also include links to external sites. While titles are optional for internal links, they are required for external links. An external link may be a full URL or a relative URL. Any path which is not found in the files is assumed to be an external link. See the section about [Meta-Data] on how MkDocs determines the page title of a document. nav: - Introduction: 'index.md' - 'about.md' - 'Issue Tracker': 'https://example.com/' In the above example, the first two items point to local files while the third points to an external site. However, sometimes the MkDocs site is hosted in a subdirectory of a project's site and you may want to link to other parts of the same site without including the full domain. In that case, you may use an appropriate relative URL. site_url: https://example.com/foo/ nav: - Home: '../' - 'User Guide': 'user-guide.md' - 'Bug Tracker': '/bugs/' In the above example, two different styles of external links are used. First, note that the site_url indicates that the MkDocs site is hosted in the /foo/ subdirectory of the domain. Therefore, the Home navigation item is a relative link that steps up one level to the server root and effectively points to https://example.com/ . The Bug Tracker item uses an absolute path from the server root and effectively points to https://example.com/bugs/ . Of course, the User Guide points to a local MkDocs page. default : By default nav will contain an alphanumerically sorted, nested list of all the Markdown files found within the docs_dir and its sub-directories. Index files will always be listed first within a sub-section. Build directories \uf0c1 theme \uf0c1 Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs. If a string, it must be the string name of a known installed theme. For a list of available themes visit Choosing Your Theme . An example set of key/value pairs might look something like this: theme: name: mkdocs locale: en custom_dir: my_theme_customizations/ static_templates: - sitemap.html include_sidebar: false If a set of key/value pairs, the following nested keys can be defined: name: \uf0c1 The string name of a known installed theme. For a list of available themes visit Choosing Your Theme . locale: \uf0c1 A code representing the language of your site. See Localizing your theme for details. custom_dir: \uf0c1 A directory containing 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 from the root of your local file system. See Customizing Your Theme for details if you would like to tweak an existing theme. See the Theme Developer Guide if you would like to build your own theme from the ground up. static_templates: \uf0c1 A list of templates to render as static pages. The templates must be located in either the theme's template directory or in the custom_dir defined in the theme configuration. (theme specific keywords) \uf0c1 Any additional keywords supported by the theme can also be defined. See the documentation for the theme you are using for details. default : 'mkdocs' docs_dir \uf0c1 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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'docs' site_dir \uf0c1 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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'site' Note: If you are using source code control you will normally want to ensure that your build output files are not committed into the repository, and only keep the source files under version control. For example, if using git you might add the following line to your .gitignore file: site/ If you're using another source code control tool, you'll want to check its documentation on how to ignore specific directories. extra_css \uf0c1 Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir . extra_css: - css/extra.css - css/second_extra.css default : [] (an empty list). extra_javascript \uf0c1 Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage. default : [] (an empty list). extra_templates \uf0c1 Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage. default : [] (an empty list). extra \uf0c1 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. For example, if you are using a theme that supports displaying the project version, you can pass it to the theme like this: extra: version: 1.0 default : By default extra will be an empty key-value mapping. Preview controls \uf0c1 use_directory_urls \uf0c1 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 . Source file use_directory_urls: true use_directory_urls: false index.md / /index.html api-guide.md /api-guide/ /api-guide.html about/license.md /about/license/ /about/license.html 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 be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it creates links that point directly to the target file rather than the target directory . default : true strict \uf0c1 Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing. default : false dev_addr \uf0c1 Determines the address used when running mkdocs serve . Must be of the format IP:PORT . Allows a custom default to be set without the need to pass it through the --dev-addr option every time the mkdocs serve command is called. default : '127.0.0.1:8000' See also: site_url . Formatting options \uf0c1 markdown_extensions \uf0c1 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 separated by a colon. If you would like to define multiple options for a single extension, each option must be defined on a separate 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 In the above examples, each extension is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for extensions for which no options are defined. Therefore, the last example above could also be defined as follows: markdown_extensions: smarty: {} toc: permalink: True sane_lists: {} This alternative syntax is required if you intend to override some options via inheritance . See Also: The Python-Markdown documentation provides a list of extensions which are available out-of-the-box. For a list of configuration options available for a given extension, see the documentation for that extension. You may also install and use various third party extensions . Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list). plugins \uf0c1 A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. If the plugins config setting is defined in the mkdocs.yml config file, then any defaults (such as search ) are ignored and you need to explicitly re-enable the defaults if you would like to continue using them: plugins: - search - your_other_plugin To define options for a given plugin, use a nested set of key/value pairs: plugins: - search - your_other_plugin: option1: value option2: other value In the above examples, each plugin is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for plugins for which no options are defined. Therefore, the last example above could also be defined as follows: plugins: search: {} your_other_plugin: option1: value option2: other value This alternative syntax is required if you intend to override some options via inheritance . To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] default : ['search'] (the \"search\" plugin included with MkDocs). Search \uf0c1 A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin: separator \uf0c1 A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen ( - ) are used. To add the dot ( . ) as a word separator you might do this: plugins: - search: separator: '[\\s\\-\\.]+' default : '[\\s\\-]+' min_search_length \uf0c1 An integer value that defines the minimum length for a search query. By default searches shorter than 3 chars in length are ignored as search result quality with short search terms are poor. However, for some use cases (such as documentation about Message Queues which might generate searches for 'MQ') it may be preferable to set a shorter limit. plugins: - search: min_search_length: 2 default : 3 lang \uf0c1 A list of languages to use when building the search index as identified by their ISO 639-1 language codes. With Lunr Languages , the following languages are supported: ar : Arabic da : Danish nl : Dutch en : English fi : Finnish fr : French de : German hu : Hungarian it : Italian ja : Japanese no : Norwegian pt : Portuguese ro : Romanian ru : Russian es : Spanish sv : Swedish th : Thai tr : Turkish vi : Vietnamese You may contribute additional languages . Warning While search does support using multiple languages together, it is best not to add additional languages unless you really need them. Each additional language adds significant bandwidth requirements and uses more browser resources. Generally, it is best to keep each instance of MkDocs to a single language. Note Lunr Languages does not currently include support for Chinese or other Asian languages. However, some users have reported decent results using Japanese. default : The value of theme.locale if set, otherwise [en] . prebuild_index \uf0c1 Optionally generates a pre-built index of all pages, which provides some performance improvements for larger sites. Before enabling, confirm that the theme you are using explicitly supports using a prebuilt index (the builtin themes do). Set to true to enable. Warning This option requires that Node.js be installed and the command node be on the system path. If the call to node fails for any reason, a warning is issued and the build continues uninterrupted. You may use the --strict flag when building to cause such a failure to raise an error instead. Note On smaller sites, using a pre-built index is not recommended as it creates a significant increase is bandwidth requirements with little to no noticeable improvement to your users. However, for larger sites (hundreds of pages), the bandwidth increase is relatively small and your users will notice a significant improvement in search performance. default : False indexing \uf0c1 Configures what strategy the search indexer will use when building the index for your pages. This property is particularly useful if your project is large in scale, and the index takes up an enormous amount of disk space. plugins: - search: indexing: 'full' Options \uf0c1 Option Description full Indexes the title, section headings, and full text of each page. sections Indexes the title and section headings of each page. titles Indexes only the title of each page. default : full Environment Variables \uf0c1 In most cases, the value of a configuration option is set directly in the configuration file. However, as an option, the value of a configuration option may be set to the value of an environment variable using the !ENV tag. For example, to set the value of the site_name option to the value of the variable SITE_NAME the YAML file may contain the following: site_name: !ENV SITE_NAME If the environment variable is not defined, then the configuration setting would be assigned a null (or None in Python) value. A default value can be defined as the last value in a list. Like this: site_name: !ENV [SITE_NAME, 'My default site name'] Multiple fallback variables can be used as well. Note that the last value is not an environment variable, but must be a value to use as a default if none of the specified environment variables are defined. site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] Simple types defined within an environment variable such as string, bool, integer, float, datestamp and null are parsed as if they were defined directly in the YAML file, which means that the value will be converted to the appropriate type. However, complex types such as lists and key/value pairs cannot be defined within a single environment variable. For more details, see the pyyaml_env_tag project. Configuration Inheritance \uf0c1 Generally, a single file would hold the entire configuration for a site. However, some organizations may maintain multiple sites which all share a common configuration across them. Rather than maintaining separate configurations for each, the common configuration options can be defined in a parent configuration while which each site's primary configuration file inherits. To define the parent for a configuration file, set the INHERIT (all caps) key to the path of the parent file. The path must be relative to the location of the primary file. For configuration options to be merged with a parent configuration, those options must be defined as key/value pairs. Specifically, the markdown_extensions and plugins options must use the alternative syntax which does not use list items (lines which start with - ). For example, suppose the common (parent) configuration is defined in base.yml : theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Then, for the \"foo\" site, the primary configuration file would be defined at foo/mkdocs.yml : INHERIT: ../base.yml site_name: Foo Project site_url: https://example.com/foo When running mkdocs build , the file at foo/mkdocs.yml would be passed in as the configuration file. MkDocs will then parse that file, retrieve and parse the parent file base.yml and deep merge the two. This would result in MkDocs receiving the following merged configuration: site_name: Foo Project site_url: https://example.com/foo theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Deep merging allows you to add and/or override various values in your primary configuration file. For example, suppose for one site you wanted to add support for definition lists, use a different symbol for permalinks, and define a different separator. In that site's primary configuration file you could do: INHERIT: ../base.yml site_name: Bar Project site_url: https://example.com/bar markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" In that case, the above configuration would be deep merged with base.yml and result in the following configuration: site_name: Bar Project site_url: https://example.com/bar theme: name: mkdocs locale: en highlightjs: true markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" admonition: {} Notice that the admonition extension was retained from the parent configuration, the def_list extension was added, the value of toc.permalink was replaced, and the value of toc.separator was added. You can replace or merge the value of any key. However, any non-key is always replaced. Therefore, you cannot append items to a list. You must redefine the entire list. As the nav configuration is made up of nested lists, this means that you cannot merge navigation items. Of course, you can replace the entire nav configuration with a new one. However, it is generally expected that the entire navigation would be defined in the primary configuration file for a project. Warning As a reminder, all path based configuration options must be relative to the primary configuration file and MkDocs does not alter the paths when merging. Therefore, defining paths in a parent file which is inherited by multiple different sites may not work as expected. It is generally best to define path based options in the primary configuration file only.","title":"Configuration"},{"location":"user-guide/configuration/#configuration","text":"Guide to all available configuration settings.","title":"Configuration"},{"location":"user-guide/configuration/#introduction","text":"Project settings are configured by default using a YAML configuration file in the project directory named mkdocs.yml . You can specify another path for it by using the -f / --config-file option (see mkdocs build --help ). As a minimum, this configuration file must contain the site_name and site_url settings. All other settings are optional.","title":"Introduction"},{"location":"user-guide/configuration/#project-information","text":"","title":"Project information"},{"location":"user-guide/configuration/#site_name","text":"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.","title":"site_name"},{"location":"user-guide/configuration/#site_url","text":"Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting ( https://example.com/foo/ ). This setting is also used for mkdocs serve : the server will be mounted onto a path taken from the path component of the URL, e.g. some/page.md will be served from http://127.0.0.1:8000/foo/some/page/ to mimic the expected remote layout. default : null","title":"site_url"},{"location":"user-guide/configuration/#repo_url","text":"When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page. repo_url: https://github.com/example/repository/ default : null","title":"repo_url"},{"location":"user-guide/configuration/#repo_name","text":"When set, provides the name for the link to your repository on each page. default : 'GitHub' , 'Bitbucket' or 'GitLab' if the repo_url matches those domains, otherwise the hostname from the repo_url .","title":"repo_name"},{"location":"user-guide/configuration/#edit_uri","text":"The path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself. MkDocs concatenates repo_url and edit_uri , and appends the input path of the page. When set, and if your theme supports it, provides a link directly to the page in your source repository. This makes it easier to find and edit the source for the page. If repo_url is not set, this option is ignored. On some themes, setting this option may cause an edit link to be used in place of a repository link. Other themes may show both links. The edit_uri supports query ('?') and fragment ('#') characters. For repository hosts that use a query or a fragment to access the files, the edit_uri might be set as follows. (Note the ? and # in the URI...) # Query string example edit_uri: '?query=root/path/docs/' # Hash fragment example edit_uri: '#root/path/docs/' For other repository hosts, simply specify the relative path to the docs directory. # Query string example edit_uri: root/path/docs/ Note On a few known hosts (specifically GitHub, Bitbucket and GitLab), the edit_uri is derived from the 'repo_url' and does not need to be set manually. Simply defining a repo_url will automatically populate the edit_uri configs setting. For example, for a GitHub- or GitLab-hosted repository, the edit_uri would be automatically set as edit/master/docs/ (Note the edit path and master branch). For a Bitbucket-hosted repository, the equivalent edit_uri would be automatically set as src/default/docs/ (note the src path and default branch). To use a different URI than the default (for example a different branch), simply set the edit_uri to your desired string. If you do not want any \"edit URL link\" displayed on your pages, then set edit_uri to an empty string to disable the automatic setting. Warning On GitHub and GitLab, the default \"edit\" path ( edit/master/docs/ ) opens the page in the online editor. This functionality requires that the user have and be logged in to a GitHub/GitLab account. Otherwise, the user will be redirected to a login/signup page. Alternatively, use the \"blob\" path ( blob/master/docs/ ) to open a read-only view, which supports anonymous access. default : edit/master/docs/ for GitHub and GitLab repos or src/default/docs/ for a Bitbucket repo, if repo_url matches those domains, otherwise null","title":"edit_uri"},{"location":"user-guide/configuration/#site_description","text":"Set the site description. This will add a meta tag to the generated HTML header. default : null","title":"site_description"},{"location":"user-guide/configuration/#site_author","text":"Set the name of the author. This will add a meta tag to the generated HTML header. default : null","title":"site_author"},{"location":"user-guide/configuration/#copyright","text":"Set the copyright information to be included in the documentation by the theme. default : null","title":"copyright"},{"location":"user-guide/configuration/#remote_branch","text":"Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : gh-pages","title":"remote_branch"},{"location":"user-guide/configuration/#remote_name","text":"Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy . default : origin","title":"remote_name"},{"location":"user-guide/configuration/#documentation-layout","text":"","title":"Documentation layout"},{"location":"user-guide/configuration/#nav","text":"This setting is used to determine the format and layout of the global navigation for the site. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths must be relative to the mkdocs.yml configuration file. See the section on configuring pages and navigation for a more detailed breakdown, including how to create sub-sections. Navigation items may also include links to external sites. While titles are optional for internal links, they are required for external links. An external link may be a full URL or a relative URL. Any path which is not found in the files is assumed to be an external link. See the section about [Meta-Data] on how MkDocs determines the page title of a document. nav: - Introduction: 'index.md' - 'about.md' - 'Issue Tracker': 'https://example.com/' In the above example, the first two items point to local files while the third points to an external site. However, sometimes the MkDocs site is hosted in a subdirectory of a project's site and you may want to link to other parts of the same site without including the full domain. In that case, you may use an appropriate relative URL. site_url: https://example.com/foo/ nav: - Home: '../' - 'User Guide': 'user-guide.md' - 'Bug Tracker': '/bugs/' In the above example, two different styles of external links are used. First, note that the site_url indicates that the MkDocs site is hosted in the /foo/ subdirectory of the domain. Therefore, the Home navigation item is a relative link that steps up one level to the server root and effectively points to https://example.com/ . The Bug Tracker item uses an absolute path from the server root and effectively points to https://example.com/bugs/ . Of course, the User Guide points to a local MkDocs page. default : By default nav will contain an alphanumerically sorted, nested list of all the Markdown files found within the docs_dir and its sub-directories. Index files will always be listed first within a sub-section.","title":"nav"},{"location":"user-guide/configuration/#build-directories","text":"","title":"Build directories"},{"location":"user-guide/configuration/#theme","text":"Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs. If a string, it must be the string name of a known installed theme. For a list of available themes visit Choosing Your Theme . An example set of key/value pairs might look something like this: theme: name: mkdocs locale: en custom_dir: my_theme_customizations/ static_templates: - sitemap.html include_sidebar: false If a set of key/value pairs, the following nested keys can be defined:","title":"theme"},{"location":"user-guide/configuration/#name","text":"The string name of a known installed theme. For a list of available themes visit Choosing Your Theme .","title":"name:"},{"location":"user-guide/configuration/#locale","text":"A code representing the language of your site. See Localizing your theme for details.","title":"locale:"},{"location":"user-guide/configuration/#custom_dir","text":"A directory containing 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 from the root of your local file system. See Customizing Your Theme for details if you would like to tweak an existing theme. See the Theme Developer Guide if you would like to build your own theme from the ground up.","title":"custom_dir:"},{"location":"user-guide/configuration/#static_templates","text":"A list of templates to render as static pages. The templates must be located in either the theme's template directory or in the custom_dir defined in the theme configuration.","title":"static_templates:"},{"location":"user-guide/configuration/#theme-specific-keywords","text":"Any additional keywords supported by the theme can also be defined. See the documentation for the theme you are using for details. default : 'mkdocs'","title":"(theme specific keywords)"},{"location":"user-guide/configuration/#docs_dir","text":"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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'docs'","title":"docs_dir"},{"location":"user-guide/configuration/#site_dir","text":"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 your configuration file, or it can be an absolute directory path from the root of your local file system. default : 'site' Note: If you are using source code control you will normally want to ensure that your build output files are not committed into the repository, and only keep the source files under version control. For example, if using git you might add the following line to your .gitignore file: site/ If you're using another source code control tool, you'll want to check its documentation on how to ignore specific directories.","title":"site_dir"},{"location":"user-guide/configuration/#extra_css","text":"Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir . extra_css: - css/extra.css - css/second_extra.css default : [] (an empty list).","title":"extra_css"},{"location":"user-guide/configuration/#extra_javascript","text":"Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage. default : [] (an empty list).","title":"extra_javascript"},{"location":"user-guide/configuration/#extra_templates","text":"Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage. default : [] (an empty list).","title":"extra_templates"},{"location":"user-guide/configuration/#extra","text":"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. For example, if you are using a theme that supports displaying the project version, you can pass it to the theme like this: extra: version: 1.0 default : By default extra will be an empty key-value mapping.","title":"extra"},{"location":"user-guide/configuration/#preview-controls","text":"","title":"Preview controls"},{"location":"user-guide/configuration/#use_directory_urls","text":"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 . Source file use_directory_urls: true use_directory_urls: false index.md / /index.html api-guide.md /api-guide/ /api-guide.html about/license.md /about/license/ /about/license.html 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 be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it creates links that point directly to the target file rather than the target directory . default : true","title":"use_directory_urls"},{"location":"user-guide/configuration/#strict","text":"Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing. default : false","title":"strict"},{"location":"user-guide/configuration/#dev_addr","text":"Determines the address used when running mkdocs serve . Must be of the format IP:PORT . Allows a custom default to be set without the need to pass it through the --dev-addr option every time the mkdocs serve command is called. default : '127.0.0.1:8000' See also: site_url .","title":"dev_addr"},{"location":"user-guide/configuration/#formatting-options","text":"","title":"Formatting options"},{"location":"user-guide/configuration/#markdown_extensions","text":"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 separated by a colon. If you would like to define multiple options for a single extension, each option must be defined on a separate 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 In the above examples, each extension is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for extensions for which no options are defined. Therefore, the last example above could also be defined as follows: markdown_extensions: smarty: {} toc: permalink: True sane_lists: {} This alternative syntax is required if you intend to override some options via inheritance . See Also: The Python-Markdown documentation provides a list of extensions which are available out-of-the-box. For a list of configuration options available for a given extension, see the documentation for that extension. You may also install and use various third party extensions . Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list).","title":"markdown_extensions"},{"location":"user-guide/configuration/#plugins","text":"A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. If the plugins config setting is defined in the mkdocs.yml config file, then any defaults (such as search ) are ignored and you need to explicitly re-enable the defaults if you would like to continue using them: plugins: - search - your_other_plugin To define options for a given plugin, use a nested set of key/value pairs: plugins: - search - your_other_plugin: option1: value option2: other value In the above examples, each plugin is a list item (starts with a - ). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for plugins for which no options are defined. Therefore, the last example above could also be defined as follows: plugins: search: {} your_other_plugin: option1: value option2: other value This alternative syntax is required if you intend to override some options via inheritance . To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] default : ['search'] (the \"search\" plugin included with MkDocs).","title":"plugins"},{"location":"user-guide/configuration/#search","text":"A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin:","title":"Search"},{"location":"user-guide/configuration/#separator","text":"A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen ( - ) are used. To add the dot ( . ) as a word separator you might do this: plugins: - search: separator: '[\\s\\-\\.]+' default : '[\\s\\-]+'","title":"separator"},{"location":"user-guide/configuration/#min_search_length","text":"An integer value that defines the minimum length for a search query. By default searches shorter than 3 chars in length are ignored as search result quality with short search terms are poor. However, for some use cases (such as documentation about Message Queues which might generate searches for 'MQ') it may be preferable to set a shorter limit. plugins: - search: min_search_length: 2 default : 3","title":"min_search_length"},{"location":"user-guide/configuration/#lang","text":"A list of languages to use when building the search index as identified by their ISO 639-1 language codes. With Lunr Languages , the following languages are supported: ar : Arabic da : Danish nl : Dutch en : English fi : Finnish fr : French de : German hu : Hungarian it : Italian ja : Japanese no : Norwegian pt : Portuguese ro : Romanian ru : Russian es : Spanish sv : Swedish th : Thai tr : Turkish vi : Vietnamese You may contribute additional languages . Warning While search does support using multiple languages together, it is best not to add additional languages unless you really need them. Each additional language adds significant bandwidth requirements and uses more browser resources. Generally, it is best to keep each instance of MkDocs to a single language. Note Lunr Languages does not currently include support for Chinese or other Asian languages. However, some users have reported decent results using Japanese. default : The value of theme.locale if set, otherwise [en] .","title":"lang"},{"location":"user-guide/configuration/#prebuild_index","text":"Optionally generates a pre-built index of all pages, which provides some performance improvements for larger sites. Before enabling, confirm that the theme you are using explicitly supports using a prebuilt index (the builtin themes do). Set to true to enable. Warning This option requires that Node.js be installed and the command node be on the system path. If the call to node fails for any reason, a warning is issued and the build continues uninterrupted. You may use the --strict flag when building to cause such a failure to raise an error instead. Note On smaller sites, using a pre-built index is not recommended as it creates a significant increase is bandwidth requirements with little to no noticeable improvement to your users. However, for larger sites (hundreds of pages), the bandwidth increase is relatively small and your users will notice a significant improvement in search performance. default : False","title":"prebuild_index"},{"location":"user-guide/configuration/#indexing","text":"Configures what strategy the search indexer will use when building the index for your pages. This property is particularly useful if your project is large in scale, and the index takes up an enormous amount of disk space. plugins: - search: indexing: 'full'","title":"indexing"},{"location":"user-guide/configuration/#options","text":"Option Description full Indexes the title, section headings, and full text of each page. sections Indexes the title and section headings of each page. titles Indexes only the title of each page. default : full","title":"Options"},{"location":"user-guide/configuration/#environment-variables","text":"In most cases, the value of a configuration option is set directly in the configuration file. However, as an option, the value of a configuration option may be set to the value of an environment variable using the !ENV tag. For example, to set the value of the site_name option to the value of the variable SITE_NAME the YAML file may contain the following: site_name: !ENV SITE_NAME If the environment variable is not defined, then the configuration setting would be assigned a null (or None in Python) value. A default value can be defined as the last value in a list. Like this: site_name: !ENV [SITE_NAME, 'My default site name'] Multiple fallback variables can be used as well. Note that the last value is not an environment variable, but must be a value to use as a default if none of the specified environment variables are defined. site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] Simple types defined within an environment variable such as string, bool, integer, float, datestamp and null are parsed as if they were defined directly in the YAML file, which means that the value will be converted to the appropriate type. However, complex types such as lists and key/value pairs cannot be defined within a single environment variable. For more details, see the pyyaml_env_tag project.","title":"Environment Variables"},{"location":"user-guide/configuration/#configuration-inheritance","text":"Generally, a single file would hold the entire configuration for a site. However, some organizations may maintain multiple sites which all share a common configuration across them. Rather than maintaining separate configurations for each, the common configuration options can be defined in a parent configuration while which each site's primary configuration file inherits. To define the parent for a configuration file, set the INHERIT (all caps) key to the path of the parent file. The path must be relative to the location of the primary file. For configuration options to be merged with a parent configuration, those options must be defined as key/value pairs. Specifically, the markdown_extensions and plugins options must use the alternative syntax which does not use list items (lines which start with - ). For example, suppose the common (parent) configuration is defined in base.yml : theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Then, for the \"foo\" site, the primary configuration file would be defined at foo/mkdocs.yml : INHERIT: ../base.yml site_name: Foo Project site_url: https://example.com/foo When running mkdocs build , the file at foo/mkdocs.yml would be passed in as the configuration file. MkDocs will then parse that file, retrieve and parse the parent file base.yml and deep merge the two. This would result in MkDocs receiving the following merged configuration: site_name: Foo Project site_url: https://example.com/foo theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {} Deep merging allows you to add and/or override various values in your primary configuration file. For example, suppose for one site you wanted to add support for definition lists, use a different symbol for permalinks, and define a different separator. In that site's primary configuration file you could do: INHERIT: ../base.yml site_name: Bar Project site_url: https://example.com/bar markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" In that case, the above configuration would be deep merged with base.yml and result in the following configuration: site_name: Bar Project site_url: https://example.com/bar theme: name: mkdocs locale: en highlightjs: true markdown_extensions: def_list: {} toc: permalink: \uf0c1 separator: \"_\" admonition: {} Notice that the admonition extension was retained from the parent configuration, the def_list extension was added, the value of toc.permalink was replaced, and the value of toc.separator was added. You can replace or merge the value of any key. However, any non-key is always replaced. Therefore, you cannot append items to a list. You must redefine the entire list. As the nav configuration is made up of nested lists, this means that you cannot merge navigation items. Of course, you can replace the entire nav configuration with a new one. However, it is generally expected that the entire navigation would be defined in the primary configuration file for a project. Warning As a reminder, all path based configuration options must be relative to the primary configuration file and MkDocs does not alter the paths when merging. Therefore, defining paths in a parent file which is inherited by multiple different sites may not work as expected. It is generally best to define path based options in the primary configuration file only.","title":"Configuration Inheritance"},{"location":"user-guide/customizing-your-theme/","text":"Customizing Your Theme \uf0c1 Altering a theme to suit your needs. If you would like to make a few tweaks to an existing theme, there is no need to create your own theme from scratch. For minor tweaks which only require some CSS and/or JavaScript, you can use the docs_dir . However, for more complex customizations, including overriding templates, you will need to use the theme custom_dir setting. Using the docs_dir \uf0c1 The extra_css and extra_javascript configuration options can be used to make tweaks and customizations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your documentation directory . For example, to change the color of the headers in your documentation, create a file called extra.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Note If you are deploying your documentation with ReadTheDocs . You will need to explicitly list the CSS and JavaScript files you want to include in your config. To do this, add the following to your mkdocs.yml. extra_css: [extra.css] After making these changes, they should be visible when you run mkdocs serve - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML document after the page content. If you desire to include a JavaScript library, you may have better success including the library by using the theme custom_dir . Using the theme custom_dir \uf0c1 The theme.custom_dir configuration option can be used to point to a directory of files which override the files in a parent theme. The parent theme would be the theme defined in the theme.name configuration option. Any file in the custom_dir with the same name as a file in the parent theme will replace the file of the same name in the parent theme. Any additional files in the custom_dir will be added to the parent theme. The contents of the custom_dir should mirror the directory structure of the parent theme. You may include templates, JavaScript files, CSS files, images, fonts, or any other media included in a theme. Note For this to work, the theme.name setting must be set to a known installed theme. If the name setting is instead set to null (or not defined), then there is no theme to override and the contents of the custom_dir must be a complete, standalone theme. See the Theme Developer Guide for more information. For example, the mkdocs theme ( browse source ), contains the following directory structure (in part): - css\\ - fonts\\ - img\\ - favicon.ico - grid.png - js\\ - 404.html - base.html - content.html - nav-sub.html - nav.html - toc.html To override any of the files contained in that theme, create a new directory next to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: theme: name: mkdocs custom_dir: custom_theme/ To override the 404 error page (\"file not found\"), add a new template file named 404.html to the custom_theme directory. For information on what can be included in a template, review the Theme Developer Guide . To override the favicon, you can add a new icon file at custom_theme/img/favicon.ico . To include a JavaScript library, copy the library to the custom_theme/js/ directory. Your directory structure should now look like this: - docs/ - index.html - custom_theme/ - img/ - favicon.ico - js/ - somelib.js - 404.html - config.yml Note Any files included in the parent theme (defined in name ) but not included in the custom_dir will still be utilized. The custom_dir will only override/replace files in the parent theme. If you want to remove files, or build a theme from scratch, then you should review the Theme Developer Guide . Overriding Template Blocks \uf0c1 The built-in themes implement many of their parts inside template blocks which can be individually overridden in the main.html template. Simply create a main.html template file in your custom_dir and define replacement blocks within that file. Just make sure that the main.html extends base.html . For example, to alter the title of the MkDocs theme, your replacement main.html template would contain the following: {% extends \"base.html\" %} {% block htmltitle %} <title>Custom title goes here</title> {% endblock %} In the above example, the htmltitle block defined in your custom main.html file will be used in place of the default htmltitle block defined in the parent theme. You may re-define as many blocks as you desire, as long as those blocks are defined in the parent. For example, you could replace the Google Analytics script with one for a different service or replace the search feature with your own. You will need to consult the parent theme you are using to determine what blocks are available to override. The MkDocs and ReadTheDocs themes provide the following blocks: site_meta : Contains meta tags in the document head. htmltitle : Contains the page title in the document head. styles : Contains the link tags for stylesheets. libs : Contains the JavaScript libraries (jQuery, etc) included in the page header. scripts : Contains JavaScript scripts which should execute after a page loads. analytics : Contains the analytics script. extrahead : An empty block in the <head> to insert custom tags/scripts/etc. site_name : Contains the site name in the navigation bar. site_nav : Contains the site navigation in the navigation bar. search_button : Contains the search box in the navigation bar. next_prev : Contains the next and previous buttons in the navigation bar. repo : Contains the repository link in the navigation bar. content : Contains the page content and table of contents for the page. footer : Contains the page footer. You may need to view the source template files to ensure your modifications will work with the structure of the site. See Template Variables for a list of variables you can use within your custom blocks. For a more complete explanation of blocks, consult the Jinja documentation . Combining the custom_dir and Template Blocks \uf0c1 Adding a JavaScript library to the custom_dir will make it available, but won't include it in the pages generated by MkDocs. Therefore, a link needs to be added to the library from the HTML. Starting the with directory structure above (truncated): - docs/ - custom_theme/ - js/ - somelib.js - config.yml A link to the custom_theme/js/somelib.js file needs to be added to the template. As somelib.js is a JavaScript library, it would logically go in the libs block. However, a new libs block that only includes the new script will replace the block defined in the parent template and any links to libraries in the parent template will be removed. To avoid breaking the template, a super block can be used with a call to super from within the block: {% extends \"base.html\" %} {% block libs %} {{ super() }} <script src=\"{{ base_url }}/js/somelib.js\"></script> {% endblock %} Note that the base_url template variable was used to ensure that the link is always relative to the current page. Now the generated pages will include links to the template provided libraries as well as the library included in the custom_dir . The same would be required for any additional CSS files included in the custom_dir .","title":"Customizing Your Theme"},{"location":"user-guide/customizing-your-theme/#customizing-your-theme","text":"Altering a theme to suit your needs. If you would like to make a few tweaks to an existing theme, there is no need to create your own theme from scratch. For minor tweaks which only require some CSS and/or JavaScript, you can use the docs_dir . However, for more complex customizations, including overriding templates, you will need to use the theme custom_dir setting.","title":"Customizing Your Theme"},{"location":"user-guide/customizing-your-theme/#using-the-docs_dir","text":"The extra_css and extra_javascript configuration options can be used to make tweaks and customizations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your documentation directory . For example, to change the color of the headers in your documentation, create a file called extra.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Note If you are deploying your documentation with ReadTheDocs . You will need to explicitly list the CSS and JavaScript files you want to include in your config. To do this, add the following to your mkdocs.yml. extra_css: [extra.css] After making these changes, they should be visible when you run mkdocs serve - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML document after the page content. If you desire to include a JavaScript library, you may have better success including the library by using the theme custom_dir .","title":"Using the docs_dir"},{"location":"user-guide/customizing-your-theme/#using-the-theme-custom_dir","text":"The theme.custom_dir configuration option can be used to point to a directory of files which override the files in a parent theme. The parent theme would be the theme defined in the theme.name configuration option. Any file in the custom_dir with the same name as a file in the parent theme will replace the file of the same name in the parent theme. Any additional files in the custom_dir will be added to the parent theme. The contents of the custom_dir should mirror the directory structure of the parent theme. You may include templates, JavaScript files, CSS files, images, fonts, or any other media included in a theme. Note For this to work, the theme.name setting must be set to a known installed theme. If the name setting is instead set to null (or not defined), then there is no theme to override and the contents of the custom_dir must be a complete, standalone theme. See the Theme Developer Guide for more information. For example, the mkdocs theme ( browse source ), contains the following directory structure (in part): - css\\ - fonts\\ - img\\ - favicon.ico - grid.png - js\\ - 404.html - base.html - content.html - nav-sub.html - nav.html - toc.html To override any of the files contained in that theme, create a new directory next to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: theme: name: mkdocs custom_dir: custom_theme/ To override the 404 error page (\"file not found\"), add a new template file named 404.html to the custom_theme directory. For information on what can be included in a template, review the Theme Developer Guide . To override the favicon, you can add a new icon file at custom_theme/img/favicon.ico . To include a JavaScript library, copy the library to the custom_theme/js/ directory. Your directory structure should now look like this: - docs/ - index.html - custom_theme/ - img/ - favicon.ico - js/ - somelib.js - 404.html - config.yml Note Any files included in the parent theme (defined in name ) but not included in the custom_dir will still be utilized. The custom_dir will only override/replace files in the parent theme. If you want to remove files, or build a theme from scratch, then you should review the Theme Developer Guide .","title":"Using the theme custom_dir"},{"location":"user-guide/customizing-your-theme/#overriding-template-blocks","text":"The built-in themes implement many of their parts inside template blocks which can be individually overridden in the main.html template. Simply create a main.html template file in your custom_dir and define replacement blocks within that file. Just make sure that the main.html extends base.html . For example, to alter the title of the MkDocs theme, your replacement main.html template would contain the following: {% extends \"base.html\" %} {% block htmltitle %} <title>Custom title goes here</title> {% endblock %} In the above example, the htmltitle block defined in your custom main.html file will be used in place of the default htmltitle block defined in the parent theme. You may re-define as many blocks as you desire, as long as those blocks are defined in the parent. For example, you could replace the Google Analytics script with one for a different service or replace the search feature with your own. You will need to consult the parent theme you are using to determine what blocks are available to override. The MkDocs and ReadTheDocs themes provide the following blocks: site_meta : Contains meta tags in the document head. htmltitle : Contains the page title in the document head. styles : Contains the link tags for stylesheets. libs : Contains the JavaScript libraries (jQuery, etc) included in the page header. scripts : Contains JavaScript scripts which should execute after a page loads. analytics : Contains the analytics script. extrahead : An empty block in the <head> to insert custom tags/scripts/etc. site_name : Contains the site name in the navigation bar. site_nav : Contains the site navigation in the navigation bar. search_button : Contains the search box in the navigation bar. next_prev : Contains the next and previous buttons in the navigation bar. repo : Contains the repository link in the navigation bar. content : Contains the page content and table of contents for the page. footer : Contains the page footer. You may need to view the source template files to ensure your modifications will work with the structure of the site. See Template Variables for a list of variables you can use within your custom blocks. For a more complete explanation of blocks, consult the Jinja documentation .","title":"Overriding Template Blocks"},{"location":"user-guide/customizing-your-theme/#combining-the-custom_dir-and-template-blocks","text":"Adding a JavaScript library to the custom_dir will make it available, but won't include it in the pages generated by MkDocs. Therefore, a link needs to be added to the library from the HTML. Starting the with directory structure above (truncated): - docs/ - custom_theme/ - js/ - somelib.js - config.yml A link to the custom_theme/js/somelib.js file needs to be added to the template. As somelib.js is a JavaScript library, it would logically go in the libs block. However, a new libs block that only includes the new script will replace the block defined in the parent template and any links to libraries in the parent template will be removed. To avoid breaking the template, a super block can be used with a call to super from within the block: {% extends \"base.html\" %} {% block libs %} {{ super() }} <script src=\"{{ base_url }}/js/somelib.js\"></script> {% endblock %} Note that the base_url template variable was used to ensure that the link is always relative to the current page. Now the generated pages will include links to the template provided libraries as well as the library included in the custom_dir . The same would be required for any additional CSS files included in the custom_dir .","title":"Combining the custom_dir and Template Blocks"},{"location":"user-guide/deploying-your-docs/","text":"Deploying your docs \uf0c1 A basic guide to deploying your docs to various hosting providers GitHub Pages \uf0c1 If you host the source code for a project on GitHub , you can easily use GitHub Pages to host the documentation for your project. There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences, which require a different work flow when deploying. Project Pages \uf0c1 Project Pages sites are simpler as the site files get deployed to a branch within the project repository ( gh-pages by default). After you checkout the primary working branch (usually master ) of the git repository where you maintain the source documentation for your project, run the following command: mkdocs gh-deploy That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command. Organization and User Pages \uf0c1 User and Organization Pages sites are not tied to a specific project, and the site files are deployed to the master branch in a dedicated repository named with the GitHub account name. Therefore, you need working copies of two repositories on our local system. For example, consider the following file structure: my-project/ mkdocs.yml docs/ orgname.github.io/ After making and verifying updates to your project you need to change directories to the orgname.github.io repository and call the mkdocs gh-deploy command from there: cd ../orgname.github.io/ mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master Note that you need to explicitly point to the mkdocs.yml configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the master branch. You may override the default with the remote_branch configuration setting, but if you forget to change directories before running the deploy script, it will commit to the master branch of your project, which you probably don't want. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command. Custom Domains \uf0c1 GitHub Pages includes support for using a Custom Domain for your site. In addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a CNAME file to the root of your docs_dir . The file must contain a single bare domain or subdomain on a single line (see MkDocs' own CNAME file as an example). You may create the file manually, or use GitHub's web interface to set up the custom domain (under Settings / Custom Domain). If you use the web interface, GitHub will create the CNAME file for you and save it to the root of your \"pages\" branch. So that the file does not get removed the next time you deploy, you need to copy the file to your docs_dir . With the file properly included in your docs_dir , MkDocs will include the file in your built site and push it to your \"pages\" branch each time you run the gh-deploy command. If you are having problems getting a custom domain to work, see GitHub's documentation on Troubleshooting custom domains . Read the Docs \uf0c1 Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository. Note To benefit from all of the features offered by Read the Docs, you will need to use the Read the Docs theme which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs. Other Providers \uf0c1 Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp , ssh or scp client to transfer the files. For example, a typical set of commands from the command line might look something like this: mkdocs build scp -r ./site user@host:/path/to/server/root Of course, you will need to replace user with the username you have with your hosting provider and host with the appropriate domain name. Additionally, you will need to adjust the /path/to/server/root to match the configuration of your hosts' file system. See your host's documentation for specifics. You will likely want to search their documentation for \"ftp\" or \"uploading site\". Local Files \uf0c1 Rather than hosting your documentation on a server, you may instead distribute the files directly, which can then be viewed in a browser using the file:// scheme. Note that, due to the security settings of all modern browsers, some things will not work the same and some features may not work at all. In fact, a few settings will need to be customized in very specific ways. site_url : The site_url must be set to an empty string, which instructs MkDocs to build your site so that it will work with the file:// scheme. site_url: \"\" use_directory_urls : Set use_directory_urls to false . Otherwise, internal links between pages will not work properly. use_directory_urls: false search : You will need to either disable the search plugin, or use a third-party search plugin which is specifically designed to work with the file:// scheme. To disable all plugins, set the plugins setting to an empty list. plugins: [] If you have other plugins enabled, simply ensure that search is not included in the list. When writing your documentation, it is imperative that all internal links use relative URLs as documented . Remember, each reader of your documentation will be using a different device and the files will likely be in a different location on that device. If you expect your documentation to be viewed off-line, you may also need to be careful about which themes you choose. Many themes make use of CDNs for various support files, which require a live Internet connection. You will need to choose a theme which includes all support files directly in the theme. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory and distribute it to your readers. Alternatively, you may choose to use a third party tool to convert the HTML files to some other documentation format. 404 Pages \uf0c1 When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.","title":"Deploying Your Docs"},{"location":"user-guide/deploying-your-docs/#deploying-your-docs","text":"A basic guide to deploying your docs to various hosting providers","title":"Deploying your docs"},{"location":"user-guide/deploying-your-docs/#github-pages","text":"If you host the source code for a project on GitHub , you can easily use GitHub Pages to host the documentation for your project. There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences, which require a different work flow when deploying.","title":"GitHub Pages"},{"location":"user-guide/deploying-your-docs/#project-pages","text":"Project Pages sites are simpler as the site files get deployed to a branch within the project repository ( gh-pages by default). After you checkout the primary working branch (usually master ) of the git repository where you maintain the source documentation for your project, run the following command: mkdocs gh-deploy That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command.","title":"Project Pages"},{"location":"user-guide/deploying-your-docs/#organization-and-user-pages","text":"User and Organization Pages sites are not tied to a specific project, and the site files are deployed to the master branch in a dedicated repository named with the GitHub account name. Therefore, you need working copies of two repositories on our local system. For example, consider the following file structure: my-project/ mkdocs.yml docs/ orgname.github.io/ After making and verifying updates to your project you need to change directories to the orgname.github.io repository and call the mkdocs gh-deploy command from there: cd ../orgname.github.io/ mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master Note that you need to explicitly point to the mkdocs.yml configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the master branch. You may override the default with the remote_branch configuration setting, but if you forget to change directories before running the deploy script, it will commit to the master branch of your project, which you probably don't want. Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally. Warning You should never edit files in your pages repository by hand if you're using the gh-deploy command because you will lose your work the next time you run the command.","title":"Organization and User Pages"},{"location":"user-guide/deploying-your-docs/#custom-domains","text":"GitHub Pages includes support for using a Custom Domain for your site. In addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a CNAME file to the root of your docs_dir . The file must contain a single bare domain or subdomain on a single line (see MkDocs' own CNAME file as an example). You may create the file manually, or use GitHub's web interface to set up the custom domain (under Settings / Custom Domain). If you use the web interface, GitHub will create the CNAME file for you and save it to the root of your \"pages\" branch. So that the file does not get removed the next time you deploy, you need to copy the file to your docs_dir . With the file properly included in your docs_dir , MkDocs will include the file in your built site and push it to your \"pages\" branch each time you run the gh-deploy command. If you are having problems getting a custom domain to work, see GitHub's documentation on Troubleshooting custom domains .","title":"Custom Domains"},{"location":"user-guide/deploying-your-docs/#read-the-docs","text":"Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository. Note To benefit from all of the features offered by Read the Docs, you will need to use the Read the Docs theme which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs.","title":"Read the Docs"},{"location":"user-guide/deploying-your-docs/#other-providers","text":"Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp , ssh or scp client to transfer the files. For example, a typical set of commands from the command line might look something like this: mkdocs build scp -r ./site user@host:/path/to/server/root Of course, you will need to replace user with the username you have with your hosting provider and host with the appropriate domain name. Additionally, you will need to adjust the /path/to/server/root to match the configuration of your hosts' file system. See your host's documentation for specifics. You will likely want to search their documentation for \"ftp\" or \"uploading site\".","title":"Other Providers"},{"location":"user-guide/deploying-your-docs/#local-files","text":"Rather than hosting your documentation on a server, you may instead distribute the files directly, which can then be viewed in a browser using the file:// scheme. Note that, due to the security settings of all modern browsers, some things will not work the same and some features may not work at all. In fact, a few settings will need to be customized in very specific ways. site_url : The site_url must be set to an empty string, which instructs MkDocs to build your site so that it will work with the file:// scheme. site_url: \"\" use_directory_urls : Set use_directory_urls to false . Otherwise, internal links between pages will not work properly. use_directory_urls: false search : You will need to either disable the search plugin, or use a third-party search plugin which is specifically designed to work with the file:// scheme. To disable all plugins, set the plugins setting to an empty list. plugins: [] If you have other plugins enabled, simply ensure that search is not included in the list. When writing your documentation, it is imperative that all internal links use relative URLs as documented . Remember, each reader of your documentation will be using a different device and the files will likely be in a different location on that device. If you expect your documentation to be viewed off-line, you may also need to be careful about which themes you choose. Many themes make use of CDNs for various support files, which require a live Internet connection. You will need to choose a theme which includes all support files directly in the theme. When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to \"site\" ) in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory and distribute it to your readers. Alternatively, you may choose to use a third party tool to convert the HTML files to some other documentation format.","title":"Local Files"},{"location":"user-guide/deploying-your-docs/#404-pages","text":"When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.","title":"404 Pages"},{"location":"user-guide/installation/","text":"MkDocs Installation \uf0c1 A detailed guide. Requirements \uf0c1 MkDocs requires a recent version of Python and the Python package manager, pip , to be installed on your system. You can check if you already have these installed from the command line: $ python --version Python 3.8.2 $ pip --version pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) If you already have those packages installed, you may skip down to Installing MkDocs . Installing Python \uf0c1 Install Python using your package manager of choice, or by downloading an installer appropriate for your system from python.org and running it. Note If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default). Installing pip \uf0c1 If you're using a recent version of Python, the Python package manager, pip , is most likely installed by default. However, you may need to upgrade pip to the lasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py . Then run the following command to install it: python get-pip.py Installing MkDocs \uf0c1 Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay. $ mkdocs --version mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) Note If you would like manpages installed for MkDocs, the click-man tool can generate and install them for you. Simply run the following two commands: pip install click-man click-man --target path/to/man/pages mkdocs See the click-man documentation for an explanation of why manpages are not automatically generated and installed by pip. Note If you are using Windows, some of the above commands may not work out-of-the-box. A quick solution may be to preface every Python command with python -m like this: python -m pip install mkdocs python -m mkdocs For a more permanent solution, you may need to edit your PATH environment variable to include the Scripts directory of your Python installation. Recent versions of Python include a script to do this for you. Navigate to your Python installation directory (for example C:\\Python38\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double clicking on it. Alternatively, you can download the script and run it ( python win_add2path.py ).","title":"Installation"},{"location":"user-guide/installation/#mkdocs-installation","text":"A detailed guide.","title":"MkDocs Installation"},{"location":"user-guide/installation/#requirements","text":"MkDocs requires a recent version of Python and the Python package manager, pip , to be installed on your system. You can check if you already have these installed from the command line: $ python --version Python 3.8.2 $ pip --version pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) If you already have those packages installed, you may skip down to Installing MkDocs .","title":"Requirements"},{"location":"user-guide/installation/#installing-python","text":"Install Python using your package manager of choice, or by downloading an installer appropriate for your system from python.org and running it. Note If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default).","title":"Installing Python"},{"location":"user-guide/installation/#installing-pip","text":"If you're using a recent version of Python, the Python package manager, pip , is most likely installed by default. However, you may need to upgrade pip to the lasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py . Then run the following command to install it: python get-pip.py","title":"Installing pip"},{"location":"user-guide/installation/#installing-mkdocs","text":"Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay. $ mkdocs --version mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) Note If you would like manpages installed for MkDocs, the click-man tool can generate and install them for you. Simply run the following two commands: pip install click-man click-man --target path/to/man/pages mkdocs See the click-man documentation for an explanation of why manpages are not automatically generated and installed by pip. Note If you are using Windows, some of the above commands may not work out-of-the-box. A quick solution may be to preface every Python command with python -m like this: python -m pip install mkdocs python -m mkdocs For a more permanent solution, you may need to edit your PATH environment variable to include the Scripts directory of your Python installation. Recent versions of Python include a script to do this for you. Navigate to your Python installation directory (for example C:\\Python38\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double clicking on it. Alternatively, you can download the script and run it ( python win_add2path.py ).","title":"Installing MkDocs"},{"location":"user-guide/localizing-your-theme/","text":"Localizing Your Theme \uf0c1 Display your theme in your preferred language. Note Theme localization only translates the text elements of the theme itself (such as \"next\" and \"previous\" links), not the actual content of your documentation. If you wish to create multilingual documentation, you need to combine theme localization as described here with a third-party internationalization/localization plugin. Installation \uf0c1 For theme localization to work, you must use a theme which supports it and enable i18n (internationalization) support by installing mkdocs[i18n] : pip install mkdocs[i18n] Supported locales \uf0c1 In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation for your language. However, a locale may also include a territory (or region or county) code as well. The language and territory must be separated by an underscore. For example, some possible locales for English might include en , en_AU , en_GB , and en_US . For a list of locales supported by the theme you are using, see that theme's documentation. mkdocs readthedocs Warning If you configure a language locale which is not yet supported by the theme that you are using, MkDocs will fall back to the theme's default locale. Usage \uf0c1 To specify the locale that MkDocs should use, set the locale parameter of the theme configuration option to the appropriate code. For example, to build the mkdocs theme in French you would use the following in your mkdocs.yml configuration file: theme: name: mkdocs locale: fr Contributing theme translations \uf0c1 If a theme has not yet been translated into your language, feel free to contribute a translation using the Translation Guide .","title":"Localizing Your Theme"},{"location":"user-guide/localizing-your-theme/#localizing-your-theme","text":"Display your theme in your preferred language. Note Theme localization only translates the text elements of the theme itself (such as \"next\" and \"previous\" links), not the actual content of your documentation. If you wish to create multilingual documentation, you need to combine theme localization as described here with a third-party internationalization/localization plugin.","title":"Localizing Your Theme"},{"location":"user-guide/localizing-your-theme/#installation","text":"For theme localization to work, you must use a theme which supports it and enable i18n (internationalization) support by installing mkdocs[i18n] : pip install mkdocs[i18n]","title":"Installation"},{"location":"user-guide/localizing-your-theme/#supported-locales","text":"In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation for your language. However, a locale may also include a territory (or region or county) code as well. The language and territory must be separated by an underscore. For example, some possible locales for English might include en , en_AU , en_GB , and en_US . For a list of locales supported by the theme you are using, see that theme's documentation. mkdocs readthedocs Warning If you configure a language locale which is not yet supported by the theme that you are using, MkDocs will fall back to the theme's default locale.","title":"Supported locales"},{"location":"user-guide/localizing-your-theme/#usage","text":"To specify the locale that MkDocs should use, set the locale parameter of the theme configuration option to the appropriate code. For example, to build the mkdocs theme in French you would use the following in your mkdocs.yml configuration file: theme: name: mkdocs locale: fr","title":"Usage"},{"location":"user-guide/localizing-your-theme/#contributing-theme-translations","text":"If a theme has not yet been translated into your language, feel free to contribute a translation using the Translation Guide .","title":"Contributing theme translations"},{"location":"user-guide/writing-your-docs/","text":"Writing your docs \uf0c1 How to layout and write your Markdown source files. File layout \uf0c1 Your documentation source should be written as regular Markdown files (see Writing with Markdown below), and placed in the documentation directory . By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml docs/ index.md By convention your project homepage should be named index.md (see Index pages below for details). Any of the following file extensions may be used for your Markdown source files: markdown , mdown , mkdn , mkd , md . All Markdown files included in your documentation directory will be rendered in the built site regardless of any settings. Note Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md ) are ignored by MkDocs, which matches the behavior of most web servers. There is no option to override this behavior. You can also create multi-page documentation, by creating several Markdown files: mkdocs.yml docs/ index.md about.md license.md The file layout you use determines the URLs that are used for the generated pages. Given the above layout, pages would be generated for the following URLs: / /about/ /license/ You can also include your Markdown files in nested directories if that better suits your documentation layout. docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md Source files inside nested directories will cause pages to be generated with nested URLs, like so: / /user-guide/getting-started/ /user-guide/configuration-options/ /license/ Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See how to link to images and media below for details. Index pages \uf0c1 When a directory is requested, by default, most web servers will return an index file (usually named index.html ) contained within that directory if one exists. For that reason, the homepage in all of the examples above has been named index.md , which MkDocs will render to index.html when building the site. Many repository hosting sites provide special treatment for README files by displaying the contents of the README file when browsing the contents of a directory. Therefore, MkDocs will allow you to name your index pages as README.md instead of index.md . In that way, when users are browsing your source code, the repository host can display the index page of that directory as it is a README file. However, when MkDocs renders your site, the file will be renamed to index.html so that the server will serve it as a proper index file. If both an index.md file and a README.md file are found in the same directory, then the index.md file is used and the README.md file is ignored. Configure Pages and Navigation \uf0c1 The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu. If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory . An automatically created navigation configuration will always be sorted alphanumerically by file name (except that index files will always be listed first within a sub-section). You will need to manually define your navigation configuration if you would like your navigation menu sorted differently. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths in the navigation configuration must be relative to the docs_dir configuration option. If that option is set to the default value, docs , the source files for the above configuration would be located at docs/index.md and docs/about.md . The above example will result in two navigation items being created at the top level and with their titles inferred from the contents of the Markdown file or, if no title is defined within the file, of the file name. To override the title in the nav setting add a title right before the filename. nav: - Home: 'index.md' - About: 'about.md' Note that if a title is defined for a page in the navigation, that title will be used throughout the site for that page and will override any title defined within the page itself. Navigation sub-sections can be created by listing related pages together under a section title. For example: nav: - Home: 'index.md' - 'User Guide': - 'Writing your docs': 'writing-your-docs.md' - 'Styling your docs': 'styling-your-docs.md' - About: - 'License': 'license.md' - 'Release Notes': 'release-notes.md' With the above configuration we have three top level items: \"Home\", \"User Guide\" and \"About.\" \"Home\" is a link to the homepage for the site. Under the \"User Guide\" section two pages are listed: \"Writing your docs\" and \"Styling your docs.\" Under the \"About\" section two more pages are listed: \"License\" and \"Release Notes.\" Note that a section cannot have a page assigned to it. Sections are only containers for child pages and sub-sections. You may nest sections as deeply as you like. However, be careful that you don't make it too difficult for your users to navigate through the site navigation by over-complicating the nesting. While sections may mirror your directory structure, they do not have to. Any pages not listed in your navigation configuration will still be rendered and included with the built site, however, they will not be linked from the global navigation and will not be included in the previous and next links. Such pages will be \"hidden\" unless linked to directly. Writing with Markdown \uf0c1 MkDocs pages must be authored in Markdown , a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner. MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation , although there are a few very minor differences . In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions . See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions. MkDocs includes some extensions by default, which are highlighted below. Internal links \uf0c1 MkDocs allows you to interlink your documentation by using regular Markdown links . However, there are a few additional benefits to formatting those links specifically for MkDocs as outlined below. Linking to pages \uf0c1 When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to. Please see the [project license](license.md) for further details. When the MkDocs build runs, these Markdown links will automatically be transformed into an HTML hyperlink to the appropriate HTML page. Warning Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server. If the target documentation file is in another directory you'll need to make sure to include any relative directory path in the link. Please see the [project license](../about/license.md) for further details. The toc extension is used by MkDocs to generate an ID for every header in your Markdown documents. You can use that ID to link to a section within a target document by using an anchor link. The generated HTML will correctly transform the path portion of the link, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details. Note that IDs are created from the text of a header. All text is converted to lowercase and any disallowed characters, including white-space, are converted to dashes. Consecutive dashes are then reduced to a single dash. There are a few configuration settings provided by the toc extension which you can set in your mkdocs.yml configuration file to alter the default behavior: permalink : Generate permanent links at the end of each header. Default: False . When set to True the paragraph symbol (\u00b6 or &para; ) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol ( # ) instead, do: markdown_extensions: - toc: permalink: \"#\" baselevel : Base level for headers. Default: 1 . This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 ( <h2> ), do: markdown_extensions: - toc: baselevel: 2 Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header ( <h2> ) in the HTML output. separator : Word separator. Default: - . Character which replaces white-space in generated IDs. If you prefer underscores, then do: markdown_extensions: - toc: separator: \"_\" Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option. markdown_extensions: - toc: permalink: \"#\" baselevel: 2 separator: \"_\" Linking to images and media \uf0c1 As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media. For example, if your project documentation needed to include a GitHub pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows: mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png To include images in your documentation source files, simply use any of the regular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes. ![Screenshot](img/screenshot.png) *Above: Cupcake indexer in progress* Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor. Linking from raw HTML \uf0c1 Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document. Meta-Data \uf0c1 MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any. In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported: template : The template to use with the current page. By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment. title : The \"title\" to use for the document. MkDocs will attempt to determine the title of a document in the following ways, in order: A title defined in the nav configuration setting for a document. A title defined in the title meta-data key of a document. A level 1 Markdown header on the first line of the document body. Please note that Setext-style headers are not supported. The filename of a document. Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list. YAML Style Meta-Data \uf0c1 YAML style meta-data consists of YAML key/value pairs wrapped in YAML style deliminators to mark the start and/or end of the meta-data. The first line of a document must be --- . The meta-data ends at the first line containing an end deliminator (either --- or ... ). The content between the deliminators is parsed as YAML . --- title: My Document summary: A brief description of my document. authors: - Waylan Limberg - Tom Christie date: 2018-07-10 some_url: https://example.com --- This is the first paragraph of the document. YAML is able to detect data types. Therefore, in the above example, the values of title , summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document. MultiMarkdown Style Meta-Data \uf0c1 MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this: Title: My Document Summary: A brief description of my document. Authors: Waylan Limberg Tom Christie Date: January 23, 2018 blank-value: some_url: https://example.com This is the first paragraph of the document. The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string. The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. Note MkDocs does not support YAML style deliminators ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the deliminators to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Tables \uf0c1 The tables extension adds a basic table syntax to Markdown which is popular across multiple implementations. The syntax is rather simple and is generally only useful for simple tabular data. A simple table looks like this: First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell Content Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | | Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header :----------- |:-------------:| -----------: Left | Center | Right Left | Center | Right Note that table cells cannot contain any block level elements and cannot contain multiple lines of text. They can, however, include inline Markdown as defined in Markdown's syntax rules. Additionally, a table must be surrounded by blank lines. There must be a blank line before and after the table. Fenced code blocks \uf0c1 The fenced code blocks extension adds an alternate method of defining code blocks without indentation. The first line should contain 3 or more backtick ( ` ) characters, and the last line should contain the same number of backtick characters ( ` ): ``` Fenced code blocks are like Standard Markdown\u2019s regular code blocks, except that they\u2019re not indented and instead rely on start and end fence lines to delimit the code block. ``` With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used: ```python def fn(): pass ``` Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.","title":"Writing Your Docs"},{"location":"user-guide/writing-your-docs/#writing-your-docs","text":"How to layout and write your Markdown source files.","title":"Writing your docs"},{"location":"user-guide/writing-your-docs/#file-layout","text":"Your documentation source should be written as regular Markdown files (see Writing with Markdown below), and placed in the documentation directory . By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml docs/ index.md By convention your project homepage should be named index.md (see Index pages below for details). Any of the following file extensions may be used for your Markdown source files: markdown , mdown , mkdn , mkd , md . All Markdown files included in your documentation directory will be rendered in the built site regardless of any settings. Note Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md ) are ignored by MkDocs, which matches the behavior of most web servers. There is no option to override this behavior. You can also create multi-page documentation, by creating several Markdown files: mkdocs.yml docs/ index.md about.md license.md The file layout you use determines the URLs that are used for the generated pages. Given the above layout, pages would be generated for the following URLs: / /about/ /license/ You can also include your Markdown files in nested directories if that better suits your documentation layout. docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md Source files inside nested directories will cause pages to be generated with nested URLs, like so: / /user-guide/getting-started/ /user-guide/configuration-options/ /license/ Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See how to link to images and media below for details.","title":"File layout"},{"location":"user-guide/writing-your-docs/#index-pages","text":"When a directory is requested, by default, most web servers will return an index file (usually named index.html ) contained within that directory if one exists. For that reason, the homepage in all of the examples above has been named index.md , which MkDocs will render to index.html when building the site. Many repository hosting sites provide special treatment for README files by displaying the contents of the README file when browsing the contents of a directory. Therefore, MkDocs will allow you to name your index pages as README.md instead of index.md . In that way, when users are browsing your source code, the repository host can display the index page of that directory as it is a README file. However, when MkDocs renders your site, the file will be renamed to index.html so that the server will serve it as a proper index file. If both an index.md file and a README.md file are found in the same directory, then the index.md file is used and the README.md file is ignored.","title":"Index pages"},{"location":"user-guide/writing-your-docs/#configure-pages-and-navigation","text":"The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu. If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory . An automatically created navigation configuration will always be sorted alphanumerically by file name (except that index files will always be listed first within a sub-section). You will need to manually define your navigation configuration if you would like your navigation menu sorted differently. A minimal navigation configuration could look like this: nav: - 'index.md' - 'about.md' All paths in the navigation configuration must be relative to the docs_dir configuration option. If that option is set to the default value, docs , the source files for the above configuration would be located at docs/index.md and docs/about.md . The above example will result in two navigation items being created at the top level and with their titles inferred from the contents of the Markdown file or, if no title is defined within the file, of the file name. To override the title in the nav setting add a title right before the filename. nav: - Home: 'index.md' - About: 'about.md' Note that if a title is defined for a page in the navigation, that title will be used throughout the site for that page and will override any title defined within the page itself. Navigation sub-sections can be created by listing related pages together under a section title. For example: nav: - Home: 'index.md' - 'User Guide': - 'Writing your docs': 'writing-your-docs.md' - 'Styling your docs': 'styling-your-docs.md' - About: - 'License': 'license.md' - 'Release Notes': 'release-notes.md' With the above configuration we have three top level items: \"Home\", \"User Guide\" and \"About.\" \"Home\" is a link to the homepage for the site. Under the \"User Guide\" section two pages are listed: \"Writing your docs\" and \"Styling your docs.\" Under the \"About\" section two more pages are listed: \"License\" and \"Release Notes.\" Note that a section cannot have a page assigned to it. Sections are only containers for child pages and sub-sections. You may nest sections as deeply as you like. However, be careful that you don't make it too difficult for your users to navigate through the site navigation by over-complicating the nesting. While sections may mirror your directory structure, they do not have to. Any pages not listed in your navigation configuration will still be rendered and included with the built site, however, they will not be linked from the global navigation and will not be included in the previous and next links. Such pages will be \"hidden\" unless linked to directly.","title":"Configure Pages and Navigation"},{"location":"user-guide/writing-your-docs/#writing-with-markdown","text":"MkDocs pages must be authored in Markdown , a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner. MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation , although there are a few very minor differences . In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions . See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions. MkDocs includes some extensions by default, which are highlighted below.","title":"Writing with Markdown"},{"location":"user-guide/writing-your-docs/#internal-links","text":"MkDocs allows you to interlink your documentation by using regular Markdown links . However, there are a few additional benefits to formatting those links specifically for MkDocs as outlined below.","title":"Internal links"},{"location":"user-guide/writing-your-docs/#linking-to-pages","text":"When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to. Please see the [project license](license.md) for further details. When the MkDocs build runs, these Markdown links will automatically be transformed into an HTML hyperlink to the appropriate HTML page. Warning Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server. If the target documentation file is in another directory you'll need to make sure to include any relative directory path in the link. Please see the [project license](../about/license.md) for further details. The toc extension is used by MkDocs to generate an ID for every header in your Markdown documents. You can use that ID to link to a section within a target document by using an anchor link. The generated HTML will correctly transform the path portion of the link, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details. Note that IDs are created from the text of a header. All text is converted to lowercase and any disallowed characters, including white-space, are converted to dashes. Consecutive dashes are then reduced to a single dash. There are a few configuration settings provided by the toc extension which you can set in your mkdocs.yml configuration file to alter the default behavior: permalink : Generate permanent links at the end of each header. Default: False . When set to True the paragraph symbol (\u00b6 or &para; ) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol ( # ) instead, do: markdown_extensions: - toc: permalink: \"#\" baselevel : Base level for headers. Default: 1 . This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 ( <h2> ), do: markdown_extensions: - toc: baselevel: 2 Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header ( <h2> ) in the HTML output. separator : Word separator. Default: - . Character which replaces white-space in generated IDs. If you prefer underscores, then do: markdown_extensions: - toc: separator: \"_\" Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option. markdown_extensions: - toc: permalink: \"#\" baselevel: 2 separator: \"_\"","title":"Linking to pages"},{"location":"user-guide/writing-your-docs/#linking-to-images-and-media","text":"As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media. For example, if your project documentation needed to include a GitHub pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows: mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png To include images in your documentation source files, simply use any of the regular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes. ![Screenshot](img/screenshot.png) *Above: Cupcake indexer in progress* Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor.","title":"Linking to images and media"},{"location":"user-guide/writing-your-docs/#linking-from-raw-html","text":"Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.","title":"Linking from raw HTML"},{"location":"user-guide/writing-your-docs/#meta-data","text":"MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any. In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported: template : The template to use with the current page. By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment. title : The \"title\" to use for the document. MkDocs will attempt to determine the title of a document in the following ways, in order: A title defined in the nav configuration setting for a document. A title defined in the title meta-data key of a document. A level 1 Markdown header on the first line of the document body. Please note that Setext-style headers are not supported. The filename of a document. Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list.","title":"Meta-Data"},{"location":"user-guide/writing-your-docs/#yaml-style-meta-data","text":"YAML style meta-data consists of YAML key/value pairs wrapped in YAML style deliminators to mark the start and/or end of the meta-data. The first line of a document must be --- . The meta-data ends at the first line containing an end deliminator (either --- or ... ). The content between the deliminators is parsed as YAML . --- title: My Document summary: A brief description of my document. authors: - Waylan Limberg - Tom Christie date: 2018-07-10 some_url: https://example.com --- This is the first paragraph of the document. YAML is able to detect data types. Therefore, in the above example, the values of title , summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document.","title":"YAML Style Meta-Data"},{"location":"user-guide/writing-your-docs/#multimarkdown-style-meta-data","text":"MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this: Title: My Document Summary: A brief description of my document. Authors: Waylan Limberg Tom Christie Date: January 23, 2018 blank-value: some_url: https://example.com This is the first paragraph of the document. The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string. The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. Note MkDocs does not support YAML style deliminators ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the deliminators to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data.","title":"MultiMarkdown Style Meta-Data"},{"location":"user-guide/writing-your-docs/#tables","text":"The tables extension adds a basic table syntax to Markdown which is popular across multiple implementations. The syntax is rather simple and is generally only useful for simple tabular data. A simple table looks like this: First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell Content Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | | Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header :----------- |:-------------:| -----------: Left | Center | Right Left | Center | Right Note that table cells cannot contain any block level elements and cannot contain multiple lines of text. They can, however, include inline Markdown as defined in Markdown's syntax rules. Additionally, a table must be surrounded by blank lines. There must be a blank line before and after the table.","title":"Tables"},{"location":"user-guide/writing-your-docs/#fenced-code-blocks","text":"The fenced code blocks extension adds an alternate method of defining code blocks without indentation. The first line should contain 3 or more backtick ( ` ) characters, and the last line should contain the same number of backtick characters ( ` ): ``` Fenced code blocks are like Standard Markdown\u2019s regular code blocks, except that they\u2019re not indented and instead rely on start and end fence lines to delimit the code block. ``` With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used: ```python def fn(): pass ``` Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.","title":"Fenced code blocks"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 0c6e703c..c72b7eb1 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,87 +2,87 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://www.mkdocs.org/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/getting-started/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/about/contributing/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/about/license/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/about/release-notes/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/dev-guide/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/dev-guide/plugins/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/dev-guide/themes/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/dev-guide/translations/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/choosing-your-theme/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/configuration/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/customizing-your-theme/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/deploying-your-docs/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/installation/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/localizing-your-theme/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.mkdocs.org/user-guide/writing-your-docs/</loc>
-         <lastmod>2021-07-18</lastmod>
+         <lastmod>2021-10-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index fa5ac90efbe5994ed3a6c238f5274c509230cd6a..160f7d0d573b32818546826128099dbcde92eeb2 100644
GIT binary patch
delta 329
zcmV-P0k;0z0@?xyABzYGhXiI}kq8`r($hAj>1|K2JpctaK_fWBrdjv&BWYFTy3544
z0Or@PPqt;z9=}FcTp*A|e<+)(E(`D)jrIMZe1CftPvx=OwJ|sXE|S>Op&Xc}7b)j?
zuE;WsYN855FG&ySLh>Gzb@g0!yCSW{;C5P9>ri)#3*BwT4}<z<(#qv=t5w8*Bbshs
z?;Fw7qS+_OJ+_hQLHQoe0X{pUth=^y6S+ai2gNUVdSFi35X34lnC$q}2_s95o`XHb
z1vOJdXEk_&Oz8qRPz1sw17*i(;3E2H4P;C<x!7BubM82er>u+1L3whD(=g5tGZKVM
zn{b1s2Si%t^%Y|fYsIt1MSr$9eGF^Ovj&aCINI<3lUf6l!|Q{0k>re<Mkg!hvTuZ>
bQtm(X!5l3AaTlyx`Y?At-<x|-U<&{MEO4CW

delta 330
zcmV-Q0k!_x0^0%zABzYGw14zqkq8`r+RM5rO>cXG?Exsb2^zr}HqE-HA4#h!*Ig#Y
z1u(yUeX=c!=J++Z;sSvz`a`*`>aqZ@(OBOd%J;Wdu`iG9risB3aFN8G4rR|gzDPMu
zQ$?0xP$N|sI!U@u7n1j&tgGj;-4tof2Dj6)8i%@_UFdEzd>GU>lSa;uYpo)G9?-PA
zdbbtzli2Q)<Q`kebgz5|=K!CrQPy1>xr*E%<b&cDJRLBnYzSf%7)*A2>V%P{M$f^X
z;*6RpqO%%2L8f#894G?ek%6*fG;k4Jv<5OJ8(r+I&pCIT##7eC<)Az{#c3GlhZzY%
zrcJm)(>)^1^ZJT0h^69L<Dx$~+b)Ks=2?SAVjS%E|4FTZ(c$&MJ4<rLO{0^QbJ;gS
cQYrVJ`d|u{|F{d5Eq$2V9|}h0vtSDV0D@ScO8@`>

diff --git a/user-guide/choosing-your-theme/index.html b/user-guide/choosing-your-theme/index.html
index 14a90156..a524356d 100644
--- a/user-guide/choosing-your-theme/index.html
+++ b/user-guide/choosing-your-theme/index.html
@@ -293,6 +293,9 @@ the key code for a given key.</p>
 <li><code>en</code>: English (default)</li>
 <li><code>fr</code>: French</li>
 <li><code>es</code>: Spanish</li>
+<li><code>ja</code>: Japanese</li>
+<li><code>pt_BR</code>: Portuguese (Brazil)</li>
+<li><code>zh_CN</code>: Simplified Chinese</li>
 </ul>
 <p>See the guide on <a href="../localizing-your-theme/">localizing your theme</a> for more information.</p>
 </li>
@@ -374,6 +377,9 @@ tracking ID, which uses the <code>G-</code> format. See Google's documentation t
 <li><code>en</code>: English (default)</li>
 <li><code>fr</code>: French</li>
 <li><code>es</code>: Spanish</li>
+<li><code>ja</code>: Japanese</li>
+<li><code>pt_BR</code>: Portuguese (Brazil)</li>
+<li><code>zh_CN</code>: Simplified Chinese</li>
 </ul>
 <p>See the guide on <a href="../localizing-your-theme/">localizing your theme</a> for more information.</p>
 </li>
diff --git a/user-guide/configuration/index.html b/user-guide/configuration/index.html
index 7b80bb98..e05ed309 100644
--- a/user-guide/configuration/index.html
+++ b/user-guide/configuration/index.html
@@ -209,8 +209,9 @@
 <p>Guide to all available configuration settings.</p>
 <hr />
 <h2 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link"></a></h2>
-<p>Project settings are always configured by using a YAML configuration file in the
-project directory named <code>mkdocs.yml</code>.</p>
+<p>Project settings are configured by default using a YAML configuration file in
+the project directory named <code>mkdocs.yml</code>. You can specify another path for it
+by using the <code>-f</code>/<code>--config-file</code> option (see <code>mkdocs build --help</code>).</p>
 <p>As a minimum, this configuration file must contain the <code>site_name</code> and
 <code>site_url</code> settings. All other settings are optional.</p>
 <h2 id="project-information">Project information<a class="headerlink" href="#project-information" title="Permanent link"></a></h2>
@@ -228,7 +229,7 @@ MkDocs site will be within a subdirectory of a domain, be sure to include that
 subdirectory in the setting (<code>https://example.com/foo/</code>).</p>
 <p>This setting is also used for <code>mkdocs serve</code>: the server will be mounted onto a
 path taken from the path component of the URL, e.g. <code>some/page.md</code> will be
-served from <code>http://127.0.0.1:8000/foo/some/page/</code> to mimick the expected remote
+served from <code>http://127.0.0.1:8000/foo/some/page/</code> to mimic the expected remote
 layout.</p>
 <p><strong>default</strong>: <code>null</code></p>
 <h3 id="repo_url">repo_url<a class="headerlink" href="#repo_url" title="Permanent link"></a></h3>
@@ -666,7 +667,7 @@ themes do). Set to <code>true</code> to enable.</p>
 <p class="admonition-title">Warning</p>
 <p>This option requires that <a href="https://nodejs.org/">Node.js</a> be installed and the command <code>node</code> be
 on the system path. If the call to <code>node</code> fails for any reason, a warning
-is issued and the build continues uninterupted. You may use the <code>--strict</code>
+is issued and the build continues uninterrupted. You may use the <code>--strict</code>
 flag when building to cause such a failure to raise an error instead.</p>
 </div>
 <div class="admonition note">
diff --git a/user-guide/installation/index.html b/user-guide/installation/index.html
index 6d27d6ed..e3730d00 100644
--- a/user-guide/installation/index.html
+++ b/user-guide/installation/index.html
@@ -185,7 +185,7 @@
 <p>A detailed guide.</p>
 <hr />
 <h2 id="requirements">Requirements<a class="headerlink" href="#requirements" title="Permanent link"></a></h2>
-<p>MkDocs requires a recent version of <a href="https://www.python.org/">Python</a> and the the Python package
+<p>MkDocs requires a recent version of <a href="https://www.python.org/">Python</a> and the Python package
 manager, <a href="https://pip.readthedocs.io/en/stable/installing/">pip</a>, to be installed on your system.</p>
 <p>You can check if you already have these installed from the command line:</p>
 <pre><code class="language-bash">$ python --version
diff --git a/user-guide/localizing-your-theme/index.html b/user-guide/localizing-your-theme/index.html
index e642a948..0caad0f8 100644
--- a/user-guide/localizing-your-theme/index.html
+++ b/user-guide/localizing-your-theme/index.html
@@ -206,7 +206,7 @@ enable <code>i18n</code> (internationalization) support by installing <code>mkdo
 <pre><code class="language-bash">pip install mkdocs[i18n]
 </code></pre>
 <h2 id="supported-locales">Supported locales<a class="headerlink" href="#supported-locales" title="Permanent link"></a></h2>
-<p>In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation
+<p>In most cases a locale is designated by the <a href="https://en.wikipedia.org/wiki/ISO_639-1">ISO-639-1</a> (2-letter) abbreviation
 for your language. However, a locale may also include a territory (or region or
 county) code as well. The language and territory must be separated by an
 underscore. For example, some possible locales for English might include <code>en</code>,