Racingfox687

A guide to creating and distributing custom themes.

Note

Nowadays, pre-made themes and templates are the norm. Since WordPress makes it so easy to change and modify your theme, more and more users are growing curious about which theme a particular website is using. Generally speaking, the best way to determine this is to perform a code inspection—but not everyone has the time and/or skills to do this. As a result, many browser extensions. I am trying to install DarkWiiv34.2e.csm that I found on this site, everytime I click it then click load it gives me 'ERROR unable to install theme' I read online that I need a compatible mym for my console, I am a noob at this still so what is a mym and how do I use it? Sea and Seifuku Theme. Click for more details. Metalshiflet Orange Anime Theme. Click for more details. YSMM1 Pokemon Winter Theme. Click for more details. Homeless Fortnite-Raven and Ravage (REDO) Scan.

If you are looking for third party themes, they are listed in the MkDocscommunity wiki. Ifyou want to share a theme you create, you should list it on the Wiki.

When creating a new theme, you can either follow the steps in this guide tocreate one from scratch or you can download the mkdocs-basic-theme as abasic, yet complete, theme with all the boilerplate required. You can findthis base theme on GitHub.It contains detailed comments in the code to describe the different featuresand their usage.

Creating a custom theme

The bare minimum required for a custom theme is a main.htmlJinja2 templatefile 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 thedirectory containing main.html. The path should be relative to theconfiguration file. For example, given this example project layout:

... you would include the following settings in mkdocs.yml to use the custom themedirectory:

Note

Generally, when building your own custom theme, the theme.nameconfiguration setting would be set to null. However, if thetheme.custom_dir configuration value is used in combination with anexisting theme, the theme.custom_dir can be used to replace only specificparts of a built-in theme. For example, with the above layout and if you setname: 'mkdocs' then the main.html file in the theme.custom_dir wouldreplace the file of the same name in the mkdocs theme but otherwise themkdocs theme would remain unchanged. This is useful if you want to makesmall adjustments to an existing theme.

For more specific information, see styling your docs.

Warning

A theme's configuration defined in a mkdocs_theme.yml file is not loadedfrom theme.custom_dir. When an entire theme exists in theme.custom_dirand theme.name is set to null, then the entire theme configuration mustbe defined in the theme configuration option in the mkdocs.yml file.

However, when a theme is packaged up for distribution, and loaded usingthe theme.name configuration option, then a mkdocs_theme.yml fileis required for the theme.

Basic theme

The simplest main.html file is the following:

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 thistheme as with a normal HTML file. Navbars and tables of contents can also begenerated and included automatically, through the nav and toc objects,respectively. If you wish to write your own theme, it is recommended to startwith one of the built-in themes and modify it accordingly.

Note

As MkDocs uses Jinja as its template engine, you have access to all thepower of Jinja, including template inheritance. You may notice that thethemes included with MkDocs make extensive use of template inheritance andblocks, allowing users to easily override small bits and pieces of thetemplates from the theme custom_dir. Therefore, the built-in themes areimplemented in a base.html file, which main.html extends. Although notrequired, third party template authors are encouraged to follow a similarpattern and may want to define the same blocks as are used in the built-inthemes for consistency.

Theme Files

There are various files which a theme treats special in some way. Any otherfiles are simply copied from the theme directory to the same path in thesite_dir when the site it built. For example image and CSS files have nospecial significance and are copied as-is. Note, however, that if the userprovides a file with the same path in their docs_dir, then the user's filewill replace the theme file.

Template Files

Any files with the .html extension are considered to be template files and arenot copied from the theme directory or any subdirectories. Also, any fileslisted in static_templates are treated as templates regardless of their fileextension.

Theme Meta Files

The various files required for packaging a theme are also ignored. Specifically,the mkdocs_theme.yml configuration file and any Python files.

Dot Files

Theme authors can explicitly force MkDocs to ignore files by starting a file ordirectory name with a dot. Any of the following files would be ignored:

Documentation Files

All documentation files are ignored. Specifically, any Markdown files (using anyof the file extensions supported by MKDocs). Additionally, any README fileswhich may exist in the theme directories are ignored.

Template Variables

