An MkDocs plugin that simplifies configuring page titles and their order

Lukas Geiter

Last update: Dec 28, 2022

Related tags

Overview

MkDocs Awesome Pages Plugin

An MkDocs plugin that simplifies configuring page titles and their order

The awesome-pages plugin allows you to customize how your pages show up the navigation of your MkDocs without having to configure the full structure in your mkdocs.yml. It gives you detailed control using a small configuration file directly placed in the relevant directory of your documentation.

Note: This plugin won't do anything if your mkdocs.yml defines a nav or pages entry. To make use of the features listed below, you'll either have to remove the entry completely or add a ... entry to it.

Installation

Note: This package requires Python >=3.5 and MkDocs version 1.0 or higher.
If you're still on MkDocs 0.17 use version 1 of this plugin.

Install the package with pip:

pip install mkdocs-awesome-pages-plugin

Enable the plugin in your mkdocs.yml:

plugins:
    - search
    - awesome-pages

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

More information about plugins in the MkDocs documentation

Features

Customize Navigation

Create a YAML file named .pages in a directory and use the nav attribute to customize the navigation on that level. List the files and subdirectories in the order that they should appear in the navigation.

nav:
    - subdirectory
    - page1.md
    - page2.md

Rest

Pages or sections that are not mentioned in the list will not appear in the navigation. However, you may include a ... entry to specify where all remaining items should be inserted.

nav:
    - introduction.md
    - ...
    - summary.md

Furthermore, it is possible to filter the remaining items using glob patterns or regular expressions. For example to match only the Markdown files starting with introduction-.

nav:
    - ... | introduction-*.md
    - ...
    - summary.md

Note: The pattern is checked against the basename (folder- / filename) of remaining items - not their whole path.

For more details refer to the Rest Filter Patterns section below.

Titles

You can optionally specify a title for the navigation entry.

nav:
    - ...
    - First page: page1.md

Note: Specifying a title for a directory containing a .pages file that defines a title has no effect.

Links

You can also use the nav attribute to add additional links to the navigation.

nav:
    - ...
    - Link Title: https://lukasgeiter.com

Change Sort Order

Create a YAML file named .pages in a directory and set the order attribute to asc or desc to change the order of navigation items.

order: desc

Note: Unlike the default order, this does not distinguish between files and directories. Therefore pages and sections might get mixed.

Collapse Single Nested Pages

Note: This feature is disabled by default. More on how to use it below

If you have directories that only contain a single page, awesome-pages can "collapse" them, so the folder doesn't show up in the navigation.

For example if you have the following file structure:

docs/
├─ section1/
│  ├─ img/
│  │  ├─ image1.png
│  │  └─ image2.png
│  └─ index.md # Section 1
└─ section2/
   └─ index.md # Section 2

The pages will appear in your navigation at the root level:

Section 1
Section 2

Instead of how MkDocs would display them by default:

Section 1
- Index
Section 2
- Index

For all pages

Collapsing can be enabled globally using the collapse_single_pages option in mkdocs.yml

For a sub-section

If you only want to collapse certain pages, create a YAML file called .pages in the directory and set collapse_single_pages to true:

collapse_single_pages: true

You may also enable collapsing globally using the plugin option and then use the .pages file to prevent certain sub-sections from being collapsed by setting collapse_single_pages to false.

Note: This feature works recursively. That means it will also collapse multiple levels of single pages.

For a single page

If you want to enable or disable collapsing of a single page, without applying the setting recursively, create a YAML file called .pages in the directory and set collapse to true or false:

collapse: true

Hide Directory

Create a YAML file named .pages in a directory and set the hide attribute to true to hide the directory, including all sub-pages and sub-sections, from the navigation:

hide: true

Note: This option only hides the section from the navigation. It will still be included in the build and can be accessed under its URL.

Set Directory Title

Create a YAML file named .pages in a directory and set the title to override the title of that directory in the navigation:

title: Page Title

Arrange Pages

Deprecated: arrange will be removed in the next major release - Use nav instead.

Create a YAML file named .pages in a directory and set the arrange attribute to change the order of how child pages appear in the navigation. This works for actual pages as well as subdirectories.

title: Page Title
arrange:
    - page1.md
    - page2.md
    - subdirectory

If you only specify some pages, they will be positioned at the beginning, followed by the other pages in their original order.

You may also include a ... entry at some position to specify where the rest of the pages should be inserted:

arrange:
    - introduction.md
    - ...
    - summary.md

In this example introduction.md is positioned at the beginning, summary.md at the end, and any other pages in between.

Combine Custom Navigation & File Structure

