from mkdocs.config import base, config_options as c
class _ValidationOptions(base.Config):
@@ -311,7 +312,7 @@ class _ValidationOptions(base.Config):
class MyPluginConfig(base.Config):
definition_file = c.File(exists=True) # required
checksum_file = c.Optional(c.File(exists=True)) # can be None but must exist if specified
- validation = c.SubConfig(_ValidationOptions)
+ validation = c.SubConfig(_ValidationOptions)
From the user's point of view SubConfig is similar to Type(dict), it's just that it also retains full ability for validation: you define all valid keys and what each value should adhere to.
And ListOfItems is similar to Type(list), but again, we define the constraint that each value must adhere to.
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
@@ -1209,6 +1211,7 @@ the theme config:
+
The startup event runs once at the very beginning of an mkdocs invocation.
@@ -1220,9 +1223,9 @@ For initializing per-build variables (and whenever in doubt), use the on_c
-
Parameters:
+
Parameters:
-
+
command
(Literal['build', 'gh-deploy', 'serve'])
–
@@ -1230,7 +1233,7 @@ For initializing per-build variables (and whenever in doubt), use the on_c
the command that MkDocs was invoked with, e.g. "serve" for mkdocs serve.
-
+
dirty
(bool)
–
@@ -1251,6 +1254,7 @@ For initializing per-build variables (and whenever in doubt), use the on_c
+
The shutdown event runs once at the very end of an mkdocs invocation, before exiting.
@@ -1274,6 +1278,7 @@ relies on detecting a graceful shutdown of MkDocs.
+
The serve event is only called when the serve command is used during
@@ -1284,9 +1289,9 @@ to the list of "watched" files for auto-reloading.
-
Parameters:
+
Parameters:
-
+
server
(LiveReloadServer)
–
@@ -1294,7 +1299,7 @@ to the list of "watched" files for auto-reloading.
livereload.Server instance
-
+
config
(MkDocsConfig)
–
@@ -1302,7 +1307,7 @@ to the list of "watched" files for auto-reloading.
global configuration object
-
+
builder
(Callable)
–
@@ -1314,9 +1319,9 @@ to the list of "watched" files for auto-reloading.
-
The build_error event is called after an exception of any kind
@@ -1627,9 +1639,9 @@ events which were scheduled to run after the error will have been skipped. See
-
Parameters:
+
Parameters:
-
+
error
(Exception)
–
@@ -1655,6 +1667,7 @@ called after the env event and before any
@@ -1898,6 +1914,7 @@ page and can be used to alter the Page instance.
+
@@ -1913,9 +1930,9 @@ the contents of a page's source from the filesystem.
-
Parameters:
+
Parameters:
-
+
page
(Page)
–
@@ -1923,7 +1940,7 @@ the contents of a page's source from the filesystem.
mkdocs.structure.pages.Page instance
-
+
config
(MkDocsConfig)
–
@@ -1935,9 +1952,9 @@ the contents of a page's source from the filesystem.
-
Returns:
+
Returns:
-
+
str | None
–
@@ -1958,6 +1975,7 @@ default loading from a file will be performed.
+
The page_markdown event is called after the page's markdown is loaded
@@ -1966,9 +1984,9 @@ data has been stripped off and is available as page.meta at this po
-
Parameters:
+
Parameters:
-
+
markdown
(str)
–
@@ -1976,7 +1994,7 @@ data has been stripped off and is available as page.meta at this po
Markdown source text of page as string
-
+
page
(Page)
–
@@ -1984,7 +2002,7 @@ data has been stripped off and is available as page.meta at this po
mkdocs.structure.pages.Page instance
-
+
config
(MkDocsConfig)
–
@@ -1992,7 +2010,7 @@ data has been stripped off and is available as page.meta at this po
global configuration object
-
+
files
(Files)
–
@@ -2004,9 +2022,9 @@ data has been stripped off and is available as page.meta at this po
-
Returns:
+
Returns:
-
+
str | None
–
@@ -2026,6 +2044,7 @@ data has been stripped off and is available as page.meta at this po
+
The page_content event is called after the Markdown text is rendered to
@@ -2034,9 +2053,9 @@ HTML body of the page.
-
Parameters:
+
Parameters:
-
+
html
(str)
–
@@ -2044,7 +2063,7 @@ HTML body of the page.
HTML rendered from Markdown source as string
-
+
page
(Page)
–
@@ -2052,7 +2071,7 @@ HTML body of the page.
mkdocs.structure.pages.Page instance
-
+
config
(MkDocsConfig)
–
@@ -2060,7 +2079,7 @@ HTML body of the page.
global configuration object
-
+
files
(Files)
–
@@ -2072,9 +2091,9 @@ HTML body of the page.
-
Returns:
+
Returns:
-
+
str | None
–
@@ -2094,6 +2113,7 @@ HTML body of the page.
+
The page_context event is called after the context for a page is created
@@ -2101,9 +2121,9 @@ and can be used to alter the context for that specific page only.
-
Parameters:
+
Parameters:
-
+
context
(TemplateContext)
–
@@ -2111,7 +2131,7 @@ and can be used to alter the context for that specific page only.
dict of template context variables
-
+
page
(Page)
–
@@ -2119,7 +2139,7 @@ and can be used to alter the context for that specific page only.
mkdocs.structure.pages.Page instance
-
+
config
(MkDocsConfig)
–
@@ -2127,7 +2147,7 @@ and can be used to alter the context for that specific page only.
global configuration object
-
+
nav
(Navigation)
–
@@ -2139,9 +2159,9 @@ and can be used to alter the context for that specific page only.
-
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
@@ -2466,7 +2486,6 @@ if log.getEffectiveLevel() <= logging.DEBUG:
-
Navigation objects contained in the nav template variable may be one of
section objects, page objects, and link objects.
@@ -1212,6 +1191,7 @@ theme chooses to do so.
+
The following attributes are available on section objects:
@@ -1219,7 +1199,6 @@ theme chooses to do so.
-
title: str
@@ -1241,7 +1220,6 @@ theme chooses to do so.
-
parent: Section | None = None
@@ -1264,7 +1242,6 @@ theme chooses to do so.
-
children: list[StructureItem]
@@ -1286,7 +1263,6 @@ theme chooses to do so.
-
heading that had to written starting with the exact character # . Now any style of Markdown heading is understood ( #1886 ). Due to the previous simplistic parsing, it was also impossible to use attr_list attributes in that first heading ( #3136 ). Now that is also fixed. Markdown extensions can use paths relative to the current document \uf0c1 This is aimed at extensions such as pymdownx.snippets or markdown_include.include : you can now specify their include paths to be relative to the currently rendered Markdown document, or relative to the docs_dir . Any other extension can of course also make use of the new !relative YAML tag. markdown_extensions: - pymdownx.snippets: base_path: !relative See documentation . Context: #2154 , #3258 {%- endfor %} This old-style example even uses the obsolete top-level extra_javascript list. Please always use config.extra_javascript instead. So, a slightly more modern approach is the following, but it is still obsolete because it ignores the extra attributes of the script: {%- for path in config.extra_javascript %} {%- endfor %} ? EXAMPLE: New style: {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} If you wish to be able to pick up the new customizations while keeping your theme compatible with older versions of MkDocs, use this snippet: ! EXAMPLE: Backwards-compatible style: {%- for script in config.extra_javascript %} {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} {{ script | script_tag }} {%- else %} {# Fallback - examine the file name directly #} {%- endif %} {%- endfor %} 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 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: homepage: Page | None instance-attribute \uf0c1 The page object for the homepage of the site. pages: list[Page] instance-attribute \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 %}
{% for nav_item in nav %} {% if nav_item.children %}
{% 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. Bases: StructureItem All page objects contain the following attributes: title() -> str | None \uf0c1 Returns the title for the current page. Before calling read_source() , this value is empty. It can also be updated by render() . Checks these in order and uses the first that returns a valid title: value provided on init (passed in from config) value of metadata 'title' content of the first H1 in Markdown content convert filename to title content: str | None instance-attribute \uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. Populated after .render() . toc: TableOfContents instance-attribute \uf0c1 An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink . The following example would display the top two levels of the Table of Contents for a page.
meta: MutableMapping[str, Any] instance-attribute \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 %} {{ filename }} {% endfor %} url: str property \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. {{ page.title }} file: File instance-attribute \uf0c1 The documentation File that the page is being rendered from. abs_url: str | None instance-attribute \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/ . canonical_url: str | None instance-attribute \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. edit_url: str | None instance-attribute \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. is_homepage: bool property \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 }} previous_page: Page | None instance-attribute \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. next_page: Page | None instance-attribute \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. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: None = None class-attribute instance-attribute \uf0c1 Pages do not contain children and the attribute is always None . active: bool property writable \uf0c1 When True , indicates that this page is the currently viewed page. Defaults to False . is_section: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for page objects. is_page: bool = True class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always True for page objects. is_link: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for page objects. AnchorLink \uf0c1 A single entry in the table of contents. title: str instance-attribute \uf0c1 The text of the item, as HTML. url: str property \uf0c1 The hash fragment of a URL pointing to the item. level: int instance-attribute \uf0c1 The zero-based level of the item. children: list[AnchorLink] instance-attribute \uf0c1 An iterable of any child items. 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. Bases: StructureItem The following attributes are available on section objects: title: str instance-attribute \uf0c1 The title of the section. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: list[StructureItem] instance-attribute \uf0c1 An iterable of all child navigation objects. Children may include nested sections, pages and links. active: bool property writable \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 . is_section: bool = True class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always True for section objects. is_page: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for section objects. is_link: bool = False class-attribute instance-attribute \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. Bases: StructureItem The following attributes are available on link objects: title: str instance-attribute \uf0c1 The title of the link. This would generally be used as the label of the link. url: str instance-attribute \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. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: None = None class-attribute instance-attribute \uf0c1 Links do not contain children and the attribute is always None . active: bool = False class-attribute instance-attribute \uf0c1 External links cannot be \"active\" and the attribute is always False . is_section: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for link objects. is_page: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for link objects. is_link: bool = True class-attribute instance-attribute \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 %}
{% for link in config.extra.links %}
{{ link }}
{% endfor %}
{% 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. {{ page.title }} tojson \uf0c1 Safely convert a Python object to a value in a JavaScript script. script_tag \uf0c1 New in version 1.5 Convert an item from extra_javascript to a With properly configured settings, the following HTML in a template will add a full search implementation to your theme.
Search Results
Sorry, page not found.
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: {...}, docs: [...], 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 docs 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 %}
...
{% 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: Block 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 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: If the locale was set to fr_CA (Canadian French), then the above template would render as: If you did not want the territory attribute to be included, then reference the language attribute directly: That would render as: 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. Using the Localization/Translation commands \uf0c1 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. The translation commands should be called from the root of your theme's working tree. 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 . 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. 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 @@ -
This is an example theme for MkDocs.
+
{% trans %}This is an example theme for MkDocs.{% endtrans %}
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 , make sure to include it in the \"wheels\", using a MANIFEST.in file or otherwise. 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//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 community wiki page and the MkDocs project catalog . If you want to share a theme you create, you should list it there. 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: {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} {%- for path in config.extra_css %} {%- endfor %} {{ page.content }} {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} 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/#picking-up-css-and-javascript-from-the-config","text":"MkDocs defines the top-level extra_css and extra_javascript configs. These are lists of files. The theme must include the HTML that links the items from these configs, otherwise the configs will be non-functional. You can see the recommended way to render both of them in the base example above . Changed in version 1.5: The items of the config.extra_javascript list used to be simple strings but now became objects that have these fields: path , type , async , defer . In that version, MkDocs also gained the script_tag filter . ? EXAMPLE: Obsolete style: {%- for path in extra_javascript %} {%- endfor %} This old-style example even uses the obsolete top-level extra_javascript list. Please always use config.extra_javascript instead. So, a slightly more modern approach is the following, but it is still obsolete because it ignores the extra attributes of the script: {%- for path in config.extra_javascript %} {%- endfor %} ? EXAMPLE: New style: {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} If you wish to be able to pick up the new customizations while keeping your theme compatible with older versions of MkDocs, use this snippet: ! EXAMPLE: Backwards-compatible style: {%- for script in config.extra_javascript %} {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} {{ script | script_tag }} {%- else %} {# Fallback - examine the file name directly #} {%- endif %} {%- endfor %}","title":"Picking up CSS and JavaScript from the config"},{"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","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/#mkdocs.structure.nav.Navigation.homepage","text":"The page object for the homepage of the site.","title":"homepage"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Navigation.pages","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":"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 %}
{% for nav_item in nav %} {% if nav_item.children %}
{% 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. Bases: StructureItem All page objects contain the following attributes:","title":"page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.title","text":"Returns the title for the current page. Before calling read_source() , this value is empty. It can also be updated by render() . Checks these in order and uses the first that returns a valid title: value provided on init (passed in from config) value of metadata 'title' content of the first H1 in Markdown content convert filename to title","title":"title()"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.content","text":"The rendered Markdown as HTML, this is the contents of the documentation. Populated after .render() .","title":"content"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.toc","text":"An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink . The following example would display the top two levels of the Table of Contents for a page.
","title":"toc"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.meta","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 %} {{ filename }} {% endfor %}","title":"meta"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.url","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. {{ page.title }}","title":"url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.file","text":"The documentation File that the page is being rendered from.","title":"file"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.abs_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":"abs_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.canonical_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":"canonical_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.edit_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":"edit_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_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":"is_homepage"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.previous_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.","title":"previous_page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.next_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.","title":"next_page"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.children","text":"Pages do not contain children and the attribute is always None .","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.active","text":"When True , indicates that this page is the currently viewed page. Defaults to False .","title":"active"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_section","text":"Indicates that the navigation object is a \"section\" object. Always False for page objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_page","text":"Indicates that the navigation object is a \"page\" object. Always True for page objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_link","text":"Indicates that the navigation object is a \"link\" object. Always False for page objects.","title":"is_link"},{"location":"dev-guide/themes/#anchorlink","text":"A single entry in the table of contents.","title":"AnchorLink"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.title","text":"The text of the item, as HTML.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.url","text":"The hash fragment of a URL pointing to the item.","title":"url"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.level","text":"The zero-based level of the item.","title":"level"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.children","text":"An iterable of any child items.","title":"children"},{"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. Bases: StructureItem The following attributes are available on section objects:","title":"Section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.title","text":"The title of the section.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.children","text":"An iterable of all child navigation objects. Children may include nested sections, pages and links.","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.active","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":"active"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_section","text":"Indicates that the navigation object is a \"section\" object. Always True for section objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_page","text":"Indicates that the navigation object is a \"page\" object. Always False for section objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_link","text":"Indicates that the navigation object is a \"link\" object. Always False for section objects.","title":"is_link"},{"location":"dev-guide/themes/#link","text":"A link navigation object contains a link which does not point to an internal MkDocs page. Bases: StructureItem The following attributes are available on link objects:","title":"Link"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.title","text":"The title of the link. This would generally be used as the label of the link.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.url","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":"url"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.children","text":"Links do not contain children and the attribute is always None .","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.active","text":"External links cannot be \"active\" and the attribute is always False .","title":"active"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_section","text":"Indicates that the navigation object is a \"section\" object. Always False for link objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_page","text":"Indicates that the navigation object is a \"page\" object. Always False for link objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_link","text":"Indicates that the navigation object is a \"link\" object. Always True for link objects.","title":"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 %}
{% for link in config.extra.links %}
{{ link }}
{% endfor %}
{% 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. {{ page.title }}","title":"url"},{"location":"dev-guide/themes/#tojson","text":"Safely convert a Python object to a value in a JavaScript script. ","title":"tojson"},{"location":"dev-guide/themes/#script_tag","text":"New in version 1.5 Convert an item from extra_javascript to a With properly configured settings, the following HTML in a template will add a full search implementation to your theme.
Search Results
Sorry, page not found.
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: {...}, docs: [...], 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 docs 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 %}
...
{% 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: Block","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 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: If the locale was set to fr_CA (Canadian French), then the above template would render as: If you did not want the territory attribute to be included, then reference the language attribute directly: That would render as: ","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/#using-the-localizationtranslation-commands","text":"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. The translation commands should be called from the root of your theme's working tree. 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 .","title":"Using the Localization/Translation commands"},{"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. 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 @@ -
This is an example theme for MkDocs.
+
{% trans %}This is an example theme for MkDocs.{% endtrans %}
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 , make sure to include it in the \"wheels\", using a MANIFEST.in file or otherwise. 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//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. You will need to be working from the git working tree on your local machine to make use of the translation commands. 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: Fork and clone the MkDocs repository and then install MkDocs for development for adding and testing translations. 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. Fork and clone the MkDocs repository \uf0c1 In the following steps you'll work with a fork of the MkDocs repository. Follow the instructions for forking and cloning the MkDocs repository . To test the translations you also need to install MkDocs for development from your fork. 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's directory and provide the appropriate language code ( -l ). The language code is almost always just two lowercase letters, such as sv , but in some cases it needs to be further disambiguated. See: Already translated languages for built-in themes ISO 639 Language List Language subtag registry In particular, the way to know that the pt language should be disambiguated as pt_PT and pt_BR is that the Language subtag registry page contains pt- if you search for it. Whereas sv should remain just sv , because that page does not contain sv- . So, if we pick es (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands: pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es The above command will create a file structure as follows: 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 both built-in themes, use the following commands: pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -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 commands will compile the es translation for both built-in themes: pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -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 The page Choosing your theme updates by itself with all available 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. You will need to be working from the git working tree on your local machine to make use of the translation commands. 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: Fork and clone the MkDocs repository and then install MkDocs for development for adding and testing translations. 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/#fork-and-clone-the-mkdocs-repository","text":"In the following steps you'll work with a fork of the MkDocs repository. Follow the instructions for forking and cloning the MkDocs repository . To test the translations you also need to install MkDocs for development from your fork.","title":"Fork and clone the MkDocs repository"},{"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's directory and provide the appropriate language code ( -l ). The language code is almost always just two lowercase letters, such as sv , but in some cases it needs to be further disambiguated. See: Already translated languages for built-in themes ISO 639 Language List Language subtag registry In particular, the way to know that the pt language should be disambiguated as pt_PT and pt_BR is that the Language subtag registry page contains pt- if you search for it. Whereas sv should remain just sv , because that page does not contain sv- . So, if we pick es (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands: pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es The above command will create a file structure as follows: 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 both built-in themes, use the following commands: pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -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 commands will compile the es translation for both built-in themes: pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -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":"The page Choosing your theme updates by itself with all available 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 Localizing Your Theme Configuration Command Line Interface Deploying Your Docs","title":"User Guide"},{"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 Localizing Your Theme Configuration Command Line Interface 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 almost every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: color_mode : Set the default color mode for the theme to one of light , dark , or auto . The auto mode will switch to light or dark based on the system configuration of the user's device. Default: light . user_color_mode_toggle : Enable a toggle menu in the navigation bar which allows users to select their preferred color_mode (light, dark, auto) from within the browser and save their preference for future page loads. The default selection of the toggle menu on first page load is the value set to color_mode . Default: false . nav_style : Adjust the visual style of the top navigation bar. Set to one of primary , dark or light . Default: primary . This option is independent of the color_mode option and must be defined separately. highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides many different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style when in light mode. Default: github . hljs_style_dark : Set this to the name of the desired highlight.js style when in dark mode. Default: github_dark . 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 that 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 that 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 . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese nb : Norwegian Bokm\u00e5l nn : Norwegian Nynorsk pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) 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. 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 anonymize_ip : To enable anonymous IP address for Google Analytics, set this to True . Default: False . 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 fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) See the guide on localizing your theme for more information. logo : To set a logo on your project instead of the plain text site_name , set this variable to be the location of your image. Default: null . Third Party Themes \uf0c1 A list of third party themes can be found at the community wiki page and the ranked catalog . If you have created your own, please add them there. Warning Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.","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 almost every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: color_mode : Set the default color mode for the theme to one of light , dark , or auto . The auto mode will switch to light or dark based on the system configuration of the user's device. Default: light . user_color_mode_toggle : Enable a toggle menu in the navigation bar which allows users to select their preferred color_mode (light, dark, auto) from within the browser and save their preference for future page loads. The default selection of the toggle menu on first page load is the value set to color_mode . Default: false . nav_style : Adjust the visual style of the top navigation bar. Set to one of primary , dark or light . Default: primary . This option is independent of the color_mode option and must be defined separately. highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides many different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style when in light mode. Default: github . hljs_style_dark : Set this to the name of the desired highlight.js style when in dark mode. Default: github_dark . 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 that 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 that 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 . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese nb : Norwegian Bokm\u00e5l nn : Norwegian Nynorsk pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) 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. 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 anonymize_ip : To enable anonymous IP address for Google Analytics, set this to True . Default: False . 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 fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) See the guide on localizing your theme for more information. logo : To set a logo on your project instead of the plain text site_name , set this variable to be the location of your image. Default: null .","title":"readthedocs"},{"location":"user-guide/choosing-your-theme/#third-party-themes","text":"A list of third party themes can be found at the community wiki page and the ranked catalog . If you have created your own, please add them there. Warning Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.","title":"Third Party Themes"},{"location":"user-guide/cli/","text":"Command Line Interface \uf0c1 mkdocs \uf0c1 MkDocs - Project documentation with Markdown. Usage: mkdocs [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default -V , --version boolean Show the version and exit. False -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --color / --no-color boolean Force enable or disable color and wrapping for the output. Default is auto-detect. None --help boolean Show this message and exit. False Subcommands build : Build the MkDocs documentation. get-deps : Show required PyPI packages inferred from plugins in mkdocs.yml. gh-deploy : Deploy your documentation to GitHub Pages. new : Create a new MkDocs project. serve : Run the builtin development server. mkdocs build \uf0c1 Build the MkDocs documentation. Usage: mkdocs build [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs get-deps \uf0c1 Show required PyPI packages inferred from plugins in mkdocs.yml. Usage: mkdocs get-deps [OPTIONS] Options: Name Type Description Default -v , --verbose boolean Enable verbose output False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -p , --projects-file text URL or local path of the registry file that declares all known MkDocs-related projects. None --help boolean Show this message and exit. False mkdocs gh-deploy \uf0c1 Deploy your documentation to GitHub Pages. Usage: mkdocs gh-deploy [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -m , --message text A commit message to use when committing to the GitHub Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions None -b , --remote-branch text The remote branch to commit to for GitHub Pages. This overrides the value specified in config None -r , --remote-name text The remote name to commit to for GitHub Pages. This overrides the value specified in config None --force boolean Force the push to the repository. False --no-history boolean Replace the whole Git history with one new commit. False --ignore-version boolean Ignore check that build is not being deployed with an older version of MkDocs. False --shell boolean Use the shell when invoking Git. False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs new \uf0c1 Create a new MkDocs project. Usage: mkdocs new [OPTIONS] PROJECT_DIRECTORY Options: Name Type Description Default -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs serve \uf0c1 Run the builtin development server. Usage: mkdocs serve [OPTIONS] Options: Name Type Description Default -a , --dev-addr text IP address and port to serve documentation locally (default: localhost:8000) None -o , --open boolean Open the website in a Web browser after the initial build finishes. False --no-livereload boolean Disable the live reloading in the development server. False --dirty text Only re-build files that have changed. False -c , --clean text Build the site without any effects of mkdocs serve - pure mkdocs build , then serve. False --watch-theme boolean Include the theme in list of files to watch for live reloading. Ignored when live reload is not used. False -w , --watch path A directory or file to watch for live reloading. Can be supplied multiple times. [] -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"Command Line Interface"},{"location":"user-guide/cli/#command-line-interface","text":"","title":"Command Line Interface"},{"location":"user-guide/cli/#mkdocs","text":"MkDocs - Project documentation with Markdown. Usage: mkdocs [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default -V , --version boolean Show the version and exit. False -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --color / --no-color boolean Force enable or disable color and wrapping for the output. Default is auto-detect. None --help boolean Show this message and exit. False Subcommands build : Build the MkDocs documentation. get-deps : Show required PyPI packages inferred from plugins in mkdocs.yml. gh-deploy : Deploy your documentation to GitHub Pages. new : Create a new MkDocs project. serve : Run the builtin development server.","title":"mkdocs"},{"location":"user-guide/cli/#mkdocs-build","text":"Build the MkDocs documentation. Usage: mkdocs build [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"build"},{"location":"user-guide/cli/#mkdocs-get-deps","text":"Show required PyPI packages inferred from plugins in mkdocs.yml. Usage: mkdocs get-deps [OPTIONS] Options: Name Type Description Default -v , --verbose boolean Enable verbose output False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -p , --projects-file text URL or local path of the registry file that declares all known MkDocs-related projects. None --help boolean Show this message and exit. False","title":"get-deps"},{"location":"user-guide/cli/#mkdocs-gh-deploy","text":"Deploy your documentation to GitHub Pages. Usage: mkdocs gh-deploy [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -m , --message text A commit message to use when committing to the GitHub Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions None -b , --remote-branch text The remote branch to commit to for GitHub Pages. This overrides the value specified in config None -r , --remote-name text The remote name to commit to for GitHub Pages. This overrides the value specified in config None --force boolean Force the push to the repository. False --no-history boolean Replace the whole Git history with one new commit. False --ignore-version boolean Ignore check that build is not being deployed with an older version of MkDocs. False --shell boolean Use the shell when invoking Git. False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"gh-deploy"},{"location":"user-guide/cli/#mkdocs-new","text":"Create a new MkDocs project. Usage: mkdocs new [OPTIONS] PROJECT_DIRECTORY Options: Name Type Description Default -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"new"},{"location":"user-guide/cli/#mkdocs-serve","text":"Run the builtin development server. Usage: mkdocs serve [OPTIONS] Options: Name Type Description Default -a , --dev-addr text IP address and port to serve documentation locally (default: localhost:8000) None -o , --open boolean Open the website in a Web browser after the initial build finishes. False --no-livereload boolean Disable the live reloading in the development server. False --dirty text Only re-build files that have changed. False -c , --clean text Build the site without any effects of mkdocs serve - pure mkdocs build , then serve. False --watch-theme boolean Include the theme in list of files to watch for live reloading. Ignored when live reload is not used. False -w , --watch path A directory or file to watch for live reloading. Can be supplied multiple times. [] -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"serve"},{"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 . 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/ For example, having this config: repo_url: https://example.com/project/repo edit_uri: blob/main/docs/ means that a page named 'foo/bar.md' will have its edit link lead to: https://example.com/project/repo/blob/main/docs/foo/bar.md edit_uri can actually be just an absolute URL, not necessarily relative to repo_url , so this can achieve the same result: edit_uri: https://example.com/project/repo/blob/main/docs/ For more flexibility, see edit_uri_template below. 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 edit_uri_template \uf0c1 The more flexible variant of edit_uri . These two are equivalent: edit_uri: 'blob/main/docs/' edit_uri_template: 'blob/main/docs/{path}' (they are also mutually exclusive -- don't specify both). Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough. The contents of edit_uri_template are normal Python format strings , with only these fields available: {path} , e.g. foo/bar.md {path_noext} , e.g. foo/bar And the conversion flag !q is available, to percent-encode the field: {path!q} , e.g. foo%2Fbar.md ? NOTE: Suggested useful configurations: GitHub Wiki: (e.g. https://github.com/project/repo/wiki/foo/bar/_edit ) repo_url: 'https://github.com/project/repo/wiki' edit_uri_template: '{path_noext}/_edit' BitBucket editor: (e.g. https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit ) repo_url: 'https://bitbucket.org/project/repo/' edit_uri_template: 'src/master/docs/{path}?mode=edit' GitLab Static Site Editor: (e.g. https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md ) repo_url: 'https://gitlab.com/project/repo' edit_uri_template: '-/sse/master/docs%2F{path!q}' GitLab Web IDE: (e.g. https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md ) edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}' default : 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 in the navigation configuration must be relative to the docs_dir configuration option. 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. exclude_docs \uf0c1 New in version 1.5 Changed in version 1.6: This config no longer applies the \"drafts\" functionality for mkdocs serve . If you have draft documents that you want available in \"serve\" and not \"build\", replace exclude_docs with the new draft_docs config option. This config defines patterns of files (under docs_dir ) to not be picked up into the built site. Example: exclude_docs: | api-config.json # A file with this name anywhere. /requirements.txt # Top-level \"docs/requirements.txt\". *.py # Any file with this extension anywhere. !/foo/example.py # But keep this particular file. This follows the .gitignore pattern format . The following defaults are always implicitly prepended - to exclude dot-files (and directories) as well as the top-level templates directory: exclude_docs: | .* /templates/ So, in order to really start this config fresh, you'd need to specify a negated version of these entries first. Otherwise you could for example opt only certain dot-files back into the site: exclude_docs: | !.assets # Don't exclude '.assets' although all other '.*' are excluded draft_docs \uf0c1 New in version 1.6 This config defines patterns of files (under docs_dir ) to be treated as a draft. Draft files are available during mkdocs serve and include a \"DRAFT\" mark but will not be included in the build. To prevent this effect and make \"serve\" behave the same as \"build\", you can run mkdocs serve --clean . Example: draft_docs: | drafts/ # A \"drafts\" directory anywhere. _unpublished.md # A md file ending in _unpublished.md !/foo_unpublished.md # But keep this particular file. This follows the .gitignore pattern format . not_in_nav \uf0c1 New in version 1.5 New in version 1.6: If the nav config is not specified at all, pages specified in this config will now be excluded from the inferred navigation. If you want to include some docs into the site but intentionally exclude them from the nav, normally MkDocs warns about this. Adding such patterns of files (relative to docs_dir ) into the not_in_nav config will prevent such warnings. Example: nav: - Foo: foo.md - Bar: bar.md not_in_nav: | /private.md As the previous option, this follows the .gitignore pattern format. Note Adding a given file to exclude_docs takes precedence over and implies not_in_nav . validation \uf0c1 New in version 1.5 Configure the strictness of MkDocs' diagnostic messages when validating links to documents. This is a tree of configs, and for each one the value can be one of the three: warn , info , ignore . Which cause a logging message of the corresponding severity to be produced. The warn level is, of course, intended for use with mkdocs build --strict (where it becomes an error), which you can employ in continuous testing. The config validation.links.absolute_links additionally has a special value relative_to_docs , for validation of absolute links . ? EXAMPLE: Defaults of this config as of MkDocs 1.6: validation: nav: omitted_files: info not_found: warn absolute_links: info links: not_found: warn anchors: info absolute_links: info unrecognized_links: info (Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.) The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before. ? EXAMPLE: Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness): validation: absolute_links: ignore unrecognized_links: ignore anchors: ignore ! EXAMPLE: Recommended settings for most sites (maximal strictness): validation: omitted_files: warn absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6 unrecognized_links: warn anchors: warn # New in MkDocs 1.6 Note how in the above examples we omitted the 'nav' and 'links' keys. Here absolute_links: means setting both nav: absolute_links: and links: absolute_links: . Full list of values and examples of log messages that they can hide or make more prominent: validation.nav.omitted_files The following pages exist in the docs directory, but are not included in the \"nav\" configuration: ... validation.nav.not_found A reference to 'foo/bar.md' is included in the 'nav' configuration, which is not found in the documentation files. A reference to 'foo/bar.md' is included in the 'nav' configuration, but this file is excluded from the built site. validation.nav.absolute_links An absolute path to '/foo/bar.html' is included in the 'nav' configuration, which presumably points to an external resource. validation.links.not_found Doc file 'example.md' contains a link '../foo/bar.md', but the target is not found among documentation files. Doc file 'example.md' contains a link to 'foo/bar.md' which is excluded from the built site. validation.links.anchors Doc file 'example.md' contains a link '../foo/bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'. Doc file 'example.md' contains a link '#some-heading', but there is no such anchor on this page. validation.links.absolute_links Doc file 'example.md' contains an absolute link '/foo/bar.html', it was left as is. Did you mean 'foo/bar.md'? validation.links.unrecognized_links Doc file 'example.md' contains an unrecognized relative link '../foo/bar/', it was left as is. Did you mean 'foo/bar.md'? Doc file 'example.md' contains an unrecognized relative link 'mail@example.com', it was left as is. Did you mean 'mailto:mail@example.com'? Validation of absolute links \uf0c1 New in version 1.6 Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected) or, more recently, warned against. If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. If you set the setting validation.links.absolute_links to the new value relative_to_docs , all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably. So, now any document (e.g. \"dir1/foo.md\") can link to the document \"dir2/bar.md\" as [link](/dir2/bar.md) , in addition to the previously only correct way [link](../dir2/bar.md) . You have to enable the setting, though. The default is still to just skip the link. Settings to recognize absolute links and validate them: validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn 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: Block 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 (relative to docs_dir ) to be included by the theme, typically as tags. Example: 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, as # New behavior in MkDocs 1.5: - implicitly_as_module.mjs # # Config keys only supported since MkDocs 1.5: - path: explicitly_as_module.mjs # type: module - path: deferred_plain.js # defer: true - path: scripts/async_module.mjs # type: module async: true So, each item can be either: a plain string, or a mapping that has the required path key and 3 optional keys type (string), async (boolean), defer (boolean). Only the plain string variant detects the .mjs extension and adds type=\"module\" , otherwise type: module must be written out regardless of extension. default : [] (an empty list). Note *.js and *.css files, just like any other type of file, are always copied from docs_dir into the site's deployed copy, regardless if they're linked to the pages via the above configs or not. 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 Live Reloading \uf0c1 watch \uf0c1 Determines additional directories to watch when running mkdocs serve . Configuration is a YAML list. watch: - directory_a - directory_b Allows a custom default to be set without the need to pass it through the -w / --watch option every time the mkdocs serve command is called. Note The paths provided via the configuration file are relative to the configuration file. The paths provided via the -w / --watch CLI parameters are not. 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. This is also available as a command line flag: --strict . 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 Dynamic config values To dynamically configure the extensions, you can get the config values from environment variables or obtain paths of the currently rendered Markdown file or the overall MkDocs site. 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 . More extensions 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 ( Python-Markdown wiki , MkDocs project catalog ). Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list). hooks \uf0c1 New in version 1.4 A list of paths to Python scripts (relative to mkdocs.yml ) that are loaded and used as plugin instances. For example: hooks: - my_hooks.py Then the file my_hooks.py can contain any plugin event handlers (without self ), e.g.: def on_page_markdown(markdown, **kwargs): return markdown.replace('a', 'z') ? EXAMPLE: Advanced example: This produces warnings based on the Markdown content (and warnings are fatal in strict mode): import logging, re import mkdocs.plugins log = logging.getLogger('mkdocs') @mkdocs.plugins.event_priority(-50) def on_page_markdown(markdown, page, **kwargs): path = page.file.src_uri for m in re.finditer(r'\\bhttp://[^) ]+', markdown): log.warning(f\"Documentation file '{path}' contains a non-HTTPS link: {m[0]}\") This does not enable any new abilities compared to plugins , it only simplifies one-off usages, as these don't need to be installed like plugins do. Note that for mkdocs serve the hook module will not be reloaded on each build. You might have seen this feature in the mkdocs-simple-hooks plugin . If using standard method names, it can be directly replaced, e.g.: -plugins: - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'my_hooks:on_page_markdown' +hooks: + - my_hooks.py New in MkDocs 1.6 If a hook file has a file foo.py adjacent to it, it can use the normal Python syntax import foo to access its functions. In older versions of MkDocs, a workaround was necessary to make this work - adding the path to sys.path . plugins \uf0c1 A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. default : ['search'] (the \"search\" plugin included with MkDocs). 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 To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] enabled option \uf0c1 New in MkDocs 1.6 Each plugin has its own options keys. However MkDocs also ensures that each plugin has the enabled boolean option. This can be used to conditionally enable a particular plugin, as in the following example: plugins: - search - code-validator: enabled: !ENV [LINT, false] See: Environment variables Alternate syntax \uf0c1 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 . 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 Special YAML tags \uf0c1 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. Paths relative to the current file or site \uf0c1 New in version 1.5 Some Markdown extensions can benefit from knowing the path of the Markdown file that's currently being processed, or just the root path of the current site. For that, the special tag !relative can be used in most contexts within the config file, though the only known usecases are within markdown_extensions . Examples of the possible values are: - !relative # Relative to the directory of the current Markdown file - !relative $docs_dir # Path of the docs_dir - !relative $config_dir # Path of the directory that contains the main mkdocs.yml - !relative $config_dir/some/child/dir # Some subdirectory of the root config directory (Here, $docs_dir and $config_dir are currently the only special prefixes that are recognized.) Example: markdown_extensions: - pymdownx.snippets: base_path: !relative # Relative to the current Markdown file This allows the pymdownx.snippets extension to include files relative to the current Markdown file, which without this tag it would have no way of knowing. Note Even for the default case, any extension's base path is technically the current working directory although the assumption is that it's the directory of mkdocs.yml . So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom: markdown_extensions: - pymdownx.snippets: base_path: !relative $config_dir # Relative to the root directory with mkdocs.yml 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 file 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. The inheritance can also be used as a quick way to override keys on the command line - by using stdin as the config file. For example: echo '{INHERIT: mkdocs.yml, site_name: \"Renamed site\"}' | mkdocs build -f -","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 . 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/ For example, having this config: repo_url: https://example.com/project/repo edit_uri: blob/main/docs/ means that a page named 'foo/bar.md' will have its edit link lead to: https://example.com/project/repo/blob/main/docs/foo/bar.md edit_uri can actually be just an absolute URL, not necessarily relative to repo_url , so this can achieve the same result: edit_uri: https://example.com/project/repo/blob/main/docs/ For more flexibility, see edit_uri_template below. 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/#edit_uri_template","text":"The more flexible variant of edit_uri . These two are equivalent: edit_uri: 'blob/main/docs/' edit_uri_template: 'blob/main/docs/{path}' (they are also mutually exclusive -- don't specify both). Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough. The contents of edit_uri_template are normal Python format strings , with only these fields available: {path} , e.g. foo/bar.md {path_noext} , e.g. foo/bar And the conversion flag !q is available, to percent-encode the field: {path!q} , e.g. foo%2Fbar.md ? NOTE: Suggested useful configurations: GitHub Wiki: (e.g. https://github.com/project/repo/wiki/foo/bar/_edit ) repo_url: 'https://github.com/project/repo/wiki' edit_uri_template: '{path_noext}/_edit' BitBucket editor: (e.g. https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit ) repo_url: 'https://bitbucket.org/project/repo/' edit_uri_template: 'src/master/docs/{path}?mode=edit' GitLab Static Site Editor: (e.g. https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md ) repo_url: 'https://gitlab.com/project/repo' edit_uri_template: '-/sse/master/docs%2F{path!q}' GitLab Web IDE: (e.g. https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md ) edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}' default : null","title":"edit_uri_template"},{"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 in the navigation configuration must be relative to the docs_dir configuration option. 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/#exclude_docs","text":"New in version 1.5 Changed in version 1.6: This config no longer applies the \"drafts\" functionality for mkdocs serve . If you have draft documents that you want available in \"serve\" and not \"build\", replace exclude_docs with the new draft_docs config option. This config defines patterns of files (under docs_dir ) to not be picked up into the built site. Example: exclude_docs: | api-config.json # A file with this name anywhere. /requirements.txt # Top-level \"docs/requirements.txt\". *.py # Any file with this extension anywhere. !/foo/example.py # But keep this particular file. This follows the .gitignore pattern format . The following defaults are always implicitly prepended - to exclude dot-files (and directories) as well as the top-level templates directory: exclude_docs: | .* /templates/ So, in order to really start this config fresh, you'd need to specify a negated version of these entries first. Otherwise you could for example opt only certain dot-files back into the site: exclude_docs: | !.assets # Don't exclude '.assets' although all other '.*' are excluded","title":"exclude_docs"},{"location":"user-guide/configuration/#draft_docs","text":"New in version 1.6 This config defines patterns of files (under docs_dir ) to be treated as a draft. Draft files are available during mkdocs serve and include a \"DRAFT\" mark but will not be included in the build. To prevent this effect and make \"serve\" behave the same as \"build\", you can run mkdocs serve --clean . Example: draft_docs: | drafts/ # A \"drafts\" directory anywhere. _unpublished.md # A md file ending in _unpublished.md !/foo_unpublished.md # But keep this particular file. This follows the .gitignore pattern format .","title":"draft_docs"},{"location":"user-guide/configuration/#not_in_nav","text":"New in version 1.5 New in version 1.6: If the nav config is not specified at all, pages specified in this config will now be excluded from the inferred navigation. If you want to include some docs into the site but intentionally exclude them from the nav, normally MkDocs warns about this. Adding such patterns of files (relative to docs_dir ) into the not_in_nav config will prevent such warnings. Example: nav: - Foo: foo.md - Bar: bar.md not_in_nav: | /private.md As the previous option, this follows the .gitignore pattern format. Note Adding a given file to exclude_docs takes precedence over and implies not_in_nav .","title":"not_in_nav"},{"location":"user-guide/configuration/#validation","text":"New in version 1.5 Configure the strictness of MkDocs' diagnostic messages when validating links to documents. This is a tree of configs, and for each one the value can be one of the three: warn , info , ignore . Which cause a logging message of the corresponding severity to be produced. The warn level is, of course, intended for use with mkdocs build --strict (where it becomes an error), which you can employ in continuous testing. The config validation.links.absolute_links additionally has a special value relative_to_docs , for validation of absolute links . ? EXAMPLE: Defaults of this config as of MkDocs 1.6: validation: nav: omitted_files: info not_found: warn absolute_links: info links: not_found: warn anchors: info absolute_links: info unrecognized_links: info (Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.) The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before. ? EXAMPLE: Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness): validation: absolute_links: ignore unrecognized_links: ignore anchors: ignore ! EXAMPLE: Recommended settings for most sites (maximal strictness): validation: omitted_files: warn absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6 unrecognized_links: warn anchors: warn # New in MkDocs 1.6 Note how in the above examples we omitted the 'nav' and 'links' keys. Here absolute_links: means setting both nav: absolute_links: and links: absolute_links: . Full list of values and examples of log messages that they can hide or make more prominent: validation.nav.omitted_files The following pages exist in the docs directory, but are not included in the \"nav\" configuration: ... validation.nav.not_found A reference to 'foo/bar.md' is included in the 'nav' configuration, which is not found in the documentation files. A reference to 'foo/bar.md' is included in the 'nav' configuration, but this file is excluded from the built site. validation.nav.absolute_links An absolute path to '/foo/bar.html' is included in the 'nav' configuration, which presumably points to an external resource. validation.links.not_found Doc file 'example.md' contains a link '../foo/bar.md', but the target is not found among documentation files. Doc file 'example.md' contains a link to 'foo/bar.md' which is excluded from the built site. validation.links.anchors Doc file 'example.md' contains a link '../foo/bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'. Doc file 'example.md' contains a link '#some-heading', but there is no such anchor on this page. validation.links.absolute_links Doc file 'example.md' contains an absolute link '/foo/bar.html', it was left as is. Did you mean 'foo/bar.md'? validation.links.unrecognized_links Doc file 'example.md' contains an unrecognized relative link '../foo/bar/', it was left as is. Did you mean 'foo/bar.md'? Doc file 'example.md' contains an unrecognized relative link 'mail@example.com', it was left as is. Did you mean 'mailto:mail@example.com'?","title":"validation"},{"location":"user-guide/configuration/#validation-of-absolute-links","text":"New in version 1.6 Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected) or, more recently, warned against. If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. If you set the setting validation.links.absolute_links to the new value relative_to_docs , all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably. So, now any document (e.g. \"dir1/foo.md\") can link to the document \"dir2/bar.md\" as [link](/dir2/bar.md) , in addition to the previously only correct way [link](../dir2/bar.md) . You have to enable the setting, though. The default is still to just skip the link. Settings to recognize absolute links and validate them: validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn","title":"Validation of absolute links"},{"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: Block","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 (relative to docs_dir ) to be included by the theme, typically as tags. Example: 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, as # New behavior in MkDocs 1.5: - implicitly_as_module.mjs # # Config keys only supported since MkDocs 1.5: - path: explicitly_as_module.mjs # type: module - path: deferred_plain.js # defer: true - path: scripts/async_module.mjs # type: module async: true So, each item can be either: a plain string, or a mapping that has the required path key and 3 optional keys type (string), async (boolean), defer (boolean). Only the plain string variant detects the .mjs extension and adds type=\"module\" , otherwise type: module must be written out regardless of extension. default : [] (an empty list). Note *.js and *.css files, just like any other type of file, are always copied from docs_dir into the site's deployed copy, regardless if they're linked to the pages via the above configs or not.","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/#live-reloading","text":"","title":"Live Reloading"},{"location":"user-guide/configuration/#watch","text":"Determines additional directories to watch when running mkdocs serve . Configuration is a YAML list. watch: - directory_a - directory_b Allows a custom default to be set without the need to pass it through the -w / --watch option every time the mkdocs serve command is called. Note The paths provided via the configuration file are relative to the configuration file. The paths provided via the -w / --watch CLI parameters are not.","title":"watch"},{"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. This is also available as a command line flag: --strict . 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 Dynamic config values To dynamically configure the extensions, you can get the config values from environment variables or obtain paths of the currently rendered Markdown file or the overall MkDocs site. 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 . More extensions 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 ( Python-Markdown wiki , MkDocs project catalog ). 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/#hooks","text":"New in version 1.4 A list of paths to Python scripts (relative to mkdocs.yml ) that are loaded and used as plugin instances. For example: hooks: - my_hooks.py Then the file my_hooks.py can contain any plugin event handlers (without self ), e.g.: def on_page_markdown(markdown, **kwargs): return markdown.replace('a', 'z') ? EXAMPLE: Advanced example: This produces warnings based on the Markdown content (and warnings are fatal in strict mode): import logging, re import mkdocs.plugins log = logging.getLogger('mkdocs') @mkdocs.plugins.event_priority(-50) def on_page_markdown(markdown, page, **kwargs): path = page.file.src_uri for m in re.finditer(r'\\bhttp://[^) ]+', markdown): log.warning(f\"Documentation file '{path}' contains a non-HTTPS link: {m[0]}\") This does not enable any new abilities compared to plugins , it only simplifies one-off usages, as these don't need to be installed like plugins do. Note that for mkdocs serve the hook module will not be reloaded on each build. You might have seen this feature in the mkdocs-simple-hooks plugin . If using standard method names, it can be directly replaced, e.g.: -plugins: - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'my_hooks:on_page_markdown' +hooks: + - my_hooks.py New in MkDocs 1.6 If a hook file has a file foo.py adjacent to it, it can use the normal Python syntax import foo to access its functions. In older versions of MkDocs, a workaround was necessary to make this work - adding the path to sys.path .","title":"hooks"},{"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. default : ['search'] (the \"search\" plugin included with MkDocs). 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 To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: []","title":"plugins"},{"location":"user-guide/configuration/#enabled-option","text":"New in MkDocs 1.6 Each plugin has its own options keys. However MkDocs also ensures that each plugin has the enabled boolean option. This can be used to conditionally enable a particular plugin, as in the following example: plugins: - search - code-validator: enabled: !ENV [LINT, false] See: Environment variables","title":"enabled option"},{"location":"user-guide/configuration/#alternate-syntax","text":"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 .","title":"Alternate syntax"},{"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/#special-yaml-tags","text":"","title":"Special YAML tags"},{"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/#paths-relative-to-the-current-file-or-site","text":"New in version 1.5 Some Markdown extensions can benefit from knowing the path of the Markdown file that's currently being processed, or just the root path of the current site. For that, the special tag !relative can be used in most contexts within the config file, though the only known usecases are within markdown_extensions . Examples of the possible values are: - !relative # Relative to the directory of the current Markdown file - !relative $docs_dir # Path of the docs_dir - !relative $config_dir # Path of the directory that contains the main mkdocs.yml - !relative $config_dir/some/child/dir # Some subdirectory of the root config directory (Here, $docs_dir and $config_dir are currently the only special prefixes that are recognized.) Example: markdown_extensions: - pymdownx.snippets: base_path: !relative # Relative to the current Markdown file This allows the pymdownx.snippets extension to include files relative to the current Markdown file, which without this tag it would have no way of knowing. Note Even for the default case, any extension's base path is technically the current working directory although the assumption is that it's the directory of mkdocs.yml . So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom: markdown_extensions: - pymdownx.snippets: base_path: !relative $config_dir # Relative to the root directory with mkdocs.yml","title":"Paths relative to the current file or site"},{"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 file 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. The inheritance can also be used as a quick way to override keys on the command line - by using stdin as the config file. For example: echo '{INHERIT: mkdocs.yml, site_name: \"Renamed site\"}' | mkdocs build -f -","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 (for example) style.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Then you need to add it to mkdocs.yml : extra_css: - style.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 %} Custom title goes here {% 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 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() }} {% 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 (for example) style.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Then you need to add it to mkdocs.yml : extra_css: - style.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 %} Custom title goes here {% 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 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() }} {% 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. Warning If there are untracked files or uncommitted work in the local repository where mkdocs gh-deploy is run, these will be included in the pages that are deployed. 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. 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. Warning If there are untracked files or uncommitted work in the local repository where mkdocs gh-deploy is run, these will be included in the pages that are deployed.","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.","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. This can be overridden with the exclude_docs config . 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 ¶ ) 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 (
), 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 (
) 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.  *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. ( Setext-style headers are supported only since MkDocs 1.5 .) 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 delimiters 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 delimiters 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 delimiters ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the delimiters to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the delimiters are detected, but the content between the delimiters 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. This can be overridden with the exclude_docs config . 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 ¶ ) 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 (
), 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 (
) 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.  *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. ( Setext-style headers are supported only since MkDocs 1.5 .) 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 delimiters 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 delimiters 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 delimiters ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the delimiters to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the delimiters are detected, but the content between the delimiters 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 (on the MkDocs Themes wiki page as well as the MkDocs Catalog ), 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 INFO - Documentation built in 0.22 seconds INFO - [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [15:50:43] Serving on http://127.0.0.1:8000/ 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 Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name configuration option is the only required option in your configuration file. 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 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 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 INFO - Documentation built in 0.22 seconds INFO - [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [15:50:43] Serving on http://127.0.0.1:8000/ 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 Your browser should immediately reload, and you'll see your new site name take effect. Note The site_name configuration option is the only required option in your configuration file.","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 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 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 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. 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. If you get an error, please include the full error message and traceback. It is particularly helpful if an issue report touches on all of these aspects: What are you trying to achieve? What is your mkdocs.yml configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example. What did you expect to happen when applying this setup? What happened instead and how didn't it match your expectation? Trying out the Development Version \uf0c1 If you want to just install and try out the latest development version of MkDocs (in case it already contains a fix for your issue), 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 git+https://github.com/mkdocs/mkdocs.git Installing for Development \uf0c1 Note that for development you can just use Hatch directly as described below. If you wish to install a local clone of MkDocs anyway, you can run pip install --editable . . It is strongly recommended that you do this within a virtualenv . Installing Hatch \uf0c1 The main tool that is used for development is Hatch . It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner. So first, install it . Ideally in an isolated way with pipx install hatch (after [installing pipx ]), or just pip install hatch as a more well-known way. Running all checks \uf0c1 To run all checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: hatch run all This will encompass all of the checks mentioned below. All checks need to pass. Running tests \uf0c1 To run the test suite for MkDocs, run the following commands: hatch run test:test hatch run integration:test 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. The rest will be verified by GitHub Actions when you submit a pull request. Python code style \uf0c1 Python code within MkDocs' code base is formatted using Black and Isort and lint-checked using Ruff , all of which are configured in pyproject.toml . You can automatically check and format the code according to these tools with the following command: hatch run style:fix The code is also type-checked using mypy - also configured in pyproject.toml , it can be run like this: hatch run types:check Other style checks \uf0c1 There are several other checks, such as spelling and JS style. To run all of them, use this command: hatch run lint:check Documentation of MkDocs itself \uf0c1 After making edits to files under the docs/ dir, you can preview the site locally using the following command: hatch run docs:serve Note that any 'WARNING' should be resolved before submitting a contribution. Documentation files are also checked by markdownlint, so you should run this as well: hatch run lint:check If you add a new plugin to mkdocs.yml, you don't need to add it to any \"requirements\" file, because that is managed automatically. Info If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with .venv being the virtualenv directory): .venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies. .venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies. 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. When working with a pull request branch: Unless otherwise agreed, prefer commit over amend , and merge over rebase . Avoid force-pushes, otherwise review history is much harder to navigate. For the end result, the \"unclean\" history is fine because most pull requests are squash-merged on GitHub. Do not add to release-notes.md , this will be written later. 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. To update the pot file for both built-in themes, run these commands: pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version=\"$(hatch version)\" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version=\"$(hatch version)\" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs 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. 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 .","title":"Contributing"},{"location":"about/contributing/#contributing-to-mkdocs","text":"An introduction to contributing to the MkDocs project. The MkDocs project welcomes 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/#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. If you get an error, please include the full error message and traceback. It is particularly helpful if an issue report touches on all of these aspects: What are you trying to achieve? What is your mkdocs.yml configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example. What did you expect to happen when applying this setup? What happened instead and how didn't it match your expectation?","title":"Reporting an Issue"},{"location":"about/contributing/#trying-out-the-development-version","text":"If you want to just install and try out the latest development version of MkDocs (in case it already contains a fix for your issue), 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 git+https://github.com/mkdocs/mkdocs.git","title":"Trying out the Development Version"},{"location":"about/contributing/#installing-for-development","text":"Note that for development you can just use Hatch directly as described below. If you wish to install a local clone of MkDocs anyway, you can run pip install --editable . . It is strongly recommended that you do this within a virtualenv .","title":"Installing for Development"},{"location":"about/contributing/#installing-hatch","text":"The main tool that is used for development is Hatch . It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner. So first, install it . Ideally in an isolated way with pipx install hatch (after [installing pipx ]), or just pip install hatch as a more well-known way.","title":"Installing Hatch"},{"location":"about/contributing/#running-all-checks","text":"To run all checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: hatch run all This will encompass all of the checks mentioned below. All checks need to pass.","title":"Running all checks"},{"location":"about/contributing/#running-tests","text":"To run the test suite for MkDocs, run the following commands: hatch run test:test hatch run integration:test 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. The rest will be verified by GitHub Actions when you submit a pull request.","title":"Running tests"},{"location":"about/contributing/#python-code-style","text":"Python code within MkDocs' code base is formatted using Black and Isort and lint-checked using Ruff , all of which are configured in pyproject.toml . You can automatically check and format the code according to these tools with the following command: hatch run style:fix The code is also type-checked using mypy - also configured in pyproject.toml , it can be run like this: hatch run types:check","title":"Python code style"},{"location":"about/contributing/#other-style-checks","text":"There are several other checks, such as spelling and JS style. To run all of them, use this command: hatch run lint:check","title":"Other style checks"},{"location":"about/contributing/#documentation-of-mkdocs-itself","text":"After making edits to files under the docs/ dir, you can preview the site locally using the following command: hatch run docs:serve Note that any 'WARNING' should be resolved before submitting a contribution. Documentation files are also checked by markdownlint, so you should run this as well: hatch run lint:check If you add a new plugin to mkdocs.yml, you don't need to add it to any \"requirements\" file, because that is managed automatically. Info If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with .venv being the virtualenv directory): .venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies. .venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies.","title":"Documentation of MkDocs itself"},{"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. When working with a pull request branch: Unless otherwise agreed, prefer commit over amend , and merge over rebase . Avoid force-pushes, otherwise review history is much harder to navigate. For the end result, the \"unclean\" history is fine because most pull requests are squash-merged on GitHub. Do not add to release-notes.md , this will be written later.","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. To update the pot file for both built-in themes, run these commands: pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version=\"$(hatch version)\" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version=\"$(hatch version)\" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs 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/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/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.5.0 from /path/to/mkdocs (Python 3.10) Maintenance team \uf0c1 The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan @oprypin @ultrabug Version 1.6.0 (2024-04-20) \uf0c1 Local preview \uf0c1 mkdocs serve no longer locks up the browser when more than 5 tabs are open. This is achieved by closing the polling connection whenever a tab becomes inactive. Background tabs will no longer auto-reload either - that will instead happen as soon the tab is opened again. Context: #3391 New flag serve --open to open the site in a browser. After the first build is finished, this flag will cause the default OS Web browser to be opened at the home page of the local site. Context: #3500 Drafts \uf0c1 Changed from version 1.5 The exclude_docs config was split up into two separate concepts. The exclude_docs config no longer has any special behavior for mkdocs serve - it now always completely excludes the listed documents from the site. If you wish to use the \"drafts\" functionality like the exclude_docs key used to do in MkDocs 1.5, please switch to the new config key draft_docs . See documentation . Other changes: Reduce warning levels when a \"draft\" page has a link to a non-existent file. Context: #3449 Update to deduction of page titles \uf0c1 MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases. Now tags are always fully sanitized from the title. Though it still remains the case that Page.title is expected to contain HTML entities and is passed directly to the themes. Images (notably, emojis in some extensions) get preserved in the title only through their alt attribute's value. Context: #3564 , #3578 Themes \uf0c1 Built-in themes now also support Polish language ( #3613 ) \"readthedocs\" theme \uf0c1 Fix: \"readthedocs\" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. ( #3464 ) Fix: \"readthedocs\" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. ( #3435 ) \"readthedocs\" theme now also has translation for the word \"theme\" in the footer that mistakenly always remained in English. ( #3613 , #3625 ) \"mkdocs\" theme \uf0c1 The \"mkdocs\" theme got a big update to a newer version of Bootstrap, meaning a slight overhaul of styles. Colors (most notably of admonitions) have much better contrast. The \"mkdocs\" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are not enabled by default and need to be configured explicitly. See color_mode , user_color_mode_toggle in documentation . Possible breaking change jQuery is no longer included into the \"mkdocs\" theme. If you were relying on it in your scripts, you will need to separately add it first (into mkdocs.yml) as an extra script: extra_javascript: - https://code.jquery.com/jquery-3.7.1.min.js Or even better if the script file is copied and included from your docs dir. Context: #3493 , #3649 Configuration \uf0c1 New \" enabled \" setting for all plugins \uf0c1 You may have seen some plugins take up the convention of having a setting enabled: false (or usually controlled through an environment variable) to make the plugin do nothing. Now every plugin has this setting. Plugins can still choose to implement this config themselves and decide how it behaves (and unless they drop older versions of MkDocs, they still should for now), but now there's always a fallback for every plugin. See documentation . Context: #3395 Validation \uf0c1 Validation of hyperlinks between pages \uf0c1 Absolute links \uf0c1 Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against). If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. If you set the setting validation.links.absolute_links to the new value relative_to_docs , all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably. So, now any document (e.g. \"dir1/foo.md\") can link to the document \"dir2/bar.md\" as [link](/dir2/bar.md) , in addition to the previously only correct way [link](../dir2/bar.md) . You have to enable the setting, though. The default is still to just skip any processing of such links. See documentation . Context: #3485 Absolute links within nav \uf0c1 Absolute links within the nav: config were also always skipped. It is now possible to also validate them in the same way with validation.nav.absolute_links . Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash. Anchors \uf0c1 There is a new config setting that is recommended to enable warnings for: validation: anchors: warn Example of a warning that this can produce: WARNING - Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'. Any of the below methods of declaring an anchor will be detected by MkDocs: ## Heading producing an anchor ## Another heading {#custom-anchor-for-heading-using-attr-list} [](){#markdown-anchor-using-attr-list} Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert etree elements as their mode of operation, rather than raw HTML which is undetectable for this purpose. If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to ignore (and they are at INFO level by default anyway). See documentation . Context: #3463 Other changes: When the nav config is not specified at all, the not_in_nav setting (originally added in 1.5.0) gains an additional behavior: documents covered by not_in_nav will not be part of the automatically deduced navigation. Context: #3443 Fix: the !relative YAML tag for markdown_extensions (originally added in 1.5.0) - it was broken in many typical use cases. See documentation . Context: #3466 Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437 MkDocs used to shorten error messages for unexpected errors such as \"file not found\", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: #3445 Upgrades for plugin developers \uf0c1 Plugins can add multiple handlers for the same event type, at multiple priorities \uf0c1 See mkdocs.plugins.CombinedEvent in documentation . Context: #3448 Enabling true generated files and expanding the File API \uf0c1 See documentation . There is a new pair of attributes File.content_string / content_bytes that becomes the official API for obtaining the content of a file and is used by MkDocs itself. This replaces the old approach where one had to manually read the file located at File.abs_src_path , although that is still the primary action that these new attributes do under the hood. The content of a File can be backed by a string and no longer has to be a real existing file at abs_src_path . It is possible to set the attribute File.content_string or File.content_bytes and it will take precedence over abs_src_path . Further, abs_src_path is no longer guaranteed to be present and can be None instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute. There is a new constructor File.generated() that should be used by plugins instead of the File() constructor. It is much more convenient because one doesn't need to manually look up the values such as docs_dir and use_directory_urls . Its signature is one of: f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes) f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str) This way, it is now extremely easy to add a virtual file even from a hook: def on_files(files: Files, config: MkDocsConfig): files.append(File.generated(config, 'fake/path.md', content=\"Hello, world!\")) For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused docs_dir . There is a new attribute File.generated_by that arose by convention - for generated files it should be set to the name of the plugin (the key in the plugins: collection) that produced this file. This attribute is populated automatically when using the File.generated() constructor. It is possible to set the edit_uri attribute of a File , for example from a plugin or hook, to make it different from the default (equal to src_uri ), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the edit_uri to that source file or script accordingly. The File object now stores its original src_dir , dest_dir , use_directory_urls values as attributes. Fields of File are computed on demand but cached. Only the three above attributes are primary ones, and partly also dest_uri . This way, it is possible to, for example, overwrite dest_uri of a File , and abs_dest_path will be calculated based on it. However you need to clear the attribute first using del f.abs_dest_path , because the values are cached. File instances are now hashable (can be used as keys of a dict ). Two files can no longer be considered \"equal\" unless it's the exact same instance of File . Other changes: The internal storage of File objects inside a Files object has been reworked, so any plugins that choose to access Files._files will get a deprecation warning. The order of File objects inside a Files collection is no longer significant when automatically inferring the nav . They get forcibly sorted according to the default alphabetic order. Context: #3451 , #3463 Hooks and debugging \uf0c1 Hook files can now import adjacent *.py files using the import statement. Previously this was possible to achieve only through a sys.path workaround. See the new mention in documentation . Context: #3568 Verbose -v log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444 Deprecations \uf0c1 Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429 The theme config file mkdocs_theme.yml no longer executes YAML tags. Context: #3465 The plugin event on_page_read_source is soft-deprecated because there is always a better alternative to it (see the new File API or just on_page_markdown , depending on the desired interaction). When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case. See documentation . Context: #3503 API deprecations \uf0c1 It is no longer allowed to set File.page to a type other than Page or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381 . Theme._vars is deprecated - use theme['foo'] instead of theme._vars['foo'] utils : modified_time() , get_html_path() , get_url_path() , is_html_file() , is_template_file() are removed. path_to_url() is deprecated. LiveReloadServer.watch() no longer accepts a custom callback. Context: #3429 Misc \uf0c1 The sitemap.xml.gz file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460 Other small improvements; see commit log . Version 1.5.3 (2023-09-18) \uf0c1 Fix mkdocs serve sometimes locking up all browser tabs when navigating quickly ( #3390 ) Add many new supported languages for \"search\" plugin - update lunr-languages to 1.12.0 ( #3334 ) Bugfix (regression in 1.5.0): In \"readthedocs\" theme the styling of \"breadcrumb navigation\" was broken for nested pages ( #3383 ) Built-in themes now also support Chinese (Traditional, Taiwan) language ( #3154 ) Plugins can now set File.page to their own subclass of Page . There is also now a warning if File.page is set to anything other than a strict subclass of Page . ( #3367 , #3381 ) Note that just instantiating a Page sets the file automatically , so care needs to be taken not to create an unneeded Page . Other small improvements; see commit log . Version 1.5.2 (2023-08-02) \uf0c1 Bugfix (regression in 1.5.0): Restore functionality of --no-livereload . ( #3320 ) Bugfix (regression in 1.5.0): The new page title detection would sometimes be unable to drop anchorlinks - fix that. ( #3325 ) Partly bring back pre-1.5 API: extra_javascript items will once again be mostly strings, and only sometimes ExtraScriptValue (when the extra script functionality is used). Plugins should be free to append strings to config.extra_javascript , but when reading the values, they must still make sure to read it as str(value) in case it is an ExtraScriptValue item. For querying the attributes such as .type you need to check isinstance first. Static type checking will guide you in that. ( #3324 ) See commit log . Version 1.5.1 (2023-07-28) \uf0c1 Bugfix (regression in 1.5.0): Make it possible to treat ExtraScriptValue as a path. This lets some plugins still work despite the breaking change. Bugfix (regression in 1.5.0): Prevent errors for special setups that have 3 conflicting files, such as index.html , index.md and README.md ( #3314 ) See commit log . Version 1.5.0 (2023-07-26) \uf0c1 New command mkdocs get-deps \uf0c1 This command guesses the Python dependencies that a MkDocs site requires in order to build. It simply prints the PyPI packages that need to be installed. In the terminal it can be combined directly with an installation command as follows: pip install $(mkdocs get-deps) The idea is that right after running this command, you can directly follow it up with mkdocs build and it will almost always \"just work\", without needing to think which dependencies to install. The way it works is by scanning mkdocs.yml for themes: , plugins: , markdown_extensions: items and doing a reverse lookup based on a large list of known projects (catalog, see below). Of course, you're welcome to use a \"virtualenv\" with such a command. Also note that for environments that require stability (for example CI) directly installing deps in this way is not a very reliable approach as it precludes dependency pinning. The command allows overriding which config file is used (instead of mkdocs.yml in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See mkdocs get-deps --help . Context: #3205 MkDocs has an official catalog of plugins \uf0c1 Check out https://github.com/mkdocs/catalog and add all your general-purpose plugins, themes and extensions there, so that they can be looked up through mkdocs get-deps . This was renamed from \"best-of-mkdocs\" and received significant updates. In addition to pip installation commands, the page now shows the config boilerplate needed to add a plugin. Expanded validation of links \uf0c1 Validated links in Markdown \uf0c1 As you may know, within Markdown, MkDocs really only recognizes relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. MkDocs knows that in the output it should turn those *.md links into *.html as appropriate, and it would also always tell you if such a link doesn't actually lead to an existing file. However, the checks for links were really loose and had many concessions. For example, links that started with / (\"absolute\") and links that ended with / were left as is and no warning was shown, which allowed such very fragile links to sneak into site sources: links that happen to work right now but get no validation and links that confusingly need an extra level of .. with use_directory_urls enabled. Now, in addition to validating relative links, MkDocs will print INFO messages for unrecognized types of links (including absolute links). They look like this: INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'? If you don't want any changes, not even the INFO messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to mkdocs.yml ( not recommended): validation: absolute_links: ignore unrecognized_links: ignore If, on the opposite end, you want these to print WARNING messages and cause mkdocs build --strict to fail, you are recommended to configure these to warn instead. See documentation for actual recommended settings and more details. Context: #3283 Validated links in the nav \uf0c1 Links to documents in the nav configuration now also have configurable validation, though with no changes to the defaults. You are welcomed to turn on validation for files that were forgotten and excluded from the nav. Example: validation: nav: omitted_files: warn absolute_links: warn This can make the following message appear with the WARNING level (as opposed to INFO as the only option previously), thus being caught by mkdocs --strict : INFO - The following pages exist in the docs directory, but are not included in the \"nav\" configuration: ... See documentation . Context: #3283 , #1755 Mark docs as intentionally \"not in nav\" \uf0c1 There is a new config not_in_nav . With it, you can mark particular patterns of files as exempt from the above omitted_files warning type; no messages will be printed for them anymore. (As a corollary, setting this config to * is the same as ignoring omitted_files altogether.) This is useful if you generally like these warnings about files that were forgotten from the nav, but still have some pages that you knowingly excluded from the nav and just want to build and copy them. The not_in_nav config is a set of gitignore-like patterns. See the next section for an explanation of another such config. See documentation . Context: #3224 , #1888 Excluded doc files \uf0c1 There is a new config exclude_docs that tells MkDocs to ignore certain files under docs_dir and not copy them to the built site as part of the build. Historically MkDocs would always ignore file names starting with a dot, and that's all. Now this is all configurable: you can un-ignore these and/or ignore more patterns of files. The exclude_docs config follows the .gitignore pattern format and is specified as a multiline YAML string. For example: exclude_docs: | *.py # Excludes e.g. docs/hooks/foo.py /requirements.txt # Excludes docs/requirements.txt Validation of links (described above) is also affected by exclude_docs . During mkdocs serve the messages explain the interaction, whereas during mkdocs build excluded files are as good as nonexistent. As an additional related change, if you have a need to have both README.md and index.md files in a directory but publish only one of them, you can now use this feature to explicitly ignore one of them and avoid warnings. See documentation . Context: #3224 Drafts \uf0c1 Dropped from version 1.6: The exclude_docs config no longer applies the \"drafts\" functionality for mkdocs serve . This was renamed to draft_docs . The exclude_docs config has another behavior: all excluded Markdown pages will still be previewable in mkdocs serve only, just with a \"DRAFT\" marker on top. Then they will of course be excluded from mkdocs build or gh-deploy . If you don't want mkdocs serve to have any special behaviors and instead want it to perform completely normal builds, use the new flag mkdocs serve --clean . See documentation . Context: #3224 mkdocs serve no longer exits after build errors \uf0c1 If there was an error (from the config or a plugin) during a site re-build, mkdocs serve used to exit after printing a stack trace. Now it will simply freeze the server until the author edits the files to fix the problem, and then will keep reloading. But errors on the first build still cause mkdocs serve to exit, as before. Context: #3255 Page titles will be deduced from any style of heading \uf0c1 MkDocs always had the ability to infer the title of a page (if it's not specified in the nav ) based on the first line of the document, if it had a
heading that had to written starting with the exact character # . Now any style of Markdown heading is understood ( #1886 ). Due to the previous simplistic parsing, it was also impossible to use attr_list attributes in that first heading ( #3136 ). Now that is also fixed. Markdown extensions can use paths relative to the current document \uf0c1 This is aimed at extensions such as pymdownx.snippets or markdown_include.include : you can now specify their include paths to be relative to the currently rendered Markdown document, or relative to the docs_dir . Any other extension can of course also make use of the new !relative YAML tag. markdown_extensions: - pymdownx.snippets: base_path: !relative See documentation . Context: #2154 , #3258 {%- endfor %} This old-style example even uses the obsolete top-level extra_javascript list. Please always use config.extra_javascript instead. So, a slightly more modern approach is the following, but it is still obsolete because it ignores the extra attributes of the script: {%- for path in config.extra_javascript %} {%- endfor %} ? EXAMPLE: New style: {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} If you wish to be able to pick up the new customizations while keeping your theme compatible with older versions of MkDocs, use this snippet: Backwards-compatible style: {%- for script in config.extra_javascript %} {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} {{ script | script_tag }} {%- else %} {# Fallback - examine the file name directly #} {%- endif %} {%- endfor %} 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 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: homepage: Page | None instance-attribute \uf0c1 The page object for the homepage of the site. pages: list[Page] instance-attribute \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 %}
{% for nav_item in nav %} {% if nav_item.children %}
{% 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. Bases: StructureItem All page objects contain the following attributes: title() -> str | None \uf0c1 Returns the title for the current page. Before calling read_source() , this value is empty. It can also be updated by render() . Checks these in order and uses the first that returns a valid title: value provided on init (passed in from config) value of metadata 'title' content of the first H1 in Markdown content convert filename to title content: str | None instance-attribute \uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. Populated after .render() . toc: TableOfContents instance-attribute \uf0c1 An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink . The following example would display the top two levels of the Table of Contents for a page.
meta: MutableMapping[str, Any] instance-attribute \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 %} {{ filename }} {% endfor %} url: str property \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. {{ page.title }} file: File instance-attribute \uf0c1 The documentation File that the page is being rendered from. abs_url: str | None instance-attribute \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/ . canonical_url: str | None instance-attribute \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. edit_url: str | None instance-attribute \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. is_homepage: bool property \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 }} previous_page: Page | None instance-attribute \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. next_page: Page | None instance-attribute \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. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: None = None class-attribute instance-attribute \uf0c1 Pages do not contain children and the attribute is always None . active: bool property writable \uf0c1 When True , indicates that this page is the currently viewed page. Defaults to False . is_section: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for page objects. is_page: bool = True class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always True for page objects. is_link: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"link\" object. Always False for page objects. AnchorLink \uf0c1 A single entry in the table of contents. title: str instance-attribute \uf0c1 The text of the item, as HTML. url: str property \uf0c1 The hash fragment of a URL pointing to the item. level: int instance-attribute \uf0c1 The zero-based level of the item. children: list[AnchorLink] instance-attribute \uf0c1 An iterable of any child items. 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. Bases: StructureItem The following attributes are available on section objects: title: str instance-attribute \uf0c1 The title of the section. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: list[StructureItem] instance-attribute \uf0c1 An iterable of all child navigation objects. Children may include nested sections, pages and links. active: bool property writable \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 . is_section: bool = True class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always True for section objects. is_page: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for section objects. is_link: bool = False class-attribute instance-attribute \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. Bases: StructureItem The following attributes are available on link objects: title: str instance-attribute \uf0c1 The title of the link. This would generally be used as the label of the link. url: str instance-attribute \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. parent: Section | None = None class-attribute instance-attribute \uf0c1 The immediate parent of the item in the site navigation. None if it's at the top level. children: None = None class-attribute instance-attribute \uf0c1 Links do not contain children and the attribute is always None . active: bool = False class-attribute instance-attribute \uf0c1 External links cannot be \"active\" and the attribute is always False . is_section: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"section\" object. Always False for link objects. is_page: bool = False class-attribute instance-attribute \uf0c1 Indicates that the navigation object is a \"page\" object. Always False for link objects. is_link: bool = True class-attribute instance-attribute \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 %}
{% for link in config.extra.links %}
{{ link }}
{% endfor %}
{% 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. {{ page.title }} tojson \uf0c1 Safely convert a Python object to a value in a JavaScript script. script_tag \uf0c1 New in version 1.5 Convert an item from extra_javascript to a With properly configured settings, the following HTML in a template will add a full search implementation to your theme.
Search Results
Sorry, page not found.
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: {...}, docs: [...], 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 docs 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 %}
...
{% 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: Block 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 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: If the locale was set to fr_CA (Canadian French), then the above template would render as: If you did not want the territory attribute to be included, then reference the language attribute directly: That would render as: 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. Using the Localization/Translation commands \uf0c1 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. The translation commands should be called from the root of your theme's working tree. 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 . 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. 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 @@ -
This is an example theme for MkDocs.
+
{% trans %}This is an example theme for MkDocs.{% endtrans %}
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 , make sure to include it in the \"wheels\", using a MANIFEST.in file or otherwise. 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//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 community wiki page and the MkDocs project catalog . If you want to share a theme you create, you should list it there. 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: {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} {%- for path in config.extra_css %} {%- endfor %} {{ page.content }} {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} 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/#picking-up-css-and-javascript-from-the-config","text":"MkDocs defines the top-level extra_css and extra_javascript configs. These are lists of files. The theme must include the HTML that links the items from these configs, otherwise the configs will be non-functional. You can see the recommended way to render both of them in the base example above . Changed in version 1.5: The items of the config.extra_javascript list used to be simple strings but now became objects that have these fields: path , type , async , defer . In that version, MkDocs also gained the script_tag filter . Obsolete style: {%- for path in extra_javascript %} {%- endfor %} This old-style example even uses the obsolete top-level extra_javascript list. Please always use config.extra_javascript instead. So, a slightly more modern approach is the following, but it is still obsolete because it ignores the extra attributes of the script: {%- for path in config.extra_javascript %} {%- endfor %} ? EXAMPLE: New style: {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} If you wish to be able to pick up the new customizations while keeping your theme compatible with older versions of MkDocs, use this snippet: Backwards-compatible style: {%- for script in config.extra_javascript %} {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} {{ script | script_tag }} {%- else %} {# Fallback - examine the file name directly #} {%- endif %} {%- endfor %}","title":"Picking up CSS and JavaScript from the config"},{"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","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/#mkdocs.structure.nav.Navigation.homepage","text":"The page object for the homepage of the site.","title":"homepage"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Navigation.pages","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":"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 %}
{% for nav_item in nav %} {% if nav_item.children %}
{% 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. Bases: StructureItem All page objects contain the following attributes:","title":"page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.title","text":"Returns the title for the current page. Before calling read_source() , this value is empty. It can also be updated by render() . Checks these in order and uses the first that returns a valid title: value provided on init (passed in from config) value of metadata 'title' content of the first H1 in Markdown content convert filename to title","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.content","text":"The rendered Markdown as HTML, this is the contents of the documentation. Populated after .render() .","title":"content"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.toc","text":"An iterable object representing the Table of contents for a page. Each item in the toc is an AnchorLink . The following example would display the top two levels of the Table of Contents for a page.
","title":"toc"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.meta","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 %} {{ filename }} {% endfor %}","title":"meta"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.url","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. {{ page.title }}","title":"url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.file","text":"The documentation File that the page is being rendered from.","title":"file"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.abs_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":"abs_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.canonical_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":"canonical_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.edit_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":"edit_url"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_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":"is_homepage"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.previous_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.","title":"previous_page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.next_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.","title":"next_page"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.children","text":"Pages do not contain children and the attribute is always None .","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.active","text":"When True , indicates that this page is the currently viewed page. Defaults to False .","title":"active"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_section","text":"Indicates that the navigation object is a \"section\" object. Always False for page objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_page","text":"Indicates that the navigation object is a \"page\" object. Always True for page objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.pages.Page.is_link","text":"Indicates that the navigation object is a \"link\" object. Always False for page objects.","title":"is_link"},{"location":"dev-guide/themes/#anchorlink","text":"A single entry in the table of contents.","title":"AnchorLink"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.title","text":"The text of the item, as HTML.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.url","text":"The hash fragment of a URL pointing to the item.","title":"url"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.level","text":"The zero-based level of the item.","title":"level"},{"location":"dev-guide/themes/#mkdocs.structure.toc.AnchorLink.children","text":"An iterable of any child items.","title":"children"},{"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. Bases: StructureItem The following attributes are available on section objects:","title":"Section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.title","text":"The title of the section.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.children","text":"An iterable of all child navigation objects. Children may include nested sections, pages and links.","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.active","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":"active"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_section","text":"Indicates that the navigation object is a \"section\" object. Always True for section objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_page","text":"Indicates that the navigation object is a \"page\" object. Always False for section objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Section.is_link","text":"Indicates that the navigation object is a \"link\" object. Always False for section objects.","title":"is_link"},{"location":"dev-guide/themes/#link","text":"A link navigation object contains a link which does not point to an internal MkDocs page. Bases: StructureItem The following attributes are available on link objects:","title":"Link"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.title","text":"The title of the link. This would generally be used as the label of the link.","title":"title"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.url","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":"url"},{"location":"dev-guide/themes/#mkdocs.structure.StructureItem.parent","text":"The immediate parent of the item in the site navigation. None if it's at the top level.","title":"parent"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.children","text":"Links do not contain children and the attribute is always None .","title":"children"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.active","text":"External links cannot be \"active\" and the attribute is always False .","title":"active"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_section","text":"Indicates that the navigation object is a \"section\" object. Always False for link objects.","title":"is_section"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_page","text":"Indicates that the navigation object is a \"page\" object. Always False for link objects.","title":"is_page"},{"location":"dev-guide/themes/#mkdocs.structure.nav.Link.is_link","text":"Indicates that the navigation object is a \"link\" object. Always True for link objects.","title":"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 %}
{% for link in config.extra.links %}
{{ link }}
{% endfor %}
{% 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. {{ page.title }}","title":"url"},{"location":"dev-guide/themes/#tojson","text":"Safely convert a Python object to a value in a JavaScript script. ","title":"tojson"},{"location":"dev-guide/themes/#script_tag","text":"New in version 1.5 Convert an item from extra_javascript to a With properly configured settings, the following HTML in a template will add a full search implementation to your theme.
Search Results
Sorry, page not found.
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: {...}, docs: [...], 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 docs 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 %}
...
{% 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: Block","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 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: If the locale was set to fr_CA (Canadian French), then the above template would render as: If you did not want the territory attribute to be included, then reference the language attribute directly: That would render as: ","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/#using-the-localizationtranslation-commands","text":"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. The translation commands should be called from the root of your theme's working tree. 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 .","title":"Using the Localization/Translation commands"},{"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. 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 @@ -
This is an example theme for MkDocs.
+
{% trans %}This is an example theme for MkDocs.{% endtrans %}
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 , make sure to include it in the \"wheels\", using a MANIFEST.in file or otherwise. 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//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. You will need to be working from the git working tree on your local machine to make use of the translation commands. 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: Fork and clone the MkDocs repository and then install MkDocs for development for adding and testing translations. 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. Fork and clone the MkDocs repository \uf0c1 In the following steps you'll work with a fork of the MkDocs repository. Follow the instructions for forking and cloning the MkDocs repository . To test the translations you also need to install MkDocs for development from your fork. 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's directory and provide the appropriate language code ( -l ). The language code is almost always just two lowercase letters, such as sv , but in some cases it needs to be further disambiguated. See: Already translated languages for built-in themes ISO 639 Language List Language subtag registry In particular, the way to know that the pt language should be disambiguated as pt_PT and pt_BR is that the Language subtag registry page contains pt- if you search for it. Whereas sv should remain just sv , because that page does not contain sv- . So, if we pick es (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands: pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es The above command will create a file structure as follows: 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 both built-in themes, use the following commands: pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -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 commands will compile the es translation for both built-in themes: pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -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 The page Choosing your theme updates by itself with all available 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. You will need to be working from the git working tree on your local machine to make use of the translation commands. 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: Fork and clone the MkDocs repository and then install MkDocs for development for adding and testing translations. 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/#fork-and-clone-the-mkdocs-repository","text":"In the following steps you'll work with a fork of the MkDocs repository. Follow the instructions for forking and cloning the MkDocs repository . To test the translations you also need to install MkDocs for development from your fork.","title":"Fork and clone the MkDocs repository"},{"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's directory and provide the appropriate language code ( -l ). The language code is almost always just two lowercase letters, such as sv , but in some cases it needs to be further disambiguated. See: Already translated languages for built-in themes ISO 639 Language List Language subtag registry In particular, the way to know that the pt language should be disambiguated as pt_PT and pt_BR is that the Language subtag registry page contains pt- if you search for it. Whereas sv should remain just sv , because that page does not contain sv- . So, if we pick es (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands: pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es The above command will create a file structure as follows: 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 both built-in themes, use the following commands: pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -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 commands will compile the es translation for both built-in themes: pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -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":"The page Choosing your theme updates by itself with all available 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 Localizing Your Theme Configuration Command Line Interface Deploying Your Docs","title":"User Guide"},{"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 Localizing Your Theme Configuration Command Line Interface 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 almost every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: color_mode : Set the default color mode for the theme to one of light , dark , or auto . The auto mode will switch to light or dark based on the system configuration of the user's device. Default: light . user_color_mode_toggle : Enable a toggle menu in the navigation bar which allows users to select their preferred color_mode (light, dark, auto) from within the browser and save their preference for future page loads. The default selection of the toggle menu on first page load is the value set to color_mode . Default: false . nav_style : Adjust the visual style of the top navigation bar. Set to one of primary , dark or light . Default: primary . This option is independent of the color_mode option and must be defined separately. highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides many different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style when in light mode. Default: github . hljs_style_dark : Set this to the name of the desired highlight.js style when in dark mode. Default: github_dark . 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 that 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 that 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 . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese nb : Norwegian Bokm\u00e5l nn : Norwegian Nynorsk pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) 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. 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 anonymize_ip : To enable anonymous IP address for Google Analytics, set this to True . Default: False . 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 fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) See the guide on localizing your theme for more information. logo : To set a logo on your project instead of the plain text site_name , set this variable to be the location of your image. Default: null . Third Party Themes \uf0c1 A list of third party themes can be found at the community wiki page and the ranked catalog . If you have created your own, please add them there. Warning Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.","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 almost every feature of MkDocs. In addition to the default theme configuration options , the mkdocs theme supports the following options: color_mode : Set the default color mode for the theme to one of light , dark , or auto . The auto mode will switch to light or dark based on the system configuration of the user's device. Default: light . user_color_mode_toggle : Enable a toggle menu in the navigation bar which allows users to select their preferred color_mode (light, dark, auto) from within the browser and save their preference for future page loads. The default selection of the toggle menu on first page load is the value set to color_mode . Default: false . nav_style : Adjust the visual style of the top navigation bar. Set to one of primary , dark or light . Default: primary . This option is independent of the color_mode option and must be defined separately. highlightjs : Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True . hljs_style : The highlight.js library provides many different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style when in light mode. Default: github . hljs_style_dark : Set this to the name of the desired highlight.js style when in dark mode. Default: github_dark . 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 that 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 that 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 . locale : The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese nb : Norwegian Bokm\u00e5l nn : Norwegian Nynorsk pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) 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. 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 anonymize_ip : To enable anonymous IP address for Google Analytics, set this to True . Default: False . 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 fall back to the default. The following locales are supported by this theme: en : English (default) de : German es : Spanish fa : Persian fr : French id : Indonesian it : Italian ja : Japanese pl : Polish pt_BR : Portuguese (Brazil) ru : Russian tr : Turkish uk : Ukrainian zh_CN : Chinese (Simplified, China) zh_TW : Chinese (Traditional, Taiwan) See the guide on localizing your theme for more information. logo : To set a logo on your project instead of the plain text site_name , set this variable to be the location of your image. Default: null .","title":"readthedocs"},{"location":"user-guide/choosing-your-theme/#third-party-themes","text":"A list of third party themes can be found at the community wiki page and the ranked catalog . If you have created your own, please add them there. Warning Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.","title":"Third Party Themes"},{"location":"user-guide/cli/","text":"Command Line Interface \uf0c1 mkdocs \uf0c1 MkDocs - Project documentation with Markdown. Usage: mkdocs [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default -V , --version boolean Show the version and exit. False -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --color / --no-color boolean Force enable or disable color and wrapping for the output. Default is auto-detect. None --help boolean Show this message and exit. False Subcommands build : Build the MkDocs documentation. get-deps : Show required PyPI packages inferred from plugins in mkdocs.yml. gh-deploy : Deploy your documentation to GitHub Pages. new : Create a new MkDocs project. serve : Run the builtin development server. mkdocs build \uf0c1 Build the MkDocs documentation. Usage: mkdocs build [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs get-deps \uf0c1 Show required PyPI packages inferred from plugins in mkdocs.yml. Usage: mkdocs get-deps [OPTIONS] Options: Name Type Description Default -v , --verbose boolean Enable verbose output False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -p , --projects-file text URL or local path of the registry file that declares all known MkDocs-related projects. None --help boolean Show this message and exit. False mkdocs gh-deploy \uf0c1 Deploy your documentation to GitHub Pages. Usage: mkdocs gh-deploy [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -m , --message text A commit message to use when committing to the GitHub Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions None -b , --remote-branch text The remote branch to commit to for GitHub Pages. This overrides the value specified in config None -r , --remote-name text The remote name to commit to for GitHub Pages. This overrides the value specified in config None --force boolean Force the push to the repository. False --no-history boolean Replace the whole Git history with one new commit. False --ignore-version boolean Ignore check that build is not being deployed with an older version of MkDocs. False --shell boolean Use the shell when invoking Git. False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs new \uf0c1 Create a new MkDocs project. Usage: mkdocs new [OPTIONS] PROJECT_DIRECTORY Options: Name Type Description Default -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False mkdocs serve \uf0c1 Run the builtin development server. Usage: mkdocs serve [OPTIONS] Options: Name Type Description Default -a , --dev-addr text IP address and port to serve documentation locally (default: localhost:8000) None -o , --open boolean Open the website in a Web browser after the initial build finishes. False --no-livereload boolean Disable the live reloading in the development server. False --dirty text Only re-build files that have changed. False -c , --clean text Build the site without any effects of mkdocs serve - pure mkdocs build , then serve. False --watch-theme boolean Include the theme in list of files to watch for live reloading. Ignored when live reload is not used. False -w , --watch path A directory or file to watch for live reloading. Can be supplied multiple times. [] -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"Command Line Interface"},{"location":"user-guide/cli/#command-line-interface","text":"","title":"Command Line Interface"},{"location":"user-guide/cli/#mkdocs","text":"MkDocs - Project documentation with Markdown. Usage: mkdocs [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default -V , --version boolean Show the version and exit. False -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --color / --no-color boolean Force enable or disable color and wrapping for the output. Default is auto-detect. None --help boolean Show this message and exit. False Subcommands build : Build the MkDocs documentation. get-deps : Show required PyPI packages inferred from plugins in mkdocs.yml. gh-deploy : Deploy your documentation to GitHub Pages. new : Create a new MkDocs project. serve : Run the builtin development server.","title":"mkdocs"},{"location":"user-guide/cli/#mkdocs-build","text":"Build the MkDocs documentation. Usage: mkdocs build [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"build"},{"location":"user-guide/cli/#mkdocs-get-deps","text":"Show required PyPI packages inferred from plugins in mkdocs.yml. Usage: mkdocs get-deps [OPTIONS] Options: Name Type Description Default -v , --verbose boolean Enable verbose output False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -p , --projects-file text URL or local path of the registry file that declares all known MkDocs-related projects. None --help boolean Show this message and exit. False","title":"get-deps"},{"location":"user-guide/cli/#mkdocs-gh-deploy","text":"Deploy your documentation to GitHub Pages. Usage: mkdocs gh-deploy [OPTIONS] Options: Name Type Description Default -c , --clean / --dirty boolean Remove old files from the site_dir before building (the default). True -m , --message text A commit message to use when committing to the GitHub Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions None -b , --remote-branch text The remote branch to commit to for GitHub Pages. This overrides the value specified in config None -r , --remote-name text The remote name to commit to for GitHub Pages. This overrides the value specified in config None --force boolean Force the push to the repository. False --no-history boolean Replace the whole Git history with one new commit. False --ignore-version boolean Ignore check that build is not being deployed with an older version of MkDocs. False --shell boolean Use the shell when invoking Git. False -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -d , --site-dir path The directory to output the result of the documentation build. None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"gh-deploy"},{"location":"user-guide/cli/#mkdocs-new","text":"Create a new MkDocs project. Usage: mkdocs new [OPTIONS] PROJECT_DIRECTORY Options: Name Type Description Default -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"new"},{"location":"user-guide/cli/#mkdocs-serve","text":"Run the builtin development server. Usage: mkdocs serve [OPTIONS] Options: Name Type Description Default -a , --dev-addr text IP address and port to serve documentation locally (default: localhost:8000) None -o , --open boolean Open the website in a Web browser after the initial build finishes. False --no-livereload boolean Disable the live reloading in the development server. False --dirty text Only re-build files that have changed. False -c , --clean text Build the site without any effects of mkdocs serve - pure mkdocs build , then serve. False --watch-theme boolean Include the theme in list of files to watch for live reloading. Ignored when live reload is not used. False -w , --watch path A directory or file to watch for live reloading. Can be supplied multiple times. [] -f , --config-file filename Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin. None -s , --strict / --no-strict boolean Enable strict mode. This will cause MkDocs to abort the build on any warnings. None -t , --theme choice ( mkdocs | readthedocs ) The theme to use when building your documentation. None --use-directory-urls / --no-directory-urls boolean Use directory URLs when building pages (the default). None -q , --quiet boolean Silence warnings False -v , --verbose boolean Enable verbose output False --help boolean Show this message and exit. False","title":"serve"},{"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 . 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/ For example, having this config: repo_url: https://example.com/project/repo edit_uri: blob/main/docs/ means that a page named 'foo/bar.md' will have its edit link lead to: https://example.com/project/repo/blob/main/docs/foo/bar.md edit_uri can actually be just an absolute URL, not necessarily relative to repo_url , so this can achieve the same result: edit_uri: https://example.com/project/repo/blob/main/docs/ For more flexibility, see edit_uri_template below. 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 edit_uri_template \uf0c1 The more flexible variant of edit_uri . These two are equivalent: edit_uri: 'blob/main/docs/' edit_uri_template: 'blob/main/docs/{path}' (they are also mutually exclusive -- don't specify both). Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough. The contents of edit_uri_template are normal Python format strings , with only these fields available: {path} , e.g. foo/bar.md {path_noext} , e.g. foo/bar And the conversion flag !q is available, to percent-encode the field: {path!q} , e.g. foo%2Fbar.md Suggested useful configurations: GitHub Wiki: (e.g. https://github.com/project/repo/wiki/foo/bar/_edit ) repo_url: 'https://github.com/project/repo/wiki' edit_uri_template: '{path_noext}/_edit' BitBucket editor: (e.g. https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit ) repo_url: 'https://bitbucket.org/project/repo/' edit_uri_template: 'src/master/docs/{path}?mode=edit' GitLab Static Site Editor: (e.g. https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md ) repo_url: 'https://gitlab.com/project/repo' edit_uri_template: '-/sse/master/docs%2F{path!q}' GitLab Web IDE: (e.g. https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md ) edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}' default : 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 in the navigation configuration must be relative to the docs_dir configuration option. 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. exclude_docs \uf0c1 New in version 1.5 Changed in version 1.6: This config no longer applies the \"drafts\" functionality for mkdocs serve . If you have draft documents that you want available in \"serve\" and not \"build\", replace exclude_docs with the new draft_docs config option. This config defines patterns of files (under docs_dir ) to not be picked up into the built site. Example: exclude_docs: | api-config.json # A file with this name anywhere. /requirements.txt # Top-level \"docs/requirements.txt\". *.py # Any file with this extension anywhere. !/foo/example.py # But keep this particular file. This follows the .gitignore pattern format . The following defaults are always implicitly prepended - to exclude dot-files (and directories) as well as the top-level templates directory: exclude_docs: | .* /templates/ So, in order to really start this config fresh, you'd need to specify a negated version of these entries first. Otherwise you could for example opt only certain dot-files back into the site: exclude_docs: | !.assets # Don't exclude '.assets' although all other '.*' are excluded draft_docs \uf0c1 New in version 1.6 This config defines patterns of files (under docs_dir ) to be treated as a draft. Draft files are available during mkdocs serve and include a \"DRAFT\" mark but will not be included in the build. To prevent this effect and make \"serve\" behave the same as \"build\", you can run mkdocs serve --clean . Example: draft_docs: | drafts/ # A \"drafts\" directory anywhere. _unpublished.md # A md file ending in _unpublished.md !/foo_unpublished.md # But keep this particular file. This follows the .gitignore pattern format . not_in_nav \uf0c1 New in version 1.5 New in version 1.6: If the nav config is not specified at all, pages specified in this config will now be excluded from the inferred navigation. If you want to include some docs into the site but intentionally exclude them from the nav, normally MkDocs warns about this. Adding such patterns of files (relative to docs_dir ) into the not_in_nav config will prevent such warnings. Example: nav: - Foo: foo.md - Bar: bar.md not_in_nav: | /private.md As the previous option, this follows the .gitignore pattern format. Note Adding a given file to exclude_docs takes precedence over and implies not_in_nav . validation \uf0c1 New in version 1.5 Configure the strictness of MkDocs' diagnostic messages when validating links to documents. This is a tree of configs, and for each one the value can be one of the three: warn , info , ignore . Which cause a logging message of the corresponding severity to be produced. The warn level is, of course, intended for use with mkdocs build --strict (where it becomes an error), which you can employ in continuous testing. The config validation.links.absolute_links additionally has a special value relative_to_docs , for validation of absolute links . Defaults of this config as of MkDocs 1.6: validation: nav: omitted_files: info not_found: warn absolute_links: info links: not_found: warn anchors: info absolute_links: info unrecognized_links: info (Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.) The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before. Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness): validation: absolute_links: ignore unrecognized_links: ignore anchors: ignore Recommended settings for most sites (maximal strictness): validation: omitted_files: warn absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6 unrecognized_links: warn anchors: warn # New in MkDocs 1.6 Note how in the above examples we omitted the 'nav' and 'links' keys. Here absolute_links: means setting both nav: absolute_links: and links: absolute_links: . Full list of values and examples of log messages that they can hide or make more prominent: validation.nav.omitted_files The following pages exist in the docs directory, but are not included in the \"nav\" configuration: ... validation.nav.not_found A reference to 'foo/bar.md' is included in the 'nav' configuration, which is not found in the documentation files. A reference to 'foo/bar.md' is included in the 'nav' configuration, but this file is excluded from the built site. validation.nav.absolute_links An absolute path to '/foo/bar.html' is included in the 'nav' configuration, which presumably points to an external resource. validation.links.not_found Doc file 'example.md' contains a link '../foo/bar.md', but the target is not found among documentation files. Doc file 'example.md' contains a link to 'foo/bar.md' which is excluded from the built site. validation.links.anchors Doc file 'example.md' contains a link '../foo/bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'. Doc file 'example.md' contains a link '#some-heading', but there is no such anchor on this page. validation.links.absolute_links Doc file 'example.md' contains an absolute link '/foo/bar.html', it was left as is. Did you mean 'foo/bar.md'? validation.links.unrecognized_links Doc file 'example.md' contains an unrecognized relative link '../foo/bar/', it was left as is. Did you mean 'foo/bar.md'? Doc file 'example.md' contains an unrecognized relative link 'mail@example.com', it was left as is. Did you mean 'mailto:mail@example.com'? Validation of absolute links \uf0c1 New in version 1.6 Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected) or, more recently, warned against. If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. If you set the setting validation.links.absolute_links to the new value relative_to_docs , all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably. So, now any document (e.g. \"dir1/foo.md\") can link to the document \"dir2/bar.md\" as [link](/dir2/bar.md) , in addition to the previously only correct way [link](../dir2/bar.md) . You have to enable the setting, though. The default is still to just skip the link. Settings to recognize absolute links and validate them: validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn 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: Block 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 (relative to docs_dir ) to be included by the theme, typically as tags. Example: 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, as # New behavior in MkDocs 1.5: - implicitly_as_module.mjs # # Config keys only supported since MkDocs 1.5: - path: explicitly_as_module.mjs # type: module - path: deferred_plain.js # defer: true - path: scripts/async_module.mjs # type: module async: true So, each item can be either: a plain string, or a mapping that has the required path key and 3 optional keys type (string), async (boolean), defer (boolean). Only the plain string variant detects the .mjs extension and adds type=\"module\" , otherwise type: module must be written out regardless of extension. default : [] (an empty list). Note *.js and *.css files, just like any other type of file, are always copied from docs_dir into the site's deployed copy, regardless if they're linked to the pages via the above configs or not. 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 Live Reloading \uf0c1 watch \uf0c1 Determines additional directories to watch when running mkdocs serve . Configuration is a YAML list. watch: - directory_a - directory_b Allows a custom default to be set without the need to pass it through the -w / --watch option every time the mkdocs serve command is called. Note The paths provided via the configuration file are relative to the configuration file. The paths provided via the -w / --watch CLI parameters are not. 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. This is also available as a command line flag: --strict . 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 Dynamic config values To dynamically configure the extensions, you can get the config values from environment variables or obtain paths of the currently rendered Markdown file or the overall MkDocs site. 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 . More extensions 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 ( Python-Markdown wiki , MkDocs project catalog ). Consult the documentation provided by those extensions for installation instructions and available configuration options. default : [] (an empty list). hooks \uf0c1 New in version 1.4 A list of paths to Python scripts (relative to mkdocs.yml ) that are loaded and used as plugin instances. For example: hooks: - my_hooks.py Then the file my_hooks.py can contain any plugin event handlers (without self ), e.g.: def on_page_markdown(markdown, **kwargs): return markdown.replace('a', 'z') Advanced example: This produces warnings based on the Markdown content (and warnings are fatal in strict mode): import logging, re import mkdocs.plugins log = logging.getLogger('mkdocs') @mkdocs.plugins.event_priority(-50) def on_page_markdown(markdown, page, **kwargs): path = page.file.src_uri for m in re.finditer(r'\\bhttp://[^) ]+', markdown): log.warning(f\"Documentation file '{path}' contains a non-HTTPS link: {m[0]}\") This does not enable any new abilities compared to plugins , it only simplifies one-off usages, as these don't need to be installed like plugins do. Note that for mkdocs serve the hook module will not be reloaded on each build. You might have seen this feature in the mkdocs-simple-hooks plugin . If using standard method names, it can be directly replaced, e.g.: -plugins: - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'my_hooks:on_page_markdown' +hooks: + - my_hooks.py New in MkDocs 1.6 If a hook file has a file foo.py adjacent to it, it can use the normal Python syntax import foo to access its functions. In older versions of MkDocs, a workaround was necessary to make this work - adding the path to sys.path . plugins \uf0c1 A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details. default : ['search'] (the \"search\" plugin included with MkDocs). 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 To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: [] enabled option \uf0c1 New in MkDocs 1.6 Each plugin has its own options keys. However MkDocs also ensures that each plugin has the enabled boolean option. This can be used to conditionally enable a particular plugin, as in the following example: plugins: - search - code-validator: enabled: !ENV [LINT, false] See: Environment variables Alternate syntax \uf0c1 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 . 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 Special YAML tags \uf0c1 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. Paths relative to the current file or site \uf0c1 New in version 1.5 Some Markdown extensions can benefit from knowing the path of the Markdown file that's currently being processed, or just the root path of the current site. For that, the special tag !relative can be used in most contexts within the config file, though the only known usecases are within markdown_extensions . Examples of the possible values are: - !relative # Relative to the directory of the current Markdown file - !relative $docs_dir # Path of the docs_dir - !relative $config_dir # Path of the directory that contains the main mkdocs.yml - !relative $config_dir/some/child/dir # Some subdirectory of the root config directory (Here, $docs_dir and $config_dir are currently the only special prefixes that are recognized.) Example: markdown_extensions: - pymdownx.snippets: base_path: !relative # Relative to the current Markdown file This allows the pymdownx.snippets extension to include files relative to the current Markdown file, which without this tag it would have no way of knowing. Note Even for the default case, any extension's base path is technically the current working directory although the assumption is that it's the directory of mkdocs.yml . So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom: markdown_extensions: - pymdownx.snippets: base_path: !relative $config_dir # Relative to the root directory with mkdocs.yml 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 file 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. The inheritance can also be used as a quick way to override keys on the command line - by using stdin as the config file. For example: echo '{INHERIT: mkdocs.yml, site_name: \"Renamed site\"}' | mkdocs build -f -","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 . 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/ For example, having this config: repo_url: https://example.com/project/repo edit_uri: blob/main/docs/ means that a page named 'foo/bar.md' will have its edit link lead to: https://example.com/project/repo/blob/main/docs/foo/bar.md edit_uri can actually be just an absolute URL, not necessarily relative to repo_url , so this can achieve the same result: edit_uri: https://example.com/project/repo/blob/main/docs/ For more flexibility, see edit_uri_template below. 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/#edit_uri_template","text":"The more flexible variant of edit_uri . These two are equivalent: edit_uri: 'blob/main/docs/' edit_uri_template: 'blob/main/docs/{path}' (they are also mutually exclusive -- don't specify both). Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough. The contents of edit_uri_template are normal Python format strings , with only these fields available: {path} , e.g. foo/bar.md {path_noext} , e.g. foo/bar And the conversion flag !q is available, to percent-encode the field: {path!q} , e.g. foo%2Fbar.md Suggested useful configurations: GitHub Wiki: (e.g. https://github.com/project/repo/wiki/foo/bar/_edit ) repo_url: 'https://github.com/project/repo/wiki' edit_uri_template: '{path_noext}/_edit' BitBucket editor: (e.g. https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit ) repo_url: 'https://bitbucket.org/project/repo/' edit_uri_template: 'src/master/docs/{path}?mode=edit' GitLab Static Site Editor: (e.g. https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md ) repo_url: 'https://gitlab.com/project/repo' edit_uri_template: '-/sse/master/docs%2F{path!q}' GitLab Web IDE: (e.g. https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md ) edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}' default : null","title":"edit_uri_template"},{"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 in the navigation configuration must be relative to the docs_dir configuration option. 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/#exclude_docs","text":"New in version 1.5 Changed in version 1.6: This config no longer applies the \"drafts\" functionality for mkdocs serve . If you have draft documents that you want available in \"serve\" and not \"build\", replace exclude_docs with the new draft_docs config option. This config defines patterns of files (under docs_dir ) to not be picked up into the built site. Example: exclude_docs: | api-config.json # A file with this name anywhere. /requirements.txt # Top-level \"docs/requirements.txt\". *.py # Any file with this extension anywhere. !/foo/example.py # But keep this particular file. This follows the .gitignore pattern format . The following defaults are always implicitly prepended - to exclude dot-files (and directories) as well as the top-level templates directory: exclude_docs: | .* /templates/ So, in order to really start this config fresh, you'd need to specify a negated version of these entries first. Otherwise you could for example opt only certain dot-files back into the site: exclude_docs: | !.assets # Don't exclude '.assets' although all other '.*' are excluded","title":"exclude_docs"},{"location":"user-guide/configuration/#draft_docs","text":"New in version 1.6 This config defines patterns of files (under docs_dir ) to be treated as a draft. Draft files are available during mkdocs serve and include a \"DRAFT\" mark but will not be included in the build. To prevent this effect and make \"serve\" behave the same as \"build\", you can run mkdocs serve --clean . Example: draft_docs: | drafts/ # A \"drafts\" directory anywhere. _unpublished.md # A md file ending in _unpublished.md !/foo_unpublished.md # But keep this particular file. This follows the .gitignore pattern format .","title":"draft_docs"},{"location":"user-guide/configuration/#not_in_nav","text":"New in version 1.5 New in version 1.6: If the nav config is not specified at all, pages specified in this config will now be excluded from the inferred navigation. If you want to include some docs into the site but intentionally exclude them from the nav, normally MkDocs warns about this. Adding such patterns of files (relative to docs_dir ) into the not_in_nav config will prevent such warnings. Example: nav: - Foo: foo.md - Bar: bar.md not_in_nav: | /private.md As the previous option, this follows the .gitignore pattern format. Note Adding a given file to exclude_docs takes precedence over and implies not_in_nav .","title":"not_in_nav"},{"location":"user-guide/configuration/#validation","text":"New in version 1.5 Configure the strictness of MkDocs' diagnostic messages when validating links to documents. This is a tree of configs, and for each one the value can be one of the three: warn , info , ignore . Which cause a logging message of the corresponding severity to be produced. The warn level is, of course, intended for use with mkdocs build --strict (where it becomes an error), which you can employ in continuous testing. The config validation.links.absolute_links additionally has a special value relative_to_docs , for validation of absolute links . Defaults of this config as of MkDocs 1.6: validation: nav: omitted_files: info not_found: warn absolute_links: info links: not_found: warn anchors: info absolute_links: info unrecognized_links: info (Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.) The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before. Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness): validation: absolute_links: ignore unrecognized_links: ignore anchors: ignore Recommended settings for most sites (maximal strictness): validation: omitted_files: warn absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6 unrecognized_links: warn anchors: warn # New in MkDocs 1.6 Note how in the above examples we omitted the 'nav' and 'links' keys. Here absolute_links: means setting both nav: absolute_links: and links: absolute_links: . Full list of values and examples of log messages that they can hide or make more prominent: validation.nav.omitted_files The following pages exist in the docs directory, but are not included in the \"nav\" configuration: ... validation.nav.not_found A reference to 'foo/bar.md' is included in the 'nav' configuration, which is not found in the documentation files. A reference to 'foo/bar.md' is included in the 'nav' configuration, but this file is excluded from the built site. validation.nav.absolute_links An absolute path to '/foo/bar.html' is included in the 'nav' configuration, which presumably points to an external resource. validation.links.not_found Doc file 'example.md' contains a link '../foo/bar.md', but the target is not found among documentation files. Doc file 'example.md' contains a link to 'foo/bar.md' which is excluded from the built site. validation.links.anchors Doc file 'example.md' contains a link '../foo/bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'. Doc file 'example.md' contains a link '#some-heading', but there is no such anchor on this page. validation.links.absolute_links Doc file 'example.md' contains an absolute link '/foo/bar.html', it was left as is. Did you mean 'foo/bar.md'? validation.links.unrecognized_links Doc file 'example.md' contains an unrecognized relative link '../foo/bar/', it was left as is. Did you mean 'foo/bar.md'? Doc file 'example.md' contains an unrecognized relative link 'mail@example.com', it was left as is. Did you mean 'mailto:mail@example.com'?","title":"validation"},{"location":"user-guide/configuration/#validation-of-absolute-links","text":"New in version 1.6 Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected) or, more recently, warned against. If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. If you set the setting validation.links.absolute_links to the new value relative_to_docs , all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably. So, now any document (e.g. \"dir1/foo.md\") can link to the document \"dir2/bar.md\" as [link](/dir2/bar.md) , in addition to the previously only correct way [link](../dir2/bar.md) . You have to enable the setting, though. The default is still to just skip the link. Settings to recognize absolute links and validate them: validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn","title":"Validation of absolute links"},{"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: Block","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 (relative to docs_dir ) to be included by the theme, typically as tags. Example: 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, as # New behavior in MkDocs 1.5: - implicitly_as_module.mjs # # Config keys only supported since MkDocs 1.5: - path: explicitly_as_module.mjs # type: module - path: deferred_plain.js # defer: true - path: scripts/async_module.mjs # type: module async: true So, each item can be either: a plain string, or a mapping that has the required path key and 3 optional keys type (string), async (boolean), defer (boolean). Only the plain string variant detects the .mjs extension and adds type=\"module\" , otherwise type: module must be written out regardless of extension. default : [] (an empty list). Note *.js and *.css files, just like any other type of file, are always copied from docs_dir into the site's deployed copy, regardless if they're linked to the pages via the above configs or not.","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/#live-reloading","text":"","title":"Live Reloading"},{"location":"user-guide/configuration/#watch","text":"Determines additional directories to watch when running mkdocs serve . Configuration is a YAML list. watch: - directory_a - directory_b Allows a custom default to be set without the need to pass it through the -w / --watch option every time the mkdocs serve command is called. Note The paths provided via the configuration file are relative to the configuration file. The paths provided via the -w / --watch CLI parameters are not.","title":"watch"},{"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. This is also available as a command line flag: --strict . 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 Dynamic config values To dynamically configure the extensions, you can get the config values from environment variables or obtain paths of the currently rendered Markdown file or the overall MkDocs site. 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 . More extensions 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 ( Python-Markdown wiki , MkDocs project catalog ). 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/#hooks","text":"New in version 1.4 A list of paths to Python scripts (relative to mkdocs.yml ) that are loaded and used as plugin instances. For example: hooks: - my_hooks.py Then the file my_hooks.py can contain any plugin event handlers (without self ), e.g.: def on_page_markdown(markdown, **kwargs): return markdown.replace('a', 'z') Advanced example: This produces warnings based on the Markdown content (and warnings are fatal in strict mode): import logging, re import mkdocs.plugins log = logging.getLogger('mkdocs') @mkdocs.plugins.event_priority(-50) def on_page_markdown(markdown, page, **kwargs): path = page.file.src_uri for m in re.finditer(r'\\bhttp://[^) ]+', markdown): log.warning(f\"Documentation file '{path}' contains a non-HTTPS link: {m[0]}\") This does not enable any new abilities compared to plugins , it only simplifies one-off usages, as these don't need to be installed like plugins do. Note that for mkdocs serve the hook module will not be reloaded on each build. You might have seen this feature in the mkdocs-simple-hooks plugin . If using standard method names, it can be directly replaced, e.g.: -plugins: - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'my_hooks:on_page_markdown' +hooks: + - my_hooks.py New in MkDocs 1.6 If a hook file has a file foo.py adjacent to it, it can use the normal Python syntax import foo to access its functions. In older versions of MkDocs, a workaround was necessary to make this work - adding the path to sys.path .","title":"hooks"},{"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. default : ['search'] (the \"search\" plugin included with MkDocs). 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 To completely disable all plugins, including any defaults, set the plugins setting to an empty list: plugins: []","title":"plugins"},{"location":"user-guide/configuration/#enabled-option","text":"New in MkDocs 1.6 Each plugin has its own options keys. However MkDocs also ensures that each plugin has the enabled boolean option. This can be used to conditionally enable a particular plugin, as in the following example: plugins: - search - code-validator: enabled: !ENV [LINT, false] See: Environment variables","title":"enabled option"},{"location":"user-guide/configuration/#alternate-syntax","text":"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 .","title":"Alternate syntax"},{"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/#special-yaml-tags","text":"","title":"Special YAML tags"},{"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/#paths-relative-to-the-current-file-or-site","text":"New in version 1.5 Some Markdown extensions can benefit from knowing the path of the Markdown file that's currently being processed, or just the root path of the current site. For that, the special tag !relative can be used in most contexts within the config file, though the only known usecases are within markdown_extensions . Examples of the possible values are: - !relative # Relative to the directory of the current Markdown file - !relative $docs_dir # Path of the docs_dir - !relative $config_dir # Path of the directory that contains the main mkdocs.yml - !relative $config_dir/some/child/dir # Some subdirectory of the root config directory (Here, $docs_dir and $config_dir are currently the only special prefixes that are recognized.) Example: markdown_extensions: - pymdownx.snippets: base_path: !relative # Relative to the current Markdown file This allows the pymdownx.snippets extension to include files relative to the current Markdown file, which without this tag it would have no way of knowing. Note Even for the default case, any extension's base path is technically the current working directory although the assumption is that it's the directory of mkdocs.yml . So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom: markdown_extensions: - pymdownx.snippets: base_path: !relative $config_dir # Relative to the root directory with mkdocs.yml","title":"Paths relative to the current file or site"},{"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 file 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. The inheritance can also be used as a quick way to override keys on the command line - by using stdin as the config file. For example: echo '{INHERIT: mkdocs.yml, site_name: \"Renamed site\"}' | mkdocs build -f -","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 (for example) style.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Then you need to add it to mkdocs.yml : extra_css: - style.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 %} Custom title goes here {% 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 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() }} {% 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 (for example) style.css and place it next to the documentation Markdown. In that file add the following CSS. h1 { color: red; } Then you need to add it to mkdocs.yml : extra_css: - style.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 %} Custom title goes here {% 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 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() }} {% 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. Warning If there are untracked files or uncommitted work in the local repository where mkdocs gh-deploy is run, these will be included in the pages that are deployed. 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. 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. Warning If there are untracked files or uncommitted work in the local repository where mkdocs gh-deploy is run, these will be included in the pages that are deployed.","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.","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. This can be overridden with the exclude_docs config . 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 ¶ ) 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 (
), 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 (
) 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.  *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. ( Setext-style headers are supported only since MkDocs 1.5 .) 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 delimiters 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 delimiters 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 delimiters ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the delimiters to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the delimiters are detected, but the content between the delimiters 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. This can be overridden with the exclude_docs config . 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 ¶ ) 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 (
), 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 (
) 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.  *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. ( Setext-style headers are supported only since MkDocs 1.5 .) 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 delimiters 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 delimiters 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 delimiters ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the delimiters to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the delimiters are detected, but the content between the delimiters 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 50409e60..4f283360 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,97 +2,97 @@
https://www.mkdocs.org/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/getting-started/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/about/contributing/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/about/license/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/about/release-notes/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/dev-guide/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/dev-guide/api/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/dev-guide/plugins/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/dev-guide/themes/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/dev-guide/translations/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/choosing-your-theme/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/cli/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/configuration/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/customizing-your-theme/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/deploying-your-docs/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/installation/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/localizing-your-theme/
- 2024-04-20
+ 2024-04-21dailyhttps://www.mkdocs.org/user-guide/writing-your-docs/
- 2024-04-20
+ 2024-04-21daily
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 579f6c25..6bed26f2 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/user-guide/configuration/index.html b/user-guide/configuration/index.html
index 78b96753..10b43944 100644
--- a/user-guide/configuration/index.html
+++ b/user-guide/configuration/index.html
@@ -358,8 +358,8 @@ edit_uri_template: 'blob/main/docs/{path}'
Set the site description. This will add a meta tag to the generated HTML header.
@@ -510,8 +510,8 @@ not_in_nav: |
Configure the strictness of MkDocs' diagnostic messages when validating links to documents.
This is a tree of configs, and for each one the value can be one of the three: warn, info, ignore. Which cause a logging message of the corresponding severity to be produced. The warn level is, of course, intended for use with mkdocs build --strict (where it becomes an error), which you can employ in continuous testing.
The config validation.links.absolute_links additionally has a special value relative_to_docs, for validation of absolute links.
-
-
? EXAMPLE: Defaults of this config as of MkDocs 1.6:
+
+Defaults of this config as of MkDocs 1.6:
validation:
nav:
omitted_files: info
@@ -523,24 +523,24 @@ not_in_nav: |
absolute_links: info
unrecognized_links: info
(Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.)
-
+
The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before.
-
-
? EXAMPLE: Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness):
+
+Configure MkDocs 1.6 to behave like MkDocs 1.4 and below (reduce strictness):
! EXAMPLE: Recommended settings for most sites (maximal strictness):
+
+Recommended settings for most sites (maximal strictness):
validation:
omitted_files: warn
absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6
unrecognized_links: warn
anchors: warn # New in MkDocs 1.6
-
+
Note how in the above examples we omitted the 'nav' and 'links' keys. Here absolute_links: means setting both nav: absolute_links: and links: absolute_links:.
Full list of values and examples of log messages that they can hide or make more prominent:
@@ -896,8 +896,8 @@ and available configuration options.
Then the file my_hooks.py can contain any plugin event handlers (without self), e.g.: