The new flat feature is great, but unfortunately it has some limitations:

1. The following one works as expected - under Project Name I get one, flat list of pages from docs/ and from all subdirs inside docs/.

nav:
  - Projects:
     - Project Name:
        - ... | flat | projects/project-name/docs/**/*

However - what If I don't want to flat subdirs? What I mean is - I would like to avoid Docs in nav, but I would like to preserve all the subdirs, so I get:

• Projects/
  • Project Name/
    • Page 1
    • Page 2
    • Subdir/
      • Page 3

And of course the point is not to define all the subdirs manually, but to autogenerate it.

I tested 2 approaches:

• in the below scenario we only get Page 1 and Page 2; Subdir and Page 3 are not included at all.

nav:
  - Projects:
     - Project Name:
        - ... | flat | projects/project-name/docs/*

• I tested both above variants with additional .pages file inside projects/project-name/docs/ with various combinations, i.a. with subdir specified explicitly:

nav:
  - subdir
  - ...

but it didn't have any impact on results - they were exactly the same as before.

2. Another issue I have is the usage of that new functionality within .pages files. I wanted to use such nav in main mkdocs.yml:

nav:
  - ... | projects/**/*

to automatically populate all the projects (actually in that example I don't need to specify nav at all to get the same result, but in real-life scenarios I just use it to define the proper order of nav tabs). It works great as it is, but of course then we have unwanted Docs in nav. My idea was to define .pages file in each project and specify there to flat the sub-structure to avoid Docs in nav.

I created such projects/project-name/.pages file then:

nav:
  - ... | flat | docs

but it doesn't work - I get exactly the same results as without the file, so Docs stays in nav. I did a few more tests:

• - ... | flat - the same result
• - ... | flat | docs/* - doesn't work at all, nothing is generated
• - docs | flat - returns an error: mkdocs_awesome_pages_plugin.navigation.NavEntryNotFound: Nav entry "docs | flat" not found.

As mentioned by @lukasgeiter in #36:

The feature was not designed to do anything more than flatten the list of remaining pages.

and that's the reason why it doesn't cover more complicated scenarios, when we actually need to work more with dirs than just pages. That FR is about extending the functionality of flat.

I'd like to configure nav contains pop up menu, like this:

What I got now doesn't contains a menu in nav.

the mkdocs.yml:
`
site_name: 畅云时讯
site_url: http://www.ichangyun.cn

#strict: true

theme:
name: material
language: zh
logo: image/icon.ico
palette:
primary: light blue
features:
- navigation.indexes
- navigation.tabs
- navigation.instant
- navigation.tabs.sticky
markdown_extensions:

• pymdownx.emoji:
  emoji_index: !!python/name:materialx.emoji.twemoji
  emoji_generator: !!python/name:materialx.emoji.to_svg
• pymdownx.critic
• pymdownx.caret
• pymdownx.mark
• pymdownx.tilde
• pymdownx.tabbed
• attr_list
• pymdownx.arithmatex:
  generic: true
• pymdownx.highlight:
  linenums: true
• pymdownx.superfences
• pymdownx.details
• admonition
• toc:
  baselevel: 2
  permalink: true
  slugify: !!python/name:pymdownx.slugs.uslugify
• meta
  plugins:
• include-markdown
• search:
  lang: ja
• awesome-pages
  `

the top level .pages:

`
nav:

• 首页: index.md
• 产品中心: products
• 解决方案: solutions
• 联合实验室: lab
• 新闻动态: news
• 关于我们: about
  `

Hi!
this plugin is awesome 👍

but there is an error with files that are encoded with UTF-8, I had to edit the following line
`
File "c:\users\perezv\appdata\local\programs\python\python36\lib\site-packages\mkdocs_awesome_pages_plugin\factory.py", line 68, in _create_leaf_page

with open(path, encoding='UTF-8') as file:
`
in order to get it to work on my project.

Thanks!

First of all, thanks for this awesome plugin! It has already saved my day. :)

I'm having trouble arranging the order of the toplevel entries in the navigation bar.

My docs folder looks like this:

docs/
├── .pages
├── how_to_guides
│   ├── .pages
│   ├── running_the_tests.md
│   └── setting_up_a_dev_environment.md
└── tutorials
    └── first_steps.md

I would like the entries in the navigation bar to appear in the following order:

Tutorials
  - First steps
How-To Guides
  - Setting up a dev environment
  - Running the tests

To achieve this, I have two .pages files (one at the toplevel and another one inside the how_to_guides folder). These look as follows:

$ cat docs/.pages
arrange:
  - tutorials
  - how_to_guides

$ cat docs/how_to_guides/.pages 
arrange:
  - setting_up_a_dev_environment.md
  - running_the_tests.md

Now, the file how_to_guides/.pages is picked up correctly by the plugin, so the order of the two entries "Setting up a dev environment" and "Running the tests" (underneath "How-To Guides") ends up being correct.

However, it seems that the toplevel .pages file is not being picked up by the plugin, and so the order of "Tutorials" and "How-To Guides" ends up being the wrong way around.

Is this a bug or am I missing something obvious? Many thanks for any help!

In order to achieve top-level sections (e.g. to utilize material navigation tabs), I need to either:

• use this plugin but restructure all of my docs based on those sections
• use the native mkdocs nav functionality, and miss out on the good features here including the spread operator for the "rest" of the pages

It would be great to be able to specify custom sections in the .pages file of the docs_dir, e.g.:

nav:
  - Vision:
    - principles.md
    - roadmap.md
  - People:
    - team.md
    - advisors.md
  - ...

In vanilla mkdocs, you're able to define your mkdocs.ymal to have web pages that purely redirect to a link.

nav:
  - Home: 'index.md'
  - Stack Overflow: 'https://stackoverflow.com/'

This would create navigation that showed an item called Stack Overflow and allow it to be clickable. Therefore a page was not needed. Is there a way to configure this already with awesome-pages or would it need to be implemented?

My group has some theme overrides setup to not render the entire nav menu of our main index page since we want the main page to be clean and the other pages are more "utility" in nature. It would be nice if this were built-in and we didn't need the custom theme work.

It feels like this functionality best fits with this plugin, hence why this enhancement suggestion was created.

I was thinking that if we don't declare the "..." and the file into the .pages-file, the specific file won't show up after rendering. Is there a Way to just render the Files that are in the .pages-file if there isn't a "..." added to the .pages-file?

Example 1:
- dir
  -  .pages
  - index.md
  - not-included.md

.pages-file:
title: Test
arrange:
    - index.md

Result: not-included.md should not be part of the generated documentation.

And now with dots:

Example 1:
- dir
  -  .pages
  - index.md
  - should-be-included.md

.pages-file:
title: Test
arrange:
    - index.md
    - ...

Result: not-included.md should be part of the generated documentation.

I have a portion of my site I'd like to use to document templates (things we create as part of our project not anything to do with MkDocs itself).

The site build breaks when I list 'templates' under arrange in the docs/.pages file.

arrange:
    - index.md
    - ...
    - templates

INFO    -  Cleaning site directory
--
243 | INFO    -  Building documentation to directory: /codebuild/...
244 | Traceback (most recent call last):
245 | File "/codebuild/.../mkdocs_awesome_pages_plugin/navigation.py", line 72, in _arrange_items
246 | return arrange(items, meta.arrange, lambda item: basename(self._get_item_path(item)))
247 | File "/codebuild/.../mkdocs_awesome_pages_plugin/arrange.py", line 29, in arrange
248 | raise InvalidArrangeEntry(entry)
249 | mkdocs_awesome_pages_plugin.arrange.InvalidArrangeEntry: Arrange entry "templates" is invalid.

Is this "invalid" because it's conflicting with potential MkDocs templates? Is there a workaround?

Seems like a nice default behaviour would to default the title of a directory in the generated navigation to the title from the directory's index.md file. After all, that seems to be the behaviour for any .md file.

Hello,

Many thanks for maintaining this plugin.
It fills a missing part from mkdocs 👍

However I am facing this issue during install:

pip install mkdocs-awesome-pages-plugin
Collecting mkdocs-awesome-pages-plugin
  Could not find a version that satisfies the requirement mkdocs-awesome-pages-plugin (from versions: )
No matching distribution found for mkdocs-awesome-pages-plugin

Any thoughts?

Cheers!

Hey, great plugin! I wrote my own plugin to conditionally include some .md files according to custom criteria (using the on_files event). Sometimes this logic ends up excluding an entire folder's contents, but the folder is still listed in my "arrange:" config in my .pages for the parent folder, so awesome-pages barfs when it parses my .pages.

The easiest way to fix this, but it's hacky, is to modify the .pages in my plugin temporarily, then restore it post-build. But that's ugly.

Any better way of ignoring empty folders when building the nav tree?

Is there a way to hide (i.e. docs/index.md) from showing up on the tabs?

Hello there,

First of all great work on this plugin, I find it really useful.

I have a usecase where I have a directory that contains release files, named 0.5.0, 0.5.1, etc. It makes sense to me to sort these in reverse order so that the latest release file is at the top of my toctree. There aren't too many files so I can specify the order myself, but I think it would be sweet if I could set a reverse: True parameter instead.

I've seen that a .pages containing hide: true can have the entire directory hidden in the navigation. However, I often would prefer to hide a part of files in a directory. For example with a directory in which I have too many files that would make the navigation list way too long, so we would put a index.md file to well organize them and only have the index.md listed in the navigation while hiding all others.

I hope the plugin could hide all files that are not listed in the nav instead of the whole directory.

Is it possible to prevent the auto capitalisation of folder names and keep the current name as per the folder (- included)

Thanks,

I host a website listing sounds enum names for the SpigotMC project.

Now I want to use Awesome pages to not have to update all pages every time a new update releases, but I encounter a rather strange issue, where the order of the pages in the navigation is completely out of order.

My intended order is:

- Spigot 1.8.x
- Spigot 1.9.x
- Spigot 1.10.x
- Spigot 1.11.x
- Spigot 1.12.x
- Spigot 1.13.x
- Spigot 1.14.x
- Spigot 1.15.x
- Spigot 1.16.x
- Spigot 1.17.x
- Spigot 1.18.x

but the order as of now is

- Spigot 1.10.x
- Spigot 1.11.x
- Spigot 1.12.x
- Spigot 1.13.x
- Spigot 1.14.x
- Spigot 1.15.x
- Spigot 1.16.x
- Spigot 1.17.x
- Spigot 1.18.x
- Spigot 1.8.x
- Spigot 1.9.x

and I'm not sure if this is now caused by awesome pages, the Material theme or even MkDocs itself.

I tried to force awesome pages to put the 1.8 and 1.9 pages before everything else using

nav:
- Spigot Sounds: index.md
- mc-1.8.md
- mc-1.9.md
- ...

but the order stays unaffected. The file names are correct.

Any idea what the issue is and how I could solve it?

Is there any way for me to get the generated navigation as if I was parsing the nav value in mkdocs.yml? Before using this plugin, I was parsing mkdocs.yml in order to generate a matching navigation structure in other parts of our site that were not managed by mkdocs. Is this possible? It looks like maybe I can call AwesomePagesPlugin.on_nav() in some way to get what I want? Not being very familiar with the mkdocs plugin system and this codebase, I'm a little hesitant to guess my way through and possibly have future releases break my hacky logic.

I get this notification now:

lib/python3.6/site-packages/mkdocs_awesome_pages_plugin/meta.py:39:
YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated, as the default Loader is unsafe. 
Please read https://msg.pyyaml.org/load for full details.
  contents = yaml.load(file) or {}

According the wiki. there are two options to migrate:

1. use safe_load instead (backwards-compatible)
2. pass Loader=yaml.FullLoader to load

I'd guess option 1 should be fine.
I can create a PR is requested.

Hi there !

I have just read the issues on @ultrabug's i18n compatibility with awesome-pages from the end of 2021, and from what I read I understood that everything works fine unless there is something unexpected in the mkdocs.yml such as .... Knowing this issue, I decided to go for a .pages file, but I do get 404 errors.

I wasn't sure whether I should put it here or as ultrabug's plugin issue, but I believe I'm doing something wrong with the .pages file, that's why I'm posting here. Would you mind giving it a look plz ?

First of all, I have this project :

mkdocs.yml
docs/
├─ .pages 
├─ index.md
├─ index.fr.md
├─ file2.md
└─ file2.fr.md

With this mkdocs.yml :

site_name: My Docs
theme:
  name: material
  font:
    text: Ubuntu
    code: Ubuntu Mono
  palette:
    scheme: slate
    primary: blue grey
    accent: amber
extra:
  alternate:
    - name: English
      link: ./
      lang: en
    - name: Français
      link: ./fr/
      lang: fr
plugins:
    - search
    - awesome-pages
    - i18n:
        default_language: en
        languages:
          en: english
          fr: français
        nav_translations:
          fr:
            'Welcome': 'Bienvenue'
            'File 2 awesome pages': 'Fichier 2 awesome pages'

This is what my .pages file looks like :

nav:
    - Welcome: index.md
    - File 2 awesome pages: file2.md

While browsing the mkdocs serve, if I change the language from default (english) to french, and try to access one of the pages it outputs a 404 error :

Whereas if I stay in the default language it doesn't :

I also notice that when clicking on a page, the url is /file2.md whereas it should be /fr/file2 : back in the default language instead of staying in the fr part.

Thank you in advance ! 😄

This is a revival of #16, but this time with a reproducible example and a proper analysis of the underlying cause. ;)

I should say upfront that I don't think this is necessarily a bug in awesome-pages itself. Rather, it seems to be an unfortunate interaction between awesome-pages and mktheapidocs. However, I'm interested whether you think there is a way this could be handled in awesome-pages, or whether this requires some additional support in MkDocs itself.

I have created a minimal example to reproduce the issue here. As described there, when used on its own awesome-pages works perfectly fine. It picks up the docs/.pages file and correctly arranges the order of the various sections in the nav bar as specified by the arrange key.

However, when the mktheapidocs plugin is activated (by uncommenting the relevant section in mkdocs.yml), it can't find the docs/.pages file any more and therefore the order of the nav bar sections is wrong.

The underlying cause of the bug is that awesome-pages tries to determine the location of the .pages file by determining the common subdirectory of the nav bar sections (via the helper methods _gather_metadata and _common_dirname in the NavigationMeta class).

In our case this location should be the toplevel docs/ folder. However, since mktheapidocs inserts an additional section "Dummy python module" whose underlying files live outside the docs folder (namely, in the in the directory dummy_python_module), awesome-pages gets confused and can't find the relevant .pages file any more.

I'd love to hear your opinions on how this could be resolved. Do you think there is an easy fix in awesome-pages? Or does this require more fundamental support in MkDocs (for example, to have a direct link from a Section instance to the associated directory on disk; or to be able to determine sections that have been dynamically inserted and/or that act like a "symlink" to a different folder, such as the API docs section for "Dummy python module" in this case)?

Hi,
First of all thank you for creating this amazing extension. so easy and nice to keep order in a otherwise unstructured documentation base.

Im having a issue when using this extension in mkdocs 1.1. It works however with v1.0.4

INFO    -  Building documentation...
Traceback (most recent call last):
  File "C:\Program Files\Python37\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "C:\Program Files\Python37\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\__main__.py", line 199, in <module>
    cli()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\click\core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\click\core.py", line 717, in main
    rv = self.invoke(ctx)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\click\core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\click\core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\click\core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\__main__.py", line 143, in serve_command
    **kwargs
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\commands\serve.py", line 141, in serve
    config = builder()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\commands\serve.py", line 129, in builder
    **kwargs
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\base.py", line 197, in load_config
    errors, warnings = cfg.validate()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\base.py", line 107, in validate
    run_failed, run_warnings = self._validate()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\base.py", line 62, in _validate
    self[key] = config_option.validate(value)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\config_options.py", line 130, in validate
    return self.run_validation(value)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\config_options.py", line 591, in run_validation
    plgins[item] = self.load_plugin(item, cfg)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs\config\config_options.py", line 599, in load_plugin
    Plugin = self.installed_plugins[name].load()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\pkg_resources\__init__.py", line 2443, in load
    return self.resolve()
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\pkg_resources\__init__.py", line 2449, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs_awesome_pages_plugin\plugin.py", line 11, in <module>
    class AwesomePagesPlugin(BasePlugin):
  File "C:\Kildekode\Git\Governance\.github\mkdocsBuild\mkserve\lib\site-packages\mkdocs_awesome_pages_plugin\plugin.py", line 16, in AwesomePagesPlugin
    ('filename', config_options.Type(mkdocs_utils.string_types, default=DEFAULT_META_FILENAME)),
AttributeError: module 'mkdocs.utils' has no attribute 'string_types'

the current pip list is

Package                     Version
--------------------------- -------
beautifulsoup4              4.8.2
Click                       7.0
future                      0.18.2
htmlmin                     0.1.12
Jinja2                      2.10.3
jsmin                       2.2.2
livereload                  2.6.1
lunr                        0.5.6
Markdown                    3.2.1
MarkupSafe                  1.1.1
md-mermaid                  0.1.0
mkdocs                      1.1
mkdocs-autolinks-plugin     0.1.0
mkdocs-awesome-pages-plugin 2.2.0
mkdocs-exclude              1.0.2
mkdocs-macros-plugin        0.3.3
mkdocs-material             4.6.3
mkdocs-mermaid-plugin       0.1.1
mkdocs-minify-plugin        0.2.1
nltk                        3.4.5
pep562                      1.0
pip                         20.0.2
Pygments                    2.5.2
pymdown-extensions          7.0b2
PyYAML                      5.3
repackage                   0.7.3
setuptools                  41.2.0
six                         1.14.0
soupsieve                   1.9.5
termcolor                   1.1.0
tornado                     6.0.3

I classify documents by version number.

but build is failed when arrange entry have only numbers,

failed case

arrange:
    - 1.11-(latest)
    - 1.12
TypeError: Expected "arrange" attribute to be a list of strings - got <class 'list'> 

success case

arrange:
    - 1.11-(latest)
    - 1.12-(develop)

This is related to issue mkdocs/mkdocs#1347

I would like to keep each page in a separate directory that contains a single index.md together with all images used on that page. Here is an example

docs/
docs/section1/page11/index.md (# My Page1 in Section1)
docs/section1/page11/image1.png (used from docs/section1/page11/index.md)
docs/page2/index.md (# My Page2)
docs/page2/image2.png (used from docs/page2/index.md)
docs/index.md (# About)

I would like to see this:

pages:
  - About: index.md
  - My Page2: page2/index.md
  - Section 1:
    - My Page1 in Section1: section1/page11/index.md

Instead, I see the following (unnecessary nesting of page2):

pages:
  - About: index.md
  - Page2:
    - My Page2: page2/index.md
  - Section 1:
    - My Page1 in Section1: section1/page11/index.md

Is there an option to automatically "collapse" sections that have just a single nested page ?

After reading the following:
https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin#arrange-pages

i tried to switch it to nav: but if i do that the build breaks with all kind of errors.

like not showing up or a 404 error.

using now the following in my docs

arrange:
    - index.md
    - dir1
    - dir2
    - dir3
    - dir4
    - dir5
    - dir6

in dir1 i got the following

arrange:
    - index.md
    - dir1
    - dir2

where index.md should be the first landing page when selected

when i change it to nav:
i get a 404 on the docs folder for the home page
and also if i go to dir1

hope i described it good enough
else i will add my actual folder names if needed

Hi, thanks for this cool plugin!

https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/#combine-custom-navigation--file-structure

It looks to me like this does not work on current version (looks like there's a typo on summary.md as well).

If I create:

docs
├── folder
│   ├── introduction.md
│   ├── page3.md
│   └── page4.md
├── introduction.md
├── page1.md
└── page2.md

I get:

TypeError: Invalid nav item format {'Start': ['page1.md', 'page2.md', 'introduction.md']} [/home/alexys/github/mkdocs-awesome-pages-plugin/docs/.pages]

Can you confirm it's a bug or am I missing something please?

awesome-pages is... awesome. But it cannot be successfully used with monorepo and multirepo plugins (and monorepos/multirepos are challenging to manage without those plugins). I decided to bail on the mono/multi-repo plugins and figure out how to make my multiple monorepos (yup, both) work, in the aggregate, with awesome-pages. Turns out that it only took a small shell script to move some files around into the "docs" directory.

And so, with that realization, I can also say that awesome-pages could be altered to work for mono/multi-repos by supporting more path options. The plugin currently only descends into docs_dir, but if .pages could add an option to look in other dirs (and maybe even support deeper paths, e.g. my_dir/nested_dir and not just my_dir), it would work for users handling mono/multi-repos (and, I believe, would also allow people using those other plugins to either ditch them or configure them to allow awesome-pages to work).

Probably something silly, but I'm having problems with this:

INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /builds/docs/sandbox/sandbox-project/site
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 1137, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/__main__.py", line 183, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 279, 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 51, in __init__
    self.items = self._process_children(
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/navigation.py", line 65, in _process_children
    item = self._process_section(item, collapse)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_awesome_pages_plugin/navigation.py", line 127, in _process_section
    meta = self.meta.sections[section]
KeyError: SectionPage(title='About', url='/about/')

Apparently I'm doing something wrong with the setup somewhere?

If this is a thing about MkDocs internal and has no way to address without change to MkDocs, that's OK, I will open a feature request in its repo.

Sections are defined by using the following syntax in mkdocs.yml, which has nothing to do with any subdirectory inside docs

nav:
  - Section1:
    - file1.md
  - Section2:
    - file2.md

The navigation will be rendered like:

Section1
  title of file1.md
Section 2
  title of file2.md

MkDocs doesn't allow specifying directory or using globbing, this is why awesome-plugin comes. With awesome-plugin in use and the following directory structure:

docs/ 
  |__ .pages
  |__ index.md
  |__ section1/
           |__ .pages
           |__ index.md
           |__ section2/
                    |__ .pages
                    |__ index.md
                    |__ ...

docs/.pages contains:

nav:
  - index.md
  - section1

docs/section1/.pages contains:

nav:
  - index.md
  - section2

docs/secton1/section2/.pages contains:

nav:
  - index.md

We only need index files in the navigation, all non-index Markdown files will get linked from inside index files. After build, we get the navigation list like:

title of docs/index.md
Section1
  title of docs/section1/index.md
  Section2
    title of docs/section1/section2/index.md

My feature request is that I don' t need those section markers, it should look like:

title of docs/index.md
  title of docs/section1/index.md
    title of docs/section1/section2/index.md

Why does this feature make sense? Suppose:

• title of docs/index.md is "Chapter1"
• title of docs/section1/index.md is "Section1"
• title of docs/section1/section2/index.md is "Section2"

With those section markers there, it looks like:

Chapter1
  Section1
    Section1
  Section2
    Section2

A bit weird, right? That's why those section markers should be removed. But what if those who don't use index files like this and they really need the section markers for grouping. I think it could be done like:

nav:
  - index.md
  - Section 1:
     - section1

Only if an explicit section is given, then produce that section item in the nav.

Of course, this could be tweaked in theme templates, but I personally think taking subdirectories as section items automatically is a bad idea because you never know how your users want their directory to be handled. Instead of tweaking each theme, it should be addressed inside the navigation generator itself.

Anyway, appreciating for developing this plugin as it really helps!

.pages.arrange is a convenient layout overriding mechanism. It'd be great if you can make it work a little more like the nav directive. e.g.

arrange:
  - Home: README.md
  - Background: background-materials-directory

The first form (<title>: <file.md>) is identical to nav. The second form would save us from having to create a .pages file with a title directive just to override the directory title.

If there is a minus in the title of a markdown file the minus is rendered as a space. I think this makes sense for underscores, because they are not part of natural language. Minus signs however are. Is there any way to configure this?

TL;DR

Best nav plugin, though it's missing ability to specify files with Regex OR Glob pattern.

Everything is just beautiful. One thing though I noticed is it's missing the ability to specify which files to place under a specific section using a regex or glob patterns.

So like the "..." just places anything that hasn't been specified:

nav:
    - section
        - ...

... which is very useful ! But also what would be useful is if you could place specific files under a section based on a regular expression or glob pattern:

nav:
    - Math:
        - 'Math Notes - .+\.md'
        - 'Math Notes - *.md'
    - Physics:
        - 'Physics Notes - .+\.md'
        - 'Physics Notes - *.md'
    - Exams:
        - '**/* Exam - *.md'

Either Regex or Glob patterns, if you can do both even better. I'm not too familiar with what's possible but just an idea: maybe to differentiate what's a regular, regex or glob string, you could do kinda like the python format string and have: nothing/ 'r' / 'g' preprend the string respectively:

nav:
    - Math:
        - 'Math Notes - Calculus.md'
        - r'Math Notes - .+\.md'
        - g'Math Notes - *.md'

Probably just getting ahead of myself. But you get the idea. I think the mkdocs-exclude has an implementation of regex/glob patterns.

If you could make that happen that would be amazing ! And make this the most complete "nav" plugin. Thanks in advance. Very grateful for your plugin. 🎩 s off brother.

Hi,

I can see that by using ... in the mkdocs.yml this allows the navigation tree to be seeded from the .pages files. This is great as it will allow custom documentation to be added to the default.

It is possible to keep these completely separate. For instance can I configure it so that all the custom documentation (including .pages) is loaded from a separate folder?

Thanks

It doesn't matter if I explicitly specify in the .pages the name of the directory or the title I gave, the arrange doesn't work nor does the Set directory name work either. Example of what I am doing

in a directory named Development:
my .pages.yml file has
title: Desarrollo

which doesn't work nor produces any changes.

In another directory which has several subdirectories:

arrange:
- Applications
- Development
- Standards
- About

which doesn't work either.

Hey there, I'm currently looking for a way to have clicking a menu header open to a page in addition to expanding the submenu. Any idea how to best do that?

Example:

-index.md
-category: category.md
  - sub-page: sub-page.md
  - sub-page2: sub-page2.md
- category2: category2.md
  - sub-page: sub-page.md
  - sub-page2: sub-page2.md

Just wondering if it would be possible to allow me to add a set of links to the nav that are not part of the docs file structure. Right now I am linking to API docs that are generated separately from mkdocs and my nav config option has a few links going out to those sub-pages. When using the awesome-pages plugin, removing nav generates links to all my mkdocs pages but adding my external links makes me lose the auto-generated navigation from this plugin.

Seems like Collections doesn't include Iterable, but Collections.abc does (based on this pr I found for same error)

Traceback (most recent call last):
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\nwesterhausen\scoop\apps\python\current\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\click\core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\click\core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\click\core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\click\core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\click\core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\mkdocs\__main__.py", line 173, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, **kwargs)
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\mkdocs\commands\serve.py", line 81, in serve
    server.serve()
...
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\mkdocs_awesome_pages_plugin\plugin.py", line 9, in <module>
    from .meta import DuplicateRestItemError, MetaNavRestItem, RestItemList
  File "C:\Users\nwesterhausen\scoop\apps\python\3.10.0\lib\site-packages\mkdocs_awesome_pages_plugin\meta.py", line 78, in <module>
    class RestItemList(collections.Iterable):
AttributeError: module 'collections' has no attribute 'Iterable'

Additional info:

python --version Python 3.10.0

If I edit mkdocs_awesome_pages_plugin\meta.py to import collections.abc and reference it on line 78 I can run mkdocs build without an issue.

Hey, your Plugin is awesome!

Unfortunately I encountered a small "missing feature" or for me a "bug". So if one of my entries in the arrange-list doesn't exists in the directory, the whole build of the MkDocs is failing.

Could you maybe add a option "strict" or something that is set to "True" in default (for not changing the current logic). If it's set to "False", even if the entry could not be found, there will be just printed a warning instead of raising an exception?

Thanks in advance!

MkDocs 1.0 changed the configuration format and doesn't provide a pre-populated pages (now nav) list anymore (at least not in the on_config hook).

• Use nav property
• Use on_nav event that should provide access to pre-populated pages
• Remove title extraction feature since that's now done properly by MkDocs

Not sure if this would be either out of scope, or even impossible to implement, but how about having a way to generate a TOC inside a page, by using a specific placeholder for it?

Example

The following structure is present:

docs/
├ index.md
├ assets/
│  ├ css/ # Some CSS assets
│  │  └ ...
│  └ img/ # Some images
│     └ ...
└ posts/
   ├ index.md # Content shown below
   ├ post1.md
   ├ post2.md
   └ archive/
      └ post3.md

I now set up a .pages.yml file in assets to ignore the folder and one in posts with the following structure:

title: Posts
nav:
- My Posts: index.md
- ...

Finally, do I add the following to my index.md:

# My Posts
Below can you find a list of all posts I made so far.

## Pages
{nav} <!-- Just an example. Not sure how the placeholder should look like -->

The {nav} placeholder would now take all pages it can find in the posts directory and also go through any additional directories found there. It will however skip the file it is used in.

Once it has all pages, will it generate a list that could look like this:

# My Posts
Below can you find a list of all posts I made so far.

## Pages
- [Post1](post1.md)
- [Post2](post2.md)
- [Archived](archive)
  - [Post3](archive/post3.md)

It would take the names to display from either the nav-section in the .pages file, or from the pages themself.

Why?

This plugin is useful for when you want to have the nav updated without needing to always set it yourself, but won't obviously work for when you have a manual nav inside a specific file.

For me is that the case with a blog I have. While I no longer need to update the nav myself do I always have to update the list in the index.md of my posts directory, which is frustrating sometimes.

Having a way to automate this using a placeholder or similar would really help a lot.

I hope this is somewhat doable.

Hi, I've been using awesome-pages for a while now, but only with material docs v4.
I tried upgrading to v7 but even the latest awesome-pages does not render out like the old way. Is there something wrong with my config or is this a clash with material docs.

What's interesting is that the ordering is actually still working

.pages

nav:
  - index.md
  - ...
  - contributing.md

Old material docs

new

all links are tabs now

mkdocs==1.1.2
mkdocs-awesome-pages-plugin==2.5.0
mkdocs-git-revision-date-plugin==0.3.1
mkdocs-material==7.0.6
mkdocs-material-extensions==1.0.1

This plugin currently only supports sorting by the filename of the page. When pages using a different visible title however, the resulting sort will appear incorrect. It would be nice to have an option where we can sort by the title instead of the page name.

I know you've mentioned that awesome-pages doesn't work so well with nav but this seems like a bug for sure.

Here is my directory structure:

and here is the nav section of my mkdocs.yml:

all of which results in the following while on the "Professional Experience" tab:

but the following while on the "About me" tab:

.pages

nav:
    - ...
    - "section 1" :
        - changelog.md

When i do mkdocs serve:

Traceback (most recent call last):
  File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.9_3.9.2800.0_x64__qbz5n2kfra8p0\lib\runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.9_3.9.2800.0_x64__qbz5n2kfra8p0\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\click\core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\click\core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\click\core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\click\core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\click\core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs\__main__.py", line 177, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, **kwargs)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs\commands\serve.py", line 54, in serve
    config = builder()
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs\commands\serve.py", line 49, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs\commands\build.py", line 287, in build
    nav = config['plugins'].run_event('nav', nav, config=config, files=files)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs\plugins.py", line 102, in run_event
    result = method(item, **kwargs)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs_awesome_pages_plugin\plugin.py", line 55, in on_nav       
    return AwesomeNavigation(nav.items, Options(**self.config), config['docs_dir'], explicit_sections).to_mkdocs()
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs_awesome_pages_plugin\navigation.py", line 43, in __init__ 
    self.meta = NavigationMeta(items, options, docs_dir, explicit_sections)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\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 "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs_awesome_pages_plugin\meta.py", line 137, in try_load_from 
    return Meta.load_from(path)
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs_awesome_pages_plugin\meta.py", line 181, in load_from     
    nav = [MetaNavItem.from_yaml(item, path) for item in nav]
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\mkdocs_awesome_pages_plugin\meta.py", line 181, in <listcomp>    
    nav = [MetaNavItem.from_yaml(item, path) for item in nav]
  File "C:\Users\Andzejs\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\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 {'section 1': ['changelog.md']} [E:\VBA_PROJECTS\DEL_HelpDocs\del-docs-gitter\docs\.pages]

What am i doing wrong?

Love the plugin—it was probably the killer feature that persuaded us to migrate our docs to mkdocs from Jekyll, as it was so simple for a contributor to add a page to the navigation.

I recently migrated the pages files to replace arrange: with nav: as I spotted it was a deprecated syntax but failed to spot the change in functionality 🤦🏻‍♂️. I’ve just worked out (after spotting #20) why some pages weren’t showing, and now understand how to fix that.

However, I’m worried that our contributors won’t understand that when they add a page to a folder with a .pages file (or when they create a .pages file) that they need to specify explicitly where unmentioned items should sit. They aren’t familiar with how mkdocs and it’s plugins work, as we encourage all engineers across the organisation to contribute to the site.

We never really want to hide pages in the navigation, and I’m conscious that the next major release will remove arrange: support, so I wondered if it would be possible to add plugin configuration to be able to disable this part of the nav: functionality? I think it will save people some head-scratching in the future for sites like ours.

Thanks!

Hi, i want disable pages o directory to scan and display, it is possible?

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?

The readme doc said to create YAML file named .pages , so I tried create '.pages.yml'...... I think it may also misleading other people..

Hi
I had a project working 4 days ago (Building without any problems)
But now, every time I try to build I get this error
mkdocs_awesome_pages_plugin.factory.PageNotFoundError: Page "index.md" not found. [.pages]

with recent update of mkdocs, the plugin crashes if there is no pages config

File "c:\hostedtoolcache\windows\python\3.6.4\x64\lib\site-packages\mkdocs_awesome_pages_plugin\plugin.py", line 24, in on_config
     pages = Factory(options).create(config['pages'])
File "c:\hostedtoolcache\windows\python\3.6.4\x64\lib\site-packages\mkdocs_awesome_pages_plugin\factory.py", line 34, in create
     children = self._create_pages(config)
File "c:\hostedtoolcache\windows\python\3.6.4\x64\lib\site-packages\mkdocs_awesome_pages_plugin\factory.py", line 64, in _create_pages
     return [self.create_page(c) for c in config]

TypeError: 'NoneType' object is not iterable