\n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -303,15 +303,15 @@\n current page is the last item in the site navigation or if the current page is\n not included in the navigation at all.\n ** parent: Optional[Section] class-attribute \u00ef\u0083\u0081 **\n The immediate parent of the page in the site navigation. None if the page is at\n the top level.\n ** children: None = None class-attribute \u00ef\u0083\u0081 **\n Pages do not contain children and the attribute is always None.\n-** active: bool writable property \u00ef\u0083\u0081 **\n+** active: bool property writable \u00ef\u0083\u0081 **\n When True, indicates that this page is the currently viewed page. Defaults to\n False.\n ** is_section: bool = False class-attribute \u00ef\u0083\u0081 **\n Indicates that the navigation object is a \"section\" object. Always False for\n page objects.\n ** is_page: bool = True class-attribute \u00ef\u0083\u0081 **\n Indicates that the navigation object is a \"page\" object. Always True for page\n@@ -346,15 +346,15 @@\n ** title: str class-attribute \u00ef\u0083\u0081 **\n The title of the section.\n ** parent: Optional[Section] class-attribute \u00ef\u0083\u0081 **\n The immediate parent of the section or None if the section is at the top level.\n ** children: List[Union[Page, Section, Link]] class-attribute \u00ef\u0083\u0081 **\n An iterable of all child navigation objects. Children may include nested\n sections, pages and links.\n-** active: bool writable property \u00ef\u0083\u0081 **\n+** active: bool property writable \u00ef\u0083\u0081 **\n When True, indicates that a child page of this section is the current page and\n can be used to highlight the section as the currently viewed section. Defaults\n to False.\n ** is_section: bool = True class-attribute \u00ef\u0083\u0081 **\n Indicates that the navigation object is a \"section\" object. Always True for\n section objects.\n ** is_page: bool = False class-attribute \u00ef\u0083\u0081 **\n"}]}, {"source1": "./usr/share/doc/mkdocs/html/search/search_index.json", "source2": "./usr/share/doc/mkdocs/html/search/search_index.json", "unified_diff": null, "details": [{"source1": "Pretty-printed", "source2": "Pretty-printed", "comments": ["Similarity: 0.9998075442648191%", "Differences: {\"'docs'\": \"{156: {'text': 'API reference \\\\uf0c1 Note The main entry point to the API is through \"", " \"Events that are received by plugins. These events\\\\' descriptions link back to this \"", " 'page. mkdocs.structure.files.Files \\\\uf0c1 A collection of File objects. src_paths: '", " 'Dict[str, File] property \\\\uf0c1 Soft-deprecated, prefer src_uris . src_uris: '", " 'Dict[str, File] property \\\\uf0c1 A mapping containing every file, with the keys being '", " 'their src_ur [\u2026]"], "unified_diff": "@@ -787,15 +787,15 @@\n {\n \"location\": \"dev-guide/index.html#developer-guide\",\n \"text\": \"Extending MkDocs The MkDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the Contributing Guide for information on contributing to MkDocs itself. You can jump directly to a page listed below, or use the next and previous buttons in the navigation bar at the top of the page to move through the documentation in order. Themes Translations Plugins API Reference\",\n \"title\": \"Developer Guide\"\n },\n {\n \"location\": \"dev-guide/api.html\",\n- \"text\": \"API reference \\uf0c1 Note The main entry point to the API is through Events that are received by plugins. These events' descriptions link back to this page. mkdocs.structure.files.Files \\uf0c1 A collection of File objects. src_paths: Dict[str, File] property \\uf0c1 Soft-deprecated, prefer src_uris . src_uris: Dict[str, File] property \\uf0c1 A mapping containing every file, with the keys being their src_uri . __iter__() -> Iterator[File] \\uf0c1 Iterate over the files within. __len__() -> int \\uf0c1 The number of files within. __contains__(path: str) -> bool \\uf0c1 Whether the file with this src_uri is in the collection. get_file_from_path(path: str) -> Optional[File] \\uf0c1 Return a File instance with File.src_uri equal to path. append(file: File) -> None \\uf0c1 Append file to Files collection. remove(file: File) -> None \\uf0c1 Remove file from Files collection. copy_static_files(dirty: bool = False) -> None \\uf0c1 Copy static files from source to destination. documentation_pages() -> Sequence[File] \\uf0c1 Return iterable of all Markdown page file objects. static_pages() -> Sequence[File] \\uf0c1 Return iterable of all static page file objects. media_files() -> Sequence[File] \\uf0c1 Return iterable of all file objects which are not documentation or static pages. javascript_files() -> Sequence[File] \\uf0c1 Return iterable of all javascript file objects. css_files() -> Sequence[File] \\uf0c1 Return iterable of all CSS file objects. add_files_from_theme(env: jinja2.Environment, config: MkDocsConfig) -> None \\uf0c1 Retrieve static files from Jinja environment and add to collection. mkdocs.structure.files.File \\uf0c1 A MkDocs File object. Points to the source and destination locations of a file. The path argument must be a path that exists relative to src_dir . The src_dir and dest_dir must be absolute paths on the local file system. The use_directory_urls argument controls how destination paths are generated. If False , a Markdown file is mapped to an HTML file of the same name (the file extension is changed to .html ). If True, a Markdown file is mapped to an HTML index file ( index.html ) nested in a directory using the \\\"name\\\" of the file in path . The use_directory_urls argument has no effect on non-Markdown files. File objects have the following properties, which are Unicode strings: src_uri: str class-attribute \\uf0c1 The pure path (always '/'-separated) of the source file relative to the source directory. dest_path: str writable property \\uf0c1 Same as dest_uri (and synchronized with it) but will use backslashes on Windows. Discouraged. url_relative_to(other: File) -> str \\uf0c1 Return url for file relative to other file. copy_file(dirty: bool = False) -> None \\uf0c1 Copy source file to destination, ensuring parent directories exist. is_documentation_page() -> bool \\uf0c1 Return True if file is a Markdown page. is_static_page() -> bool \\uf0c1 Return True if file is a static page (HTML, XML, JSON). is_media_file() -> bool \\uf0c1 Return True if file is not a documentation or static page. is_javascript() -> bool \\uf0c1 Return True if file is a JavaScript file. is_css() -> bool \\uf0c1 Return True if file is a CSS file. mkdocs.config.base.Config \\uf0c1 Bases: UserDict Base class for MkDocs configuration, plugin configuration (and sub-configuration) objects. It should be subclassed and have ConfigOption s defined as attributes. For examples, see mkdocs/contrib/search/ init .py and mkdocs/config/defaults.py. Behavior as it was prior to MkDocs 1.4 is now handled by LegacyConfig. __new__(*args, **kwargs) -> Config \\uf0c1 Compatibility: allow referring to LegacyConfig(...) constructor as Config(...) . set_defaults() -> None \\uf0c1 Set the base config by going through each validator and getting the default if it has one. load_dict(patch: Optional[dict]) -> None \\uf0c1 Load config options from a dictionary. load_file(config_file: IO) -> None \\uf0c1 Load config options from the open file descriptor of a YAML file. mkdocs.livereload.LiveReloadServer \\uf0c1 Bases: socketserver . ThreadingMixIn , wsgiref . simple_server . WSGIServer watch(path: str, func: Optional[Callable[[], None]] = None, recursive: bool = True) -> None \\uf0c1 Add the 'path' to watched paths, call the function and reload when any file changes under it. unwatch(path: str) -> None \\uf0c1 Stop watching file changes for path. Raises if there was no corresponding watch call.\",\n+ \"text\": \"API reference \\uf0c1 Note The main entry point to the API is through Events that are received by plugins. These events' descriptions link back to this page. mkdocs.structure.files.Files \\uf0c1 A collection of File objects. src_paths: Dict[str, File] property \\uf0c1 Soft-deprecated, prefer src_uris . src_uris: Dict[str, File] property \\uf0c1 A mapping containing every file, with the keys being their src_uri . __iter__() -> Iterator[File] \\uf0c1 Iterate over the files within. __len__() -> int \\uf0c1 The number of files within. __contains__(path: str) -> bool \\uf0c1 Whether the file with this src_uri is in the collection. get_file_from_path(path: str) -> Optional[File] \\uf0c1 Return a File instance with File.src_uri equal to path. append(file: File) -> None \\uf0c1 Append file to Files collection. remove(file: File) -> None \\uf0c1 Remove file from Files collection. copy_static_files(dirty: bool = False) -> None \\uf0c1 Copy static files from source to destination. documentation_pages() -> Sequence[File] \\uf0c1 Return iterable of all Markdown page file objects. static_pages() -> Sequence[File] \\uf0c1 Return iterable of all static page file objects. media_files() -> Sequence[File] \\uf0c1 Return iterable of all file objects which are not documentation or static pages. javascript_files() -> Sequence[File] \\uf0c1 Return iterable of all javascript file objects. css_files() -> Sequence[File] \\uf0c1 Return iterable of all CSS file objects. add_files_from_theme(env: jinja2.Environment, config: MkDocsConfig) -> None \\uf0c1 Retrieve static files from Jinja environment and add to collection. mkdocs.structure.files.File \\uf0c1 A MkDocs File object. Points to the source and destination locations of a file. The path argument must be a path that exists relative to src_dir . The src_dir and dest_dir must be absolute paths on the local file system. The use_directory_urls argument controls how destination paths are generated. If False , a Markdown file is mapped to an HTML file of the same name (the file extension is changed to .html ). If True, a Markdown file is mapped to an HTML index file ( index.html ) nested in a directory using the \\\"name\\\" of the file in path . The use_directory_urls argument has no effect on non-Markdown files. File objects have the following properties, which are Unicode strings: src_uri: str class-attribute \\uf0c1 The pure path (always '/'-separated) of the source file relative to the source directory. dest_path: str property writable \\uf0c1 Same as dest_uri (and synchronized with it) but will use backslashes on Windows. Discouraged. url_relative_to(other: File) -> str \\uf0c1 Return url for file relative to other file. copy_file(dirty: bool = False) -> None \\uf0c1 Copy source file to destination, ensuring parent directories exist. is_documentation_page() -> bool \\uf0c1 Return True if file is a Markdown page. is_static_page() -> bool \\uf0c1 Return True if file is a static page (HTML, XML, JSON). is_media_file() -> bool \\uf0c1 Return True if file is not a documentation or static page. is_javascript() -> bool \\uf0c1 Return True if file is a JavaScript file. is_css() -> bool \\uf0c1 Return True if file is a CSS file. mkdocs.config.base.Config \\uf0c1 Bases: UserDict Base class for MkDocs configuration, plugin configuration (and sub-configuration) objects. It should be subclassed and have ConfigOption s defined as attributes. For examples, see mkdocs/contrib/search/ init .py and mkdocs/config/defaults.py. Behavior as it was prior to MkDocs 1.4 is now handled by LegacyConfig. __new__(*args, **kwargs) -> Config \\uf0c1 Compatibility: allow referring to LegacyConfig(...) constructor as Config(...) . set_defaults() -> None \\uf0c1 Set the base config by going through each validator and getting the default if it has one. load_dict(patch: Optional[dict]) -> None \\uf0c1 Load config options from a dictionary. load_file(config_file: IO) -> None \\uf0c1 Load config options from the open file descriptor of a YAML file. mkdocs.livereload.LiveReloadServer \\uf0c1 Bases: socketserver . ThreadingMixIn , wsgiref . simple_server . WSGIServer watch(path: str, func: Optional[Callable[[], None]] = None, recursive: bool = True) -> None \\uf0c1 Add the 'path' to watched paths, call the function and reload when any file changes under it. unwatch(path: str) -> None \\uf0c1 Stop watching file changes for path. Raises if there was no corresponding watch call.\",\n \"title\": \"API Reference\"\n },\n {\n \"location\": \"dev-guide/api.html#api-reference\",\n \"text\": \"Note The main entry point to the API is through Events that are received by plugins. These events' descriptions link back to this page.\",\n \"title\": \"API reference\"\n },\n@@ -1192,15 +1192,15 @@\n {\n \"location\": \"dev-guide/plugins.html#entry-point\",\n \"text\": \"Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_points . Add the following to your setup.py script: entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself ( from path.to.some_plugin import SomePluginClass ) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry point. entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] } Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.\",\n \"title\": \"Entry Point\"\n },\n {\n \"location\": \"dev-guide/themes.html\",\n- \"text\": \"Developing Themes \\uf0c1 A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage. Creating a custom theme \\uf0c1 The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \\\"mkdocs\\\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme. Basic theme \\uf0c1 The simplest main.html file is the following:
{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} {{ page.content }} The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency. Theme Files \\uf0c1 There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file. Template Files \\uf0c1 Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension. Theme Meta Files \\uf0c1 The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files. Dot Files \\uf0c1 Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt Documentation Files \\uf0c1 All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored. Template Variables \\uf0c1 Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html. Global Context \\uf0c1 The following variables are available globally on any template. config \\uf0c1 The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics nav \\uf0c1 The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes: homepage: Optional[Page] class-attribute \\uf0c1 The page object for the homepage of the site. pages: List[Page] class-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 %} - {{ nav_item.title }}
{% else %} - {{ nav_item.title }}
{% endif %} {% endfor %}
{% endif %} base_url \\uf0c1 The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url . mkdocs_version \\uf0c1 Contains the current MkDocs version. build_date_utc \\uf0c1 A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated. pages \\uf0c1 A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page . page \\uf0c1 In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes: title: Optional[str] class-attribute \\uf0c1 Contains the Title for the current page. content: Optional[str] class-attribute \\uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. toc: TableOfContents class-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] class-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 class-attribute \\uf0c1 The documentation File that the page is being rendered from. abs_url: Optional[str] class-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: Optional[str] class-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: Optional[str] class-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: Optional[Page] class-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: Optional[Page] class-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: Optional[Section] class-attribute \\uf0c1 The immediate parent of the page in the site navigation. None if the page is at the top level. children: None = None class-attribute \\uf0c1 Pages do not contain children and the attribute is always None . active: bool writable property \\uf0c1 When True , indicates that this page is the currently viewed page. Defaults to False . is_section: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always False for page objects. is_page: bool = True class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always True for page objects. is_link: bool = False class-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 class-attribute \\uf0c1 The text of the item. url: str property \\uf0c1 The hash fragment of a URL pointing to the item. level: int class-attribute \\uf0c1 The zero-based level of the item. children: List[AnchorLink] class-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. The following attributes are available on section objects: title: str class-attribute \\uf0c1 The title of the section. parent: Optional[Section] class-attribute \\uf0c1 The immediate parent of the section or None if the section is at the top level. children: List[Union[Page, Section, Link]] class-attribute \\uf0c1 An iterable of all child navigation objects. Children may include nested sections, pages and links. active: bool writable property \\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 \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always True for section objects. is_page: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always False for section objects. is_link: bool = False class-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. The following attributes are available on link objects: title: str class-attribute \\uf0c1 The title of the link. This would generally be used as the label of the link. url: str class-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: Optional[Section] class-attribute \\uf0c1 The immediate parent of the link. None if the link is at the top level. children: None = None class-attribute \\uf0c1 Links do not contain children and the attribute is always None . active: bool = False class-attribute \\uf0c1 External links cannot be \\\"active\\\" and the attribute is always False . is_section: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always False for link objects. is_page: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always False for link objects. is_link: bool = True class-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 Safety convert a Python object to a value in a JavaScript script. Search and themes \\uf0c1 As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. 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.\",\n+ \"text\": \"Developing Themes \\uf0c1 A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage. Creating a custom theme \\uf0c1 The bare minimum required for a custom theme is a main.html Jinja2 template file which is placed in a directory that is not a child of the docs_dir . Within mkdocs.yml , set the theme.custom_dir option to the path of the directory containing main.html . The path should be relative to the configuration file. For example, given this example project layout: mkdocs.yml docs/ index.md about.md custom_theme/ main.html ... ... you would include the following settings in mkdocs.yml to use the custom theme directory: theme: name: null custom_dir: 'custom_theme/' Note Generally, when building your own custom theme, the theme. name configuration setting would be set to null . However, if the theme. custom_dir configuration value is used in combination with an existing theme, the theme. custom_dir can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set name: \\\"mkdocs\\\" then the main.html file in the theme. custom_dir would replace the file of the same name in the mkdocs theme but otherwise the mkdocs theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. For more specific information, see Customizing Your Theme . Warning A theme's configuration defined in a mkdocs_theme.yml file is not loaded from theme.custom_dir . When an entire theme exists in theme.custom_dir and theme.name is set to null , then the entire theme configuration must be defined in the theme configuration option in the mkdocs.yml file. However, when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme. Basic theme \\uf0c1 The simplest main.html file is the following: {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} {{ page.content }} The body content from each page specified in mkdocs.yml is inserted using the {{ page.content }} tag. Style-sheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav and toc objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly. Note As MkDocs uses Jinja as its template engine, you have access to all the power of Jinja, including template inheritance . You may notice that the themes included with MkDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme custom_dir . Therefore, the built-in themes are implemented in a base.html file, which main.html extends. Although not required, third party template authors are encouraged to follow a similar pattern and may want to define the same blocks as are used in the built-in themes for consistency. Theme Files \\uf0c1 There are various files which a theme treats special in some way. Any other files are simply copied from the theme directory to the same path in the site_dir when the site it built. For example image and CSS files have no special significance and are copied as-is. Note, however, that if the user provides a file with the same path in their docs_dir , then the user's file will replace the theme file. Template Files \\uf0c1 Any files with the .html extension are considered to be template files and are not copied from the theme directory or any subdirectories. Also, any files listed in static_templates are treated as templates regardless of their file extension. Theme Meta Files \\uf0c1 The various files required for packaging a theme are also ignored. Specifically, the mkdocs_theme.yml configuration file and any Python files. Dot Files \\uf0c1 Theme authors can explicitly force MkDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: .ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt Documentation Files \\uf0c1 All documentation files are ignored. Specifically, any Markdown files (using any of the file extensions supported by MKDocs). Additionally, any README files which may exist in the theme directories are ignored. Template Variables \\uf0c1 Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html. Global Context \\uf0c1 The following variables are available globally on any template. config \\uf0c1 The config variable is an instance of MkDocs' config object generated from the mkdocs.yml config file. While you can use any config option, some commonly used options include: config.site_name config.site_url config.site_author config.site_description config.theme.locale (See also Theme Configuration below) config.extra_javascript config.extra_css config.repo_url config.repo_name config.copyright config.google_analytics nav \\uf0c1 The nav variable is used to create the navigation for the documentation. The nav object is an iterable of navigation objects as defined by the nav configuration setting. In addition to the iterable of navigation objects , the nav object contains the following attributes: homepage: Optional[Page] class-attribute \\uf0c1 The page object for the homepage of the site. pages: List[Page] class-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 %} - {{ nav_item.title }}
{% else %} - {{ nav_item.title }}
{% endif %} {% endfor %}
{% endif %} base_url \\uf0c1 The base_url provides a relative path to the root of the MkDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the url template filter, which is smarter about how it applies base_url . mkdocs_version \\uf0c1 Contains the current MkDocs version. build_date_utc \\uf0c1 A Python datetime object that represents the date and time the documentation was built in UTC. This is useful for showing how recently the documentation was updated. pages \\uf0c1 A flat list of File objects for all pages in the project. This list can contain pages not included in the global navigation and may not match the order of pages within that navigation. The page object for each File can be accessed from file.page . page \\uf0c1 In templates which are not rendered from a Markdown source file, the page variable is None . In templates which are rendered from a Markdown source file, the page variable contains a page object. The same page objects are used as page navigation objects in the global navigation and in the pages template variable. All page objects contain the following attributes: title: Optional[str] class-attribute \\uf0c1 Contains the Title for the current page. content: Optional[str] class-attribute \\uf0c1 The rendered Markdown as HTML, this is the contents of the documentation. toc: TableOfContents class-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] class-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 class-attribute \\uf0c1 The documentation File that the page is being rendered from. abs_url: Optional[str] class-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: Optional[str] class-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: Optional[str] class-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: Optional[Page] class-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: Optional[Page] class-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: Optional[Section] class-attribute \\uf0c1 The immediate parent of the page in the site navigation. None if the page is at the top level. children: None = None class-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 \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always False for page objects. is_page: bool = True class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always True for page objects. is_link: bool = False class-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 class-attribute \\uf0c1 The text of the item. url: str property \\uf0c1 The hash fragment of a URL pointing to the item. level: int class-attribute \\uf0c1 The zero-based level of the item. children: List[AnchorLink] class-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. The following attributes are available on section objects: title: str class-attribute \\uf0c1 The title of the section. parent: Optional[Section] class-attribute \\uf0c1 The immediate parent of the section or None if the section is at the top level. children: List[Union[Page, Section, Link]] class-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 \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always True for section objects. is_page: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always False for section objects. is_link: bool = False class-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. The following attributes are available on link objects: title: str class-attribute \\uf0c1 The title of the link. This would generally be used as the label of the link. url: str class-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: Optional[Section] class-attribute \\uf0c1 The immediate parent of the link. None if the link is at the top level. children: None = None class-attribute \\uf0c1 Links do not contain children and the attribute is always None . active: bool = False class-attribute \\uf0c1 External links cannot be \\\"active\\\" and the attribute is always False . is_section: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"section\\\" object. Always False for link objects. is_page: bool = False class-attribute \\uf0c1 Indicates that the navigation object is a \\\"page\\\" object. Always False for link objects. is_link: bool = True class-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 Safety convert a Python object to a value in a JavaScript script. Search and themes \\uf0c1 As of MkDocs version 0.17 client side search support has been added to MkDocs via the search plugin. A theme needs to provide a few things for the plugin to work with the theme. While the search plugin is activated by default, users can disable the plugin and themes should account for this. It is recommended that theme templates wrap search specific markup with a check for the plugin: {% if 'search' in config['plugins'] %} search stuff here... {% endif %} At its most basic functionality, the search plugin will simply provide an index file which is no more than a JSON file containing the content of all pages. The theme would need to implement its own search functionality client-side. However, with a few settings and the necessary templates, the plugin can provide a complete functioning client-side search tool based on lunr.js . The following HTML needs to be added to the theme so that the provided JavaScript is able to properly load the search scripts and make relative links to the search results from the current page. 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.\",\n \"title\": \"Themes\"\n },\n {\n \"location\": \"dev-guide/themes.html#developing-themes\",\n \"text\": \"A guide to creating and distributing custom themes. Note If you are looking for existing third party themes, they are listed in the MkDocs community wiki . If you want to share a theme you create, you should list it on the Wiki. When creating a new theme, you can either follow the steps in this guide to create one from scratch or you can download the mkdocs-basic-theme as a basic, yet complete, theme with all the boilerplate required. You can find this base theme on GitHub . It contains detailed comments in the code to describe the different features and their usage.\",\n \"title\": \"Developing Themes\"\n },\n"}]}]}]}]}]}