# 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]. [Tags plugin]: ../../plugins/tags.md __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. !!! example "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: ```yaml hl_lines="5 6" nav: - Home: index.md - Install: install.md - Usage: usage.md - Blog: - blog/index.md ``` 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: ```yaml hl_lines="3 4" theme: name: material features: - navigation.indexes ``` !!! tip "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. [Setting up a blog]: ../../setup/setting-up-a-blog.md#blog-only !!! tip "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. !!! example "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): ```yaml hl_lines="2" - blog: archive_date_format: MMMM yyyy ``` 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. !!! example "Add a category" Add a category to your first blog post by adding it to the page header: ``` hl_lines="4 5"" --- date: 2023-12-31 updated: 2024-01-02 categories: - Holidays --- ``` 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. !!! tip "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. !!! example "Control your categories" Add a `categories_allowed` entry to the configuration of the Blog plugin with the entries "Holidays" and "News": ```yaml hl_lines="5-7" plugins: - search - blog: archive_date_format: MMMM yyyy categories_allowed: - Holidays - 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. [Tags plugin]: https://squidfunk.github.io/mkdocs-material/plugins/tags/ 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. !!! example "Enable the plugin and add tags" First, you need to add the plugin to your `mkdocs.yml`: ```yaml hl_lines="8" 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: ``` hl_lines="9-12"" --- date: created: 2023-12-31 updated: 2024-01-02 authors: - material categories: - Holidays tags: - new year - hogmanay - festive season --- ``` 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. !!! example "Adding a tags index" === "Basic tag 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. ```yaml hl_lines="8-9 17" 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. === "Insider Edition" 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`. ```markdown # Tag index ``` 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`: ```markdown # Tag index for the blog ``` You now have two index pages: one covers the whole site and one covers only the blog. Add both to the navigation: ```yaml nav: - Home: index.md - Tags: tags.md - Blog: - blog/index.md - blog/tags.md ``` 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]. [tags plugin reference]: ../../plugins/tags.md ## 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. !!! example "Create author info" Create a file `docs/blog/.authors.yml` with this content: ```yaml 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: ```hl_lines="5-6" --- date: created: 2023-12-31 updated: 2024-01-02 authors: - team --- ``` 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. !!! example "Add author page " First, you need to enable author profiles in the `mkdocs.yml`: ```yaml hl_lines="8" 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: ```hl_lines="3" docs ├── blog │   ├── author │   ├── index.md │   └── posts │   ├── draft.md │   └── myfirst.md └── index.md ``` 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. !!! example "Changing pagination" Add five more blog posts, then set the pagination setting to show five per page only: ```yaml hl_lines="7" - 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: ```yaml - blog: archive_date_format: MMMM yyyy categories_allowed: - Holidays - News authors_profiles: true pagination_per_page: 5 archive_pagination_per_page: 10 categories_pagination_per_page: 10 ``` ## 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). !!! example "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: ```yaml hl_lines="2" - blog: blog_toc: true archive_date_format: MMMM yyyy # ... ``` ## 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. !!! example "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: ```python 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) ``` Save this code in `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: ```yaml hl_lines="4-6" 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. !!! example "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: ```hl_lines="7" --- date: created: 2023-12-31 updated: 2024-01-02 readtime: 15 pin: true slug: ny-eve --- ``` 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. [engagement and dissemination tutorial]: engage.md