Each template in a theme is built with a template context. These are thevariables that are available to themes. The context varies depending on thetemplate that is being built. At the moment templates are either built withthe global context or with a page specific context. The global context is usedfor HTML pages that don't represent an individual Markdown document, forexample a 404.html page or search.html.

Global Context

The following variables are available globally on any template.

config

The config variable is an instance of MkDocs' config object generated from themkdocs.yml config file. While you can use any config option, some commonlyused options include:

nav

The nav variable is used to create the navigation for the documentation. Thenav object is an iterable of navigation objects asdefined by the nav configuration setting.

In addition to the iterable of navigation objects, thenav object contains the following attributes:

nav.homepage

The page object for the homepage of the site.

nav.pages

A flat list of all page objects contained in the navigation. This listis not necessarily a complete list of all site pages as it does not containpages which are not included in the navigation. This list does match the listand order of pages used for all 'next page' and 'previous page' links. For alist of all pages, use the pages template variable.

Nav Example

Following is a basic usage example which outputs the first and second levelnavigation as a nested list.

base_url

The base_url provides a relative path to the root of the MkDocs project. Whilethis can be used directly by prepending it to a local relative URL, it is bestto use the url template filter, which is smarter about how it appliesbase_url.

mkdocs_version

Contains the current MkDocs version.

build_date_utc

A Python datetime object that represents the date and time the documentationwas built in UTC. This is useful for showing how recently the documentationwas updated.

pages

A list of page objects including all pages in the project. The listis a flat list with all pages sorted alphanumerically by directory and filename. Note that index pages sort to the top within a directory. This list cancontain pages not included in the global navigation and may not matchthe order of pages within that navigation.

page

In templates which are not rendered from a Markdown source file, the pagevariable is None. In templates which are rendered from a Markdown source file,the page variable contains a page object. The same page objects are usedas pagenavigation objects in the globalnavigation and in the pages template variable.

All page objects contain the following attributes:

page.title

Contains the Title for the current page.

page.content

The rendered Markdown as HTML, this is the contents of the documentation.

page.toc

An iterable object representing the Table of contents for a page. Each item inthe toc is an AnchorLink which contains the following attributes:

• AnchorLink.title: The text of the item.
• AnchorLink.url: The hash fragment of a URL pointing to the item.
• AnchorLink.level: The zero-based level of the item.
• AnchorLink.children: An iterable of any child items.

The following example would display the top two levels of the Table of Contentsfor a page.

page.meta

A mapping of the metadata included at the top of the markdown page. In thisexample we define a source property above the page title.

A template can access this metadata for the page with the meta.sourcevariable. This could then be used to link to source files related to thedocumentation page.

page.url

The URL of the page relative to the MkDocs site_dir. It is expected that thisbe used with the url filter to ensure the URL is relative to the currentpage.

page.abs_url

The absolute URL of the page from the server root as determined by the valueassigned to the site_url configuration setting. The value includes anysubdirectory included in the site_url, but not the domain. base_url shouldnot be used with this variable.

For example, if site_url: https://example.com/, then the value ofpage.abs_url for the page foo.md would be /foo/. However, ifsite_url: https://example.com/bar/, then the value of page.abs_url for thepage foo.md would be /bar/foo/.

page.canonical_url

The full, canonical URL to the current page as determined by the value assignedto the site_url configuration setting. The value includes the domain and anysubdirectory included in the site_url. base_url should not be used with thisvariable.

page.edit_url

The full URL to the source page in the source repository. Typically used toprovide a link to edit the source page. base_url should not be used with thisvariable.

page.is_homepage

Evaluates to True for the homepage of the site and False for all otherpages. This can be used in conjunction with other attributes of the pageobject to alter the behavior. For example, to display a different titleon the homepage:

page.previous_page

The page object for the previous page or None. The value will be None if thecurrent page is the first item in the site navigation or if the current page isnot included in the navigation at all. When the value is a page object, theusage is the same as for page.

page.next_page

The page object for the next page or None. The value will be None if thecurrent page is the last item in the site navigation or if the current page isnot included in the navigation at all. When the value is a page object, theusage is the same as for page.

page.parent

The immediate parent of the page in the site navigation. None if thepage is at the top level.

page.children

Pages do not contain children and the attribute is always None.

page.active

When True, indicates that this page is the currently viewed page. Defaultsto False.

page.is_section