MkDocs gives you two ways to define the structure of your navigation. Either create a custom navigation manually in mkdocs.yml or use the file structure to generate the navigation. This feature makes it possible to combine both methods. Allowing you to manually define parts of your navigation without having to list all files.

Note: You can freely combine this with all the other features of this plugin. However they will only affect the part of the navigation that is not defined manually.

Use the nav entry in mkdocs.yml to define the custom part of your navigation. Include a ... entry where you want the navigation tree of all remaining pages to be inserted.

The following examples are based on this file structure:

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

If you wanted introduction.md, page1.md and page2.md to appear under their own section you could do this:

nav:
    - Start:
        - page1.md
        - page2.md
        - summary.md
    - ...

Which would result in the following navigation:

Start
- Introduction
- Page 1
- Page 2
Folder
- Introduction
- Page 3
- Page 4

The ... entry can also be placed at a deeper level:

nav:
    - page1.md
    - Rest:
        - ...

Which would result in the following navigation:

Page 1
Rest
- Introduction
- Page 2
- Folder
  - Introduction
  - Page 3
  - Page 4

Furthermore, it is possible to filter the remaining items using glob patterns or regular expressions. For example to match only files named introduction.md.

nav:
    - Introductions:
        - ... | **/introduction.md
    - ...

With the following result:

Introductions
- Introduction
- Introduction
Page 1
Page 2
Folder
- Page 3
- Page 4

Note: The pattern is checked against the path relative to the docs directory.

For more details refer to the Rest Filter Patterns section below.

Rest Filter Patterns

In all places where the rest entry (...) is allowed, you can also include a glob pattern or regular expression to filter the items to be displayed.

nav:
    - ... | page-*.md
    - ... | regex=page-[0-9]+.md

The filter only operates on remaining items. This means it will not include items that are explicitly listed in the navigation or items that are matched by another filter that appears earlier in the configuration.

You may also include a rest entry without filter to act as a catch-all, inserting everything that is not matched by a filter.

Syntax Details

Unless the filter starts with regex= it is interpreted as glob pattern, however you may also explicitly say so using glob=. The spaces around ... are optional but recommended for readability.

Note: Depending on the characters in your filter, you might also need to use quotes around the whole entry.

nav:
    # equivalent glob entries
    - ... | page-*.md
    - ... | glob=page-*.md
    - ...|page-*.md
    - '... | page-*.md'

    # equivalent regex entries
    - ... | regex=page-[0-9]+.md
    - ...|regex=page-[0-9]+.md
    - '... | regex=page-[0-9]+.md'

Options

You may customize the plugin by passing options in mkdocs.yml:

plugins:
    - awesome-pages:
        filename: .index
        collapse_single_pages: true
        strict: false

`filename`

Name of the file used to configure pages of a directory. Default is .pages

`collapse_single_pages`

Enable the collapsing of single nested pages. Default is false

`strict`

Raise errors instead of warnings when:

arrange entries cannot be found
nav entries cannot be found

Default is true

Contributing

From reporting a bug to submitting a pull request: every contribution is appreciated and welcome. Report bugs, ask questions and request features using Github issues. If you want to contribute to the code of this project, please read the Contribution Guidelines.

Comments

Feature request: do not render subdirectory as section
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!
enhancement
opened by madjxatw 15
Idea: Option to generate TOC in pages using placeholder?
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} 

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.
opened by Andre601 14

Add natural sorting

Natural sorting is important for documents that have file names that are numbered.

Take for example

>>> items
['3000.', '4.']
>>> print(sorted(items))
['3000.', '4.']
>>> print(os_sorted(items, key = lambda i: i,reverse = False))
['4.', '3000.']
>>>

opened by rkk1995 12

Arrange entry "templates" is invalid

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?

opened by connerxyz 10

Best "nav" plugin but Please have Regex/Glob patterns to specify files !
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.
enhancement
opened by akharrou 9
Awesome pages doesn't respect specified file order over `...` pattern
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?
opened by Andre601 8
Allow sections to be configured in `nav`
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 - ...
enhancement
opened by athal7 8
Exclude Files from rendering when they are not in .pages file and no "..." is given
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.
enhancement
opened by alexander-matthiesen 7

Grouping of Rest items is not working

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?

enhancement

opened by ThuF 6

Hide entire menu with an `hide-menu: true` setting in .pages file

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.
enhancement

opened by kleinen 6

Some issues during install

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!

opened by AdrienFromToulouse 6

Feature request : Standalone Navigation for sub sections

docs
|______ index.md
|______ subdir/
              |_____ index.md
              |_____ subsubdir/
                           |_____ index.md
                           |_____ ....
