Grouping of Rest items is not working

[ThuF]

I'm experiencing a TypeError error with the following configuration:

.pages:

order: desc
nav:
  - 2020 Blogs:
    - ... | regex=2020[A-Z0-9a-z_-]+.md
  - 2019 Blogs:
    - ... | regex=2019[A-Z0-9a-z_-]+.md

However the following configuration is working:

order: desc
nav:
  - ... | regex=2020[A-Z0-9a-z_-]+.md

Error:

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/__main__.py", line 133, in serve_command
    serve.serve(
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 141, in serve
    config = builder()
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 136, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 266, in build
    nav = config['plugins'].run_event('nav', nav, config=config, files=files)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/plugin.py", line 45, in on_nav
    return AwesomeNavigation(nav.items, Options(**self.config), config['docs_dir'], explicit_sections).to_mkdocs()
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/navigation.py", line 43, in __init__
    self.meta = NavigationMeta(items, options, docs_dir, explicit_sections)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/navigation.py", line 183, in __init__
    self.root = Meta.try_load_from(join_paths(root_path, self.options.filename))
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/meta.py", line 131, in try_load_from
    return Meta.load_from(path)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/meta.py", line 175, in load_from
    nav = [MetaNavItem.from_yaml(item, path) for item in nav]
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/meta.py", line 175, in <listcomp>
    nav = [MetaNavItem.from_yaml(item, path) for item in nav]
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/meta.py", line 41, in from_yaml
    raise TypeError('Invalid nav item format {type} [{context}]'.format(type=item, context=context))
TypeError: Invalid nav item format {'2020 Blogs': ['... | regex=2020[A-Z0-9a-z_-]+.md']} [/docs/docs/.pages]

Also I'm building a custom Docker image for Material for MkDocs, to include the awesome-pages-plugin: - https://squidfunk.github.io/mkdocs-material/getting-started/ - How to add plugins to the Docker image?

[lukasgeiter]

The nav config in .pages files doesn't support creating new sections. There are two ways to achieve what you want:

1. Create a folder for every year
2. Use the nav config in mkdocs.yml. It allows you to create sections which are not present in the file structure (README)

---

That said, let me know if you'd find such a feature useful and I'll see what I can do.

[ThuF]

Hi @lukasgeiter,

Thank you for the fast reply!

Yes, I think such feature request will make the plugin much more flexible!

I have the following use case - I am trying to update the look & feel of the Blogs section of Eclipse Dirigible with MkDocs (Material for MkDocs) and part of the task is how to organise the blogs. My initial attempt was to separate each blog post into separate year folder - 2020, 2019, 2018 etc. That way the default grouping is okay, but I need to change the ordering - 2020 to come first, instead of 2014 for example - order: desc. Also I want to introduce such ordering for the items (blogs) in each group (year), so that the latest blog will come first.

The existing naming convention that is as following - 2014-03-21-blogs_start_of_journey.md, but it can be changed to 03-21-blogs_start_of_journey.md for example.

Regards, Yordan

[lukasgeiter]

I'll see what I can do...

---

In the meantime, you should be able to do the following with the current version:

1. Create folders for every year
2. Put a .pages file with order: desc in each folder as well as on the top-level

I think this is actually a cleaner solution as it doesn't need regex and doesn't require you to manually list each year in nav.

[sharoonthomas]

@lukasgeiter any advice on how/where to implement this?

Would this be checking for type list here and then returning a nested list?

[zubieta]

Hi @lukasgeiter, this is something that would be pretty useful for me too. I have some docs autogenerated with openapi-codegen where the endpoints and models are all inside the same folder but it would be pretty useful to have them as sections in the nav. Moving the files into subfolders is not feasible since they contain cross links in the markdown that would need to be replaced, which is ugly and error prone.

So something like this would be pretty awesome:

nav:
  - Endpoints:
    - ... | *Api.md
  - Models:
    - ...

[lukasgeiter]

This is now possible in version 2.7.0