Indicates that the navigation object is a 'section' object. Always False forpage objects.

page.is_page

Indicates that the navigation object is a 'page' object. Always True forpage objects.

page.is_link

Indicates that the navigation object is a 'link' object. Always False forpage objects.

Navigation Objects

Navigation objects contained in the nav template variable may be one ofsection objects, page objects, and link objects.While section objects may contain nested navigation objects, pages and links donot.

Page objects are the full page object as used for the current page withall of the same attributes available. Section and Link objects contain a subsetof those attributes as defined below:

Section

A section navigation object defines a named section in the navigation andcontains a list of child navigation objects. Note that sections do not containURLs and are not links of any kind. However, by default, MkDocs sorts indexpages to the top and the first child might be used as the URL for a section if atheme choses to do so.

The following attributes are available on section objects:

section.title

The title of the section.

section.parent

The immediate parent of the section or None if the section is at the toplevel.

section.children

An iterable of all child navigation objects. Children may include nestedsections, pages and links.

section.active

When True, indicates that a child page of this section is the current page andcan be used to highlight the section as the currently viewed section. Defaultsto False.

section.is_section

Indicates that the navigation object is a 'section' object. Always True forsection objects.

section.is_page

Indicates that the navigation object is a 'page' object. Always False forsection objects.

section.is_link

Indicates that the navigation object is a 'link' object. Always False forsection objects.

Link

A link navigation object contains a link which does not point to an internalMkDocs page. The following attributes are available on link objects:

link.title

The title of the link. This would generally be used as the label of the link.

link.url

The URL that the link points to. The URL should always be an absolute URLs andshould not need to have base_url prepened.

link.parent

The immediate parent of the link. None if the link is at the top level.

link.children

Links do not contain children and the attribute is always None.

link.active

External links cannot be 'active' and the attribute is always False.

link.is_section

Indicates that the navigation object is a 'section' object. Always False forlink objects.

link.is_page

Indicates that the navigation object is a 'page' object. Always False forlink objects.

link.is_link

Indicates that the navigation object is a 'link' object. Always True forlink objects.

Extra Context

Additional variables can be passed to the template with theextra configuration option. This is aset 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 pagesand a list of links related to the project. This can be achieved with thefollowing extra configuration:

And then displayed with this HTML in the custom theme.

Mymenuify Gui

Template Filters

In addition to Jinja's default filters, the following custom filters areavailable to use in MkDocs templates:

url

Normalizes a URL. Absolute URLs are passed through unaltered. If the URL isrelative and the template context includes a page object, then the URL isreturned relative to the page object. Otherwise, the URL is returned withbase_url prepended.

tojson

Safety convert a Python object to a value in a JavaScript script.

Search and themes

As of MkDocs version 0.17 client side search support has been added to MkDocsvia the search plugin. A theme needs to provide a few things for the plugin towork with the theme.

While the search plugin is activated by default, users can disable the pluginand themes should account for this. It is recommended that theme templates wrapsearch specific markup with a check for the plugin:

At its most basic functionality, the search plugin will simply provide an indexfile which is no more than a JSON file containing the content of all pages.The theme would need to implement its own search functionality client-side.However, with a few settings and the necessary templates, the plugin can providea complete functioning client-side search tool based on lunr.js.

The following HTML needs to be added to the theme so that the providedJavaScript is able to properly load the search scripts and make relative linksto the search results from the current page.

With properly configured settings, the following HTML in a template will add afull search implementation to your theme.

The JavaScript in the plugin works by looking for the specific ID's used in theabove HTML. The form input for the user to type the search query must beidentified with id='mkdocs-search-query' and the div where the results will beplaced must be identified with id='mkdocs-search-results'.

The plugin supports the following options being set in the theme'sconfiguration file, mkdocs_theme.yml:

include_search_page

Determines whether the search plugin expects the theme to provide a dedicatedsearch page via a template located at search/search.html.

When include_search_page is set to true, the search template will be builtand available at search/search.html. This method is used by the readthedocstheme.

When include_search_page is set to false or not defined, it is expected thatthe theme provide some other mechanisms for displaying search results. Forexample, the mkdocs theme displays results on any page via a modal.

search_index_only

Determines whether the search plugin should only generate a search index or acomplete search solution.