|______ Teachings/
              |_____ .pages
              |_____ index.md
              |_____ CoursTAI/
                           |_____ .pages
                           |_____ index.md
                           |_____ ....
                           |_____ subsubdir222/
              |_____ SQL/
                           |_____ .pages
                           |_____ index.md
                           |_____ ....
                           |_____ subsubdir222/
                                       |_____ index.md
                                       |_____ ....

What I am trying to achieve : I want to create a sub-directory with it's own navigation that doesn't show other upper section navigation

In example: The navigation for CoursTAI should only include all pages under CoursTAI Teaching and SQL should not be visible

enhancement

opened by Noobzik 2

Feature Request: multiple root directories

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).

opened by rplotkin 3
Default title to directory/index.md

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.

opened by mikew 1
awesome-pages and i18n compatibility using .pages
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 ! 😄
bug
opened by Argald0 3
Allow sorting by page title instead of filename

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.
enhancement

opened by ekoleda-codaio 0
[FR] Extend "flat" to also work with dirs
The new flat feature is great, but unfortunately it has some limitations:

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.

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.
opened by jaklan 4

Releases(v2.8.0)

v2.8.0(Jul 24, 2022)
Features

Support for natural sorting with sort_type: natural

Source code(tar.gz)
Source code(zip)
v2.7.0(Feb 12, 2022)
Features

Items can now be grouped into sections

Source code(tar.gz)
Source code(zip)
v2.6.1(Nov 22, 2021)
Improvements

Add warning if preceding plugins define a on_nav listener that might get overridden

Bugfixes

Restrict mkdocs.yml nav workaround to cases where it's necessary

Source code(tar.gz)
Source code(zip)
v2.6.0(Oct 19, 2021)
Features

Remaining pages can now be flattened by adding | flat to the ... entry.

Source code(tar.gz)
Source code(zip)
v2.5.1(Oct 14, 2021)
Bugfixes

Fix collections import (Python 3.10) #49

Source code(tar.gz)
Source code(zip)
v2.5.0(Dec 22, 2020)
Features

Remaining pages can now be filtered by adding a glob pattern or regex to the ... entry.

Source code(tar.gz)
Source code(zip)
v2.4.0(Oct 14, 2020)
Features

The ... entry is now supported in nav of mkdocs.yml as well Interoperability with nav has been improved in general. The plugin now leaves manually defined navigation sections untouched.

Source code(tar.gz)
Source code(zip)
v2.3.1(Oct 3, 2020)
Bugfixes

Fix compatibility issue with mktheapidocs #17

Source code(tar.gz)
Source code(zip)
v2.3.0(Sep 30, 2020)
Features

More powerful navigation customization using nav

Hide navigation entries

Override titles

Add links

Change the sort order using order

Deprecations

The arrange attribute is now deprecated in favor of nav and will be removed in the next major release.

Source code(tar.gz)
Source code(zip)
v2.2.1(Feb 24, 2020)
Bugfixes

Make plugin compatible with MkDocs 1.1 #18

Source code(tar.gz)
Source code(zip)
v2.2.0(Dec 6, 2019)
Features

New strict option which can be set to false to receive warnings instead of errors when arrange entries cannot be found.

Source code(tar.gz)
Source code(zip)
v2.1.0(May 3, 2019)
Features

Hide directories in the navigation using the new hide attribute

Source code(tar.gz)
Source code(zip)
v2.0.1(Mar 14, 2019)
Bugfixes

Use yaml.safe_load instead of yaml.load #8

Source code(tar.gz)
Source code(zip)
v2.0.0(Sep 22, 2018)
Features

Support for MkDocs 1.0 If you're still on MkDocs 0.17 use version 1 of this plugin.

Breaking Changes

The disable_auto_arrange_index plugin option has been removed MkDocs 1.0 includes this feature out-of-the-box, therefore it has been removed from the plugin entirely

Notes

Two features have been removed because MkDocs 1.0 implements them out-of-the-box:

Extracting page titles from Markdown

Displaying index pages at the top

Source code(tar.gz)
Source code(zip)
v1.2.2(Sep 22, 2018)

This release doesn't contain any real changes, it just adjusts the MkDocs version requirement. Version 1 of the plugin is only compatible with MkDocs 0.17. For MkDocs 1.0 use the latest version of the plugin.
Source code(tar.gz)
Source code(zip)
v1.2.1(Sep 22, 2018)
Bugfixes

Prevent error when using with MkDocs 1.0 In this version the plugin doesn't properly work with MkDocs 1.0, use the latest version instead

Source code(tar.gz)
Source code(zip)
v1.2.0(Mar 2, 2018)
Improvements

Collapsing single pages can be configured in the .pages file and allow to use the feature selectively

