QUESTION: Blog in `nav:` and pagination problem

[Valdes-Tresanco-MS]

Hi. First of all, excellent plugin! I want to include it in my documentation as part of the navigation. However, when I add any element to the nav: automatically, the plugin stops paginating both blogs and reviews in the navigation sidebar. At first, I thought it was due to some compatibility problem with mkdocs material, but after testing the example, it behaves the same. Is there any way to fix this? Another point that is perhaps worth mentioning. Since mkdocs material implements tags as well, the way it is defined mixes both, having both tags in different index files and all tags appearing in both. Maybe changing the keyword tag to blog_tag or something like that should solve this problem. Thank you in advance

[liang2kl]

Could you please provide more context for me to reproduce the problem? You can follow the template in https://github.com/liang2kl/mkdocs-blogging-plugin/issues/new/choose to do this.

[Valdes-Tresanco-MS]

Suppose I have documentation that already has other pages defined in the navigation. For example:

nav:
  - Home: index.md
  - Getting started:
      -  Getting started: getting_started.md

If I want to add a section that has the Blog content, the navigation mode defined by your plugin is lost.

nav:
  - Home: index.md
  - Getting started:
      -  Getting started: getting_started.md
  - Blog: blog.md             # blog.md contain {{ blog_content }}

This appears in the terminal

INFO     -  The following pages exist in the docs directory but are not
            included in the "nav" configuration:
              - reviews.md
              - tags.md
              - blog/blog1.md
              - blog/blog2.md
              - blog/blog3.md
              - reviews/review1.md
              - reviews/review2.md
              - reviews/review3.md

You can reproduce this problem by adding the nav to the example file.

# This is a template for setting up a blog page using mkdocs-bloggin-plugin
# (https://github.com/liang2kl/mkdocs-blogging-plugin). Please follow the
# guide (https://liang2kl.github.io/mkdocs-blogging-plugin) for further
# customization. You can also follow an example project
# (https://liang2kl.github.io/mkdocs-blogging-plugin-example) to customize
# the appearance using templates.

# [NOTE] change this to your site name
site_name: Blog Template
# [NOTE] change this to your site url
site_url: https://liang2kl.github.io/mkdocs-blogging-plugin-bootstrap/
# [NOTE] change these three repo settings, delete them if not desired
repo_url: https://github.com/liang2kl/mkdocs-blogging-plugin-bootstrap/
repo_name: liang2kl/mkdocs-blogging-plugin-example
edit_uri: ""

# [NOTE] edit mkdocs configs as normal
theme:
  name: 'material'

plugins:
  - blogging:
      dirs:
        - blog
      categories:
        - name: reviews
          dirs:
            - reviews
      features:
        tags:
          index_page: tags.md
          insert: top

nav:
  - Blog: index.md

Reviewing the mkdocs code, I saw why. As I see it, by not defining the navigation in the mkdocs.yml file, mkdocs uses the files list to generate the navigation. But both cases are in contrast, that is, either the navigation defined in the mkdocs.yml file is used, or the files list is used to generate it. https://github.com/mkdocs/mkdocs/blob/b776ad8820cbcc53079ac3e75c04ba7e6d96c47c/mkdocs/structure/nav.py#L148-L150

If I add the main page that defines the blogs, the one containing {{ blog_content }} to the navigation, then the blog navigation is not generated. That is, you get this: instead of this:

I was looking if it was possible to do it while the plugin is loading, using the on_files method to add the files and their labels to config['nav'], but I was busy with another important thing. Another possible idea would be to use on_nav to update it, but you would need to create separate navigation by calling the function get_navigation https://github.com/mkdocs/mkdocs/blob/b776ad8820cbcc53079ac3e75c04ba7e6d96c47c/mkdocs/structure/nav.py#L148-L192 with a modified config.

I hope I have explained the issue well. Let me know any other things you need to reproduce the problem.

[liang2kl]

Thank you for the detailed context!

Unfortunately, the plugin does nothing about navigation at this point. You will get an automatically generated navigation list from mkdocs if you omit the nav setting, but you will have to fill them up by yourself if you want to customize nav because the plugin will not touch the navigation structure, and mkdocs expects you to define it.

It would be an interesting feature of the plugin to automatically do that. I might take some time into this in the future, and feel free to implement this if you want.