When search_index_only is set to false, then the search plugin modifies theJinja environment by adding its own templates directory (with a lowerprecedence than the theme) and adds its scripts to the extra_javascript configsetting.

When search_index_only is set to true or not defined, the search pluginmakes no modifications to the Jinja environment. A complete solution using theprovided index file is the responsibility of the theme.

Mymenuify Themes 4.3u

The search index is written to a JSON file at search/search_index.json in thesite_dir. The JSON object contained within the file may contain up to threeobjects.

If present, the config object contains the key/value pairs of config optionsdefined for the plugin in the user's mkdocs.yml config file underplugings.search. The config object was new in MkDocs version 1.0.

The data object contains a list of document objects. Each document object ismade up of a location (URL), a title, and text which can be used to createa search index and/or display search results.

If present, the index object contains a pre-built index which offersperformance improvements for larger sites. Note that the pre-built index is onlycreated if the user explicitly enables the prebuild_index config option.Themes should expect the index to not be present, but can choose to use theindex when it is available. The index object was new in MkDocs version 1.0.

Packaging Themes

MkDocs makes use of Python packaging to distribute themes. This comes with afew requirements.

To see an example of a package containing one theme, see the MkDocs Bootstraptheme and to see a package that contains many themes, see the MkDocsBootswatch theme.

Note

Mymenuify Themes 4.3u Download

It is not strictly necessary to package a theme, as the entire themecan 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 themefor others to use, packaging the theme has some advantages. By packagingyour theme, your users can more easily install it, they can rely on a defaultconfiguration being defined, and they can then take advantage of thecustom_dir to make tweaks to your theme to better suit their needs.

Package Layout

The following layout is recommended for themes. Two files at the top leveldirectory called MANIFEST.in and setup.py beside the theme directory whichcontains an empty __init__.py file, a theme configuration file(mkdocs-theme.yml), and your template and media files.

The MANIFEST.in file should contain the following contents but withtheme_name updated and any extra file extensions added to the include.

The setup.py should include the following text with the modificationsdescribed below.

Fill in the URL, license, description, author and author email address.

Thememii Download

The name should follow the convention mkdocs-themename (like mkdocs-bootstrap and mkdocs-bootswatch), starting with MkDocs, using hyphens toseparate words and including the name of your theme.

Most of the rest of the file can be left unedited. The last section we need tochange is the entry_points. This is how MkDocs finds the theme(s) you areincluding in the package. The name on the left is the one that users will usein their mkdocs.yml and the one on the right is the directory containing yourtheme files.

The directory you created at the start of this section with the main.html fileshould contain all of the other theme files. The minimum requirement is thatit includes a main.html for the theme. It must also include a__init__.py file which should be empty, this file tells Python that thedirectory is a package.

Theme Configuration

A packaged theme is required to include a configuration file namedmkdocs_theme.yml which is placed in the root of your template files. The fileshould contain default configuration options for the theme. However, if thetheme offers no configuration options, the file is still required and can beleft blank. A theme which is not packaged does not need a mkdocs_theme.ymlfile as that file is not loaded from theme.custom_dir.

The theme author is free to define any arbitrary options deemed necessary andthose options will be made available in the templates to control behavior.For example, a theme might want to make a sidebar optional and include thefollowing in the mkdocs_theme.yml file:

Then in a template, that config option could be referenced:

And the user could override the default in their project's mkdocs.yml configfile:

In addition to arbitrary options defined by the theme, MkDocs defines a fewspecial options which alters its behavior:

static_templates

This option mirrors the theme config option of the same name and allowssome defaults to be set by the theme. Note that while the user can addtemplates to this list, the user cannot remove templates included in thetheme's config.

extends

Defines a parent theme that this theme inherits from. The value should bethe string name of the parent theme. Normal Jinja inheritance rules apply.

Plugins may also define some options which allow the theme to inform a pluginabout which set of plugin options it expects. See the documentation for anyplugins you may wish to support in your theme.

Distributing Themes

With the above changes, your theme should now be ready to install. This can bedone with pip, using pip install . if you are still in the same directory asthe setup.py.

Most Python packages, including MkDocs, are distributed on PyPI. To do this,you should run the following command.

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 packagingdocumentation for Packaging and Distributing Projects.