When we want to organize docs pages in subdirectories (paths), mkdocs doesn't have a built-in way of defining directories that a set of pages should live under, and instead you have to specify the entire path to each .md file in mkdocs.yml, e.g.:
- Running cohort queries:
- Search the public nodes: "user_guide/public_nodes.md"
- How to use the query tool: "user_guide/query_tool.md"
- Querying the API directly: "user_guide/api.md"
This quickly gets tedious if you have a lot of docs pages or want a slightly more nested docs structure.
The awesome-pages plugin (the top navigation plugin for mkdocs, see https://github.com/mkdocs/catalog?tab=readme-ov-file#-navigation--page-building) helps solve this problem by allowing you to define the docs structure in a .pages file in your docs directory instead of mkdocs.yml. Here you can specify the name / order / etc. of both files and directories, using the same nav attribute (by default, it should include all files in a directory you specify).
If desired, you can then use .pages in a subdirectory to control the order/names of files in just those subdirectory.
This could make it more intuitive to organize the docs, as each directory could have its own .pages, and also minimizes repetition.
Description
When we want to organize docs pages in subdirectories (paths), mkdocs doesn't have a built-in way of defining directories that a set of pages should live under, and instead you have to specify the entire path to each
.mdfile inmkdocs.yml, e.g.:This quickly gets tedious if you have a lot of docs pages or want a slightly more nested docs structure.
The
awesome-pagesplugin (the top navigation plugin for mkdocs, see https://github.com/mkdocs/catalog?tab=readme-ov-file#-navigation--page-building) helps solve this problem by allowing you to define the docs structure in a.pagesfile in your docs directory instead ofmkdocs.yml. Here you can specify the name / order / etc. of both files and directories, using the samenavattribute (by default, it should include all files in a directory you specify).If desired, you can then use
.pagesin a subdirectory to control the order/names of files in just those subdirectory.This could make it more intuitive to organize the docs, as each directory could have its own .pages, and also minimizes repetition.
Relevant documentation pages
No response
Additional details
No response