9.0 KiB
Reference
Material for MkDocs is packed with many great features that make technical writing a joyful activity. 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 typeset plugin :material-alert-decagram:
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.27.0 · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental
The built-in typeset plugin preserves HTML formatting in the navigation and
table of contents. This means that now, code blocks, icons, emojis and other
inline formatting will be preserved, which allows for a richer editing
experience. Add the following lines to mkdocs.yml
:
plugins:
- typeset
For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: – code blocks and icons are preserved from the section headlines; even highlighting inline code blocks is supported 🎉
Built-in meta plugin
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.21.0 · :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
:
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 }-
: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
:plugins: - meta: meta_file: '**/.meta.yml' # (1)!
- Note that it's strongly recommended to prefix meta files with a
.
, since otherwise they would be included in the build output.
- Note that it's strongly recommended to prefix meta files with a
Usage
Setting the page title
Each page has a designated title, which is used in the navigation sidebar, for
social cards and in other places. While MkDocs attempts to automatically
determine the title of a page in a four step process, the title can also be
explicitly set with the front matter title
property:
---
title: Lorem ipsum dolor sit amet # (1)!
---
# Document title
...
- This line sets the
title
inside the HTML document'shead
for the generated page to the given value. Note that the site title, which is set viasite_name
, is appended with a dash.
Setting the page description
A Markdown file can include a description that is added to the meta
tags of
a page, and is also used for social cards. It's a good idea to set a
site_description
in mkdocs.yml
as a fallback value if
the author does not explicitly define a description for a Markdown file:
---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
---
# Document title
...
- This line sets the
meta
tag containing the description inside the documenthead
for the current page to the provided value.
Setting the page icon
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.5.0 · :octicons-beaker-24: Experimental
An icon can be assigned to each page, which is then rendered as part of the
navigation sidebar, as well as navigation tabs, if enabled. Use the front
matter icon
property to reference an icon, adding the following lines at the
top of a Markdown file:
---
icon: material/emoticon-happy # (1)!
---
# Document title
...
-
Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:
Setting the page status
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.22.0 · :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
:
extra:
status:
<identifier>: <description> # (1)!
-
The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a status
Recently added
, you can setnew
as an identifier:extra: status: new: Recently added
The page status can now be set with the front matter status
property. For
example, you can mark a page as new
with the following lines at the top of a
Markdown file:
---
status: new
---
# Document title
...
The following status identifiers are currently supported:
- :material-alert-decagram: –
new
- :material-trash-can: –
deprecated
Setting the page subtitle
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.25.0 · :octicons-beaker-24: Experimental
Each page can define a subtitle, which is then rendered below the title as part
of the navigation sidebar by using the front matter subtitle
property, and
adding the following lines:
---
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---
# Document title
...
Setting the page template
If you're using theme extension and created a new page template in the
overrides
directory, you can enable it for a specific page. Add the following
lines at the top of a Markdown file:
---
template: custom.html
---
# Document title
...
??? question "How to set a page template for an entire folder?"
With the help of the [built-in meta plugin], you can set a custom template
for an entire section and all nested pages, by creating a `.meta.yml` file
in the corresponding folder with the following content:
``` yaml
template: custom.html
```
Customization
Using metadata in templates
:material-check-all: on all pages
In order to add custom meta
tags to your document, you can extend the theme
and override the extrahead
block,
e.g. to add indexing policies for search engines via the robots
property:
{% extends "base.html" %}
{% block extrahead %}
<meta property="robots" content="noindex, nofollow" />
{% endblock %}
:material-check: on a single page
If you want to set a meta
tag on a single page, or want to set different
values for different pages, you can use the page.meta
object inside your
template override, e.g.:
{% extends "base.html" %}
{% block extrahead %}
{% if page and page.meta and page.meta.robots %}
<meta property="robots" content="{{ page.meta.robots }}" />
{% else %}
<meta property="robots" content="index, follow" />
{% endif %}
{% endblock %}
You can now use robots
exactly like title
and
description
to set values. Note that in this case, the
template defines an else
branch, which would set a default if none was given.