Source code(tar.gz)
Source code(zip)
v1.1.2(Feb 10, 2018)
Bugfixes

Use UTF-8 encoding when reading files #2

Source code(tar.gz)
Source code(zip)
v1.1.1(Feb 7, 2018)
Bugfixes

Disable collapsing of nested single pages by default This is not technically a bugfix but the feature can lead to unwanted results in many cases so it needs to be enabled explicitly with the collapse_single_pages option

Source code(tar.gz)
Source code(zip)
v1.1.0(Feb 7, 2018)
Features

Collapse single nested pages

Source code(tar.gz)
Source code(zip)
v1.0.0(Feb 7, 2018)

Initial public release of the MkDocs Awesome Pages Plugin
Source code(tar.gz)
Source code(zip)

Owner

Lukas Geiter

GitHub

MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

48 Jan 6, 2023

MkDocs Plugin allowing your visitors to File > Print > Save as PDF the entire site.

mkdocs-print-site-plugin MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF th

67 Jan 4, 2023

A Material Design theme for MkDocs

A Material Design theme for MkDocs Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commerci

12.3k Jan 4, 2023

:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

1.1k Dec 31, 2022

Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

198 Jan 3, 2023

A tool that allows for versioning sites built with mkdocs

mkdocs-versioning mkdocs-versioning is a plugin for mkdocs, a tool designed to create static websites usually for generating project documentation. mk

38 Feb 26, 2022

:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

1.1k Jan 4, 2023

Yet Another MkDocs Parser

yamp Motivation You want to document your project. You make an effort and write docstrings. You try Sphinx. You think it sucks and it's slow -- I did.

10 May 20, 2022

Dev Centric Tools for Mkdocs Based Documentation

docutools MkDocs Documentation Tools For Developers This repo is providing a set of plugins for mkdocs material compatible documentation. It is meant

14 Sep 10, 2022

Mkdocs obsidian publish - Publish your obsidian vault through a python script

Mkdocs Obsidian Mkdocs Obsidian is an association between a python script and a

49 Jan 9, 2023

Plugins for MkDocs.

Plugins for MkDocs and Python Markdown pip install neoteroi-mkdocs This package includes the following plugins and extensions: Name Description Type m

35 Dec 23, 2022

An ongoing curated list of OS X best applications, libraries, frameworks and tools to help developers set up their macOS Laptop.

macOS Development Setup Welcome to MacOS Local Development & Setup. An ongoing curated list of OS X best applications, libraries, frameworks and tools

3 Apr 3, 2022

An MkDocs plugin that simplifies configuring page titles and their order

Related tags

Overview

MkDocs Awesome Pages Plugin

Installation

Features

Customize Navigation

Rest

Titles

Links

Change Sort Order

Collapse Single Nested Pages

For all pages

For a sub-section

For a single page

Hide Directory

Set Directory Title

Arrange Pages

Combine Custom Navigation & File Structure

Rest Filter Patterns

Syntax Details

Options

filename

collapse_single_pages

strict

Contributing

Comments

Example

Why?

Releases(v2.8.0)

v2.8.0(Jul 24, 2022)

Features

v2.7.0(Feb 12, 2022)

Features

v2.6.1(Nov 22, 2021)

Improvements

Bugfixes

v2.6.0(Oct 19, 2021)

Features

v2.5.1(Oct 14, 2021)

Bugfixes

v2.5.0(Dec 22, 2020)

Features

v2.4.0(Oct 14, 2020)

Features

v2.3.1(Oct 3, 2020)

Bugfixes

v2.3.0(Sep 30, 2020)

Features

Deprecations

v2.2.1(Feb 24, 2020)

Bugfixes

v2.2.0(Dec 6, 2019)

Features

v2.1.0(May 3, 2019)

Features

v2.0.1(Mar 14, 2019)

Bugfixes

v2.0.0(Sep 22, 2018)

Features

Breaking Changes

Notes

v1.2.2(Sep 22, 2018)

v1.2.1(Sep 22, 2018)

Bugfixes

v1.2.0(Mar 2, 2018)

Improvements

v1.1.2(Feb 10, 2018)

Bugfixes

v1.1.1(Feb 7, 2018)

Bugfixes

v1.1.0(Feb 7, 2018)

Features

v1.0.0(Feb 7, 2018)

Owner

Lukas Geiter

MkDocs plugin for setting revision date from git per markdown file

MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

A Material Design theme for MkDocs

:blue_book: Automatic documentation from sources, for MkDocs.

`filename`

`collapse_single_pages`

`strict`

MkDocs Plugin allowing your visitors to File > Print > Save as PDF the entire site.