Navigation, authors, and pagination¶
The Blog plugin provides blog-style navigation with a reverse-chronological index page and an archive organized by year by default. This tutorial shows how you can configure details of the default navigation, configure authors, and add more navigation options using categories and the Tags plugin.
Time required: typically 30 minutes
Integrating navigation¶
So far, you have let the Blog plugin and MkDocs worry about navigation. For some use cases, this might be enough and it is simply sufficient to not declare a nav section in the mkdocs.yml.
However, you may want to integrate a blog with other content and a navigation structure that you have defined in the nav section of the configuration. In such cases, you need to provide a place where the Blog plugin should attach the blog navigation to the rest of the navigation structure.
Integrate with site navigation
Add the following to your mkdocs.yml to see how the Blog plugin can integrate the blog navigation with the overall navigation structure. Note that the only thing you need to specify at this point is the index page for the blog and its path must match the blog_dir setting, which is blog by default:
You will notice that "Blog" is duplicated in the navigation structure. To avoid this, you can use the navigation.indexes feature to make the blog index the seciton index page for the blog:
Stand-alone blog
If what you need is a stand-alone blog instead of one that is integrated with a larger site, this can be done by using the blog_dir configuration option. To see how this is done, see setting up a blog. The rest of the tutorial assumes that you are integrating the blog with a wider site.
Adding pages
You can add additional pages to the blog section by putting them into docs/blog (and adding them to the navigation). The blog archive will be added to the navigation after these pages.
Configuring the archive¶
By default, the blog archive lists posts by year only. If you want to add listings by month, you can configure the date format for the archive.
Organize posts by month
Add the following to your mkdocs.yml to get a listing with the month name (in the language selected in the theme options):
If you do not want the full month name, you can make the the date configuration MM/yyyy, for example.
If you want to add the day, you can add a placeholder for them. For example, to get an American-style output, make it MM/dd/yyyy. For the plugin to sort the blog posts by the full date, you will also need to set the archive_url_date_format to include the month and day, so make it MM/dd/yyyy as well.
Using categories¶
Categories are a way to make blog posts accessible by topic while retaining the navigation structure based on chronology within each category listing. Use them when there is a limited set of non-overlapping categories that you can sort your posts into.
Categories appear in the main navigation, so are directly accessible from there. This implies that there are relatively few categories as otherwise the categories section in your main navigation will become too crowded.
Add a category
Add a category to your first blog post by adding it to the page header:
Now that the blog post has been categorised, Holidays appears under Categories in the main navigation and the blog post appears in the index page for this category.
Single or multiple categories?
While it is traditionally the case that a blog post would belong to only one category, Material for MkDocs actually allows you to assign more than one. While this gives you a degree of freedom, you should probably not use this too much, not least because you can use tags to deal with multiple classifications. We will cover them in the next step.
Material allows you to control which categories blog authors can use. You declare them in the mkdocs.yml. This way you can make sure everyone sticks to agreed categories and that the plugin detects typos.
Control your categories
Add a categories_allowed entry to the configuration of the Blog plugin with the entries "Holidays" and "News":
Now, when you add a category to a blog post that does not match one of these two, you should get a build error.
Using tags¶
The Tags plugin provides another way to classify blog posts and to make them accessible independently of the main navigation structure. Tags are useful for making related content easily discoverable even if it is in different parts of the navigation hierarchy.
You may have a tutorial like this one as well as a more comprehensive setup guide and reference documentation. Adding the same tag to all three shows that they are related. As you will see, it is possible to navigate from a tagged page to the tag index and, from there, to other pages that carry the same tag.
Enable the plugin and add tags
First, you need to add the plugin to your mkdocs.yml:
plugins:
- search
- blog:
archive_date_format: MMMM yyyy
categories_allowed:
- Holidays
- News
- tags
Once this is done, you can add tags to posts in the page header:
You should see the tags that you defined at the top of the post. However, at the moment that is it. While the blog plugin automatically creates an index page for categories, the tags plugin does not do the same for tags. This is because the tags plugin is not specific for blogs. You can use it for any site content, so it is not obvious were the tag index should go.
You can configure a basic tag index using the public version of Material for MkDocs. The Insider Edition supports this as well, of course, but also provides an alternative index mechanism that allows for an arbitrary number of tag indexes, scoped listings, shadow tags, nested tags, and much more.
Adding a tags index
To configure a tag index using the public version, add a tags_file entry to your configuration of the tags plugin and configure it in your nav section. Remember to add a colon at the end of the existing tags entry.
plugins:
- search
- blog:
archive_date_format: MMMM yyyy
categories_allowed:
- Holidays
- News
- tags:
tags_file: blog/tags.md
nav:
- Home: index.md
- Install: install.md
- Usage: usage.md
- Blog:
- blog/index.md
Tags: blog/tags.md
The tag index will be appended to the configured page, which you should now create at the location specified.
Note that you can put the tag index page anywhere in your primary navigation, so if you are using tags elsewhere instead of just in your blog then you may want to have the tag index outside the blog section of the navigation.
To add a tag index, you add a placeholder in a Markdown file to tell the plugin to insert an index at that point. This means that you can add content before and after the index. Crucially, you can add placeholders in multiple pages, each with a configuration of what subset of tags should be displayed in the index.
The simplest index page looks like this. Create it under docs/tags.md.
Now, you may want to keep the tags for your blog separate from tags you use in the rest of your page. You can achieve this by assigning the tag index a scope. Put the following under docs/blog/tags.md:
You now have two index pages: one covers the whole site and one covers only the blog. Add both to the navigation:
The tags plugin in the Insider Edition is an incredibly powerful tool and we can only scratch the surface of what is possible with it. If you want to explore more after you have worked for this part of the tutorial, have a look at the tags plugin reference.
Defining authors¶
If your blog has more than one author then you may want to identify the author for each blog post. The blog plugin allows you to create a file that contains the author information and to then reference the authors of a particular post in the page header.
Create author info
Create a file docs/blog/.authors.yml with this content:
authors:
team:
name: Team
description: Creator
avatar: https://simpleicons.org/icons/materialformkdocs.svg
squidfunk:
name: Martin Donath
description: Creator
avatar: https://github.com/squidfunk.png
and then add a line to the header of the first post:
Note that authors is a list, so you can specify multiple authors.
With the Insiders edition, you can create custom author index pages that can highlight the contributions of an author as well as provide additional information about them.
First, you need to enable author profiles in the mkdocs.yml:
plugins:
- search
- blog:
archive_date_format: MMMM yyyy
categories_allowed:
- Holidays
- News
authors_profiles: true
Check your blog to see that there is now an extra entry in the main navigation next to archive and categories that lists the authors and their contributions.
To customize the author page, you can create a page that overrides the one generated by default. First, create the author directory that the profile pages will live in:
Then create a page docs/blog/author/team.md:
# The Material Team
A small group of people dedicated to making writing documentation easy, if
not outright fun! Here are some of the things we have blogged about:
As you can see, the author index gets appended to the content you have written in the Markdown file.
Pagination¶
Once your blog starts growing, you may not want to pay attention to the number of posts displayed per page. By default, the plugin displays up to 10 posts on the index pages. You can change this number separately for the main index, the archive index pages, and the category index pages.
Changing pagination
Add five more blog posts, then set the pagination setting to show five per page only:
- blog:
archive_date_format: MMMM yyyy
categories_allowed:
- Holidays
- News
authors_profiles: true
pagination_per_page: 5
You will see that the pagination setting for archive and category pages are inherited from the setting you added. If you want to have different settings for the different index pages, you can specify each setting separately:
Blog table of contents¶
Another thing you may want to do once you have a large enough number of posts is to turn on the function that produces a table of contents for the blog index pages, giving your readers the opportunity to quickly scan the content of each page for something that interests them without having to scroll (assuming that the number of post per page is not too big).
Turn on the table of contents feature
To produce a table of contents for the blog index pages, add the following to the configuration of the blog plugin:
Custom slugs¶
If, for some reason, you are not happy with the way that Material for MkDocs turns headings into slugs, you can create your own slugify function or you can manually define a slug for a specific post.
Slugify function
To define your own slugify function, you need to write a Python function that converts text into a slug given additional arguments from the configuration. You also need to write a function that returns that function.
Say you want to define two slugify functions that you can switch between. The first one returns a slug similar to what the default slugify function produces. The second one cuts the result of that up into words and returns a slug based on a maximum of five of them:
import re, functools, unicodedata
RE_HTML_TAGS = re.compile(r'</?[^>]*>', re.UNICODE)
RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE)
RE_WHITESPACE = re.compile(r'\s', re.UNICODE)
def _make_slug(text, sep, **kwargs):
slug = unicodedata.normalize('NFC', text)
slug = RE_HTML_TAGS.sub('', slug)
slug = RE_INVALID_SLUG_CHAR.sub('', slug)
slug = slug.strip().lower()
slug = RE_WHITESPACE.sub(sep, slug)
return slug
def _make_slug_short(text, sep, **kwargs):
words = _make_slug(text, sep, **kwargs).split(sep)
return sep.join(words[:5])
def slugify(**kwargs):
if 'short' in kwargs and kwargs['short']:
return functools.partial(_make_slug_short, **kwargs)
return functools.partial(_make_slug, **kwargs)
ext/slugs.py and also add an (empty) __init__.py file to indicate that the directory is a module. Now you can configure your custom slugify code like this: plugins:
- blog:
# other entries omitted
post_slugify: !!python/object/apply:ext.slugs.slugify
kwds:
short: true
Change the heading of a blog post to be longer than five words and observe how the slugify function shortens the URL. Change the short attribute to false and you can turn this off again.
If you want to influence the slug only for a single blog post, you can define it manually by specifying it in the header of the post. Note that this is meant as a last resort option. Specifying a custom slug manually for every post would be tedious.
Manually define slug
If, for example, you wanted the slug to be 'ny-eve' instead of the somewhat lengthy 'happy-new-years-eve', you could add the following:
The URL for this post should now be http://localhost:8000/blog/2023/01/31/ny-eve/.
What's next?¶
You may want to increase engagement with your blog by allowing people to subscribe to an RSS feed, by providing links to your social media profiles, by providing share and like buttons, or by setting up a comment system. The engagement and dissemination tutorial walks you through setting these up.