--- template: overrides/main.html --- # Reference Material for MkDocs is packed with many great features that make technical writing a pleasure. This section of the documentation explains how to set up a page, and showcases all available specimen that can be used directly from within Markdown files. ## Configuration ### Built-in meta plugin [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.21.0][Insiders] · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental The built-in meta plugin allows to __set front matter per folder__, which is especially handy to ensure that all pages in a folder use specific templates or tags. Add the following lines to `mkdocs.yml`: ``` yaml plugins: - meta ``` > If you need to be able to build your documentation with and without > [Insiders], please refer to the [built-in plugins] section to learn how > shared configurations help to achieve this. The following configuration options are available: [`meta_file`](#+meta.meta_file){ #+meta.meta_file } : :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the name of the meta files that the plugin should look for. The default setting assumes that meta files are called `.meta.yml`: ``` yaml plugins: - meta: meta_file: '**/.meta.yml' # (1)! ``` 1. Note that it's strongly recommended to prefix meta files with a `.`, since otherwise they would be included in the build output. [built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin [built-in plugins]: ../insiders/getting-started.md#built-in-plugins ## Usage ### Setting the page title The page title can be overridden for a document with the front matter `title` property. Add the following lines at the top of a Markdown file: ``` yaml --- title: Lorem ipsum dolor sit amet # (1)! --- # Document title ... ``` 1. This will set the [`title`][title] inside the HTML document's [`head`][head] for the generated page to this value. Note that the site title, which is set via [`site_name`][site_name], is appended with a dash. [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name ### Setting the page description The page description can be overridden for a document with the front matter `description` property. Add the following lines at the top of a Markdown file: ``` yaml --- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! --- # Document title ... ``` 1. This will set the `meta` tag containing the site description inside the document `head` for the current page to the provided value. ### Setting the page icon [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.5.0][Insiders] · :octicons-beaker-24: Experimental An icon can be assigned to each page, which is then rendered as part of the navigation sidebar. Add the following lines at the top of a Markdown file: ``` yaml --- icon: material/emoticon-happy # (1)! --- # Document title ... ``` 1. Enter a few keywords to find the perfect icon using our [icon search] and click on the shortcode to copy it to your clipboard:
[Insiders]: ../insiders/index.md [icon search]: icons-emojis.md#search ### Setting the page status [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.22.0][Insiders] · :octicons-beaker-24: Experimental A status can be assigned to each page, which is then displayed as part of the navigation sidebar. First, associate a status identifier with a description by adding the following to `mkdocs.yml`: ``` yaml extra: status: