Best "nav" plugin but Please have Regex/Glob patterns to specify files !

[akharrou]

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.

[lukasgeiter]

That's an interesting idea. I'll see what I can do...

[lukasgeiter]

Alright, so I did some thinking and prototyping. It should definitely be possible to add such a feature. I'm now trying to figure out how exactly it should behave - especially when patterns overlap.

Consider this example:

docs/
├─ foo-a.md
├─ foo-b.md
├─ bar-a.md
└─ bar-b.md

nav:
  - Foo
    - foo-*.md
  - A
    - *-a.md

The patterns both match foo-a.md. Should the output include the item twice like this:

• Foo
  • foo-a
  • foo-b
• A
  • foo-a
  • bar-a

Or only once (whereas the first match takes precedence):

• Foo
  • foo-a
  • foo-b
• A
  • bar-a

---

Then there's also the question of what happens if an item matched by the pattern is also explicitly listed in the config.

nav:
  - foo-a.md
  - foo-*.md

Should foo-a now show up twice?

---

I think the best solution is to think of this feature as an extension of .... Kind of like ... but with a filter. That way it would be clear that the patterns are only checked against pages that are not specified explicitly.

It might also help to use a similar syntax. For example:

nav:
  - Foo
    - ...|foo-*.md
  - A
    - ...|*-a.md

However, I'm still unsure if it would make sense to allow for duplicates if patterns overlap or not.

---

I would really appreciate your opinion on these points. Thanks!

[akharrou]

TL;DR

Order of precedence:

• Explicit file names > Patterns > "..." (the rest)

There should never be double inclusion of a file. Explicitly including more than once and overlapping patterns should be resolved in the manner of your first suggestion: files specified/matched that come before in the nav have precedence over those that come later in the nav; the former should be included, in the section they are found in, whilst the later should be ignored.

---

Concerning the order of precedence, it would seem to me that the following order makes the most sense:

1. Explicit file names

   • Explicit filenames above overrule explicit filenames below
   • Explicit filenames always overrule patterns
   • Explicit filenames always overrule "..."

2. Patterns

   • Pattern matches above overrule pattern matches below

   • Pattern matches always overrule "..."

     The way I see it is that, it should be up to the user to:

     1. have a naming scheme that is reasonably matchable such that there are no overlaps

     2. have precise enough patterns such that there are no overlaps; this is trivial with regex

        

3. "..."

   • This catch-all-thats-left-pattern, so to speak, should be last to take effect regardless of where it is placed in the nav, nothing should ever be re-included.

---

It can be understood as: whatever takes more effort (to type) is in other words bringing more emphasis to the table, that this is how I want things to be and not any other way.

Also if you think about it, the user, with naming schemes and regex patterns, has an infinite amount of possibilities to arrive at his desired goal of including files and not others, you as the implementor on the other hand only have a few and cannot satisfy everyone at the same time.

With regex patterns a user can be as specific or as vague as he wants to, so as to include precisely desired files and omit those he doesn't. With good regex patterns overlaps should literally never arise, even with the dumbest naming schemes; and if it does, its either the regex pattern that's lacking specificity or the naming scheme that's not good enough.

This also goes for glob patterns even though they are indeed less flexible than regex, in fact I only see glob patterns being used for very simple naming schemes. And if the user still can't figure it out, he can always fallback to explicitly naming his files.

---

Concerning the patterns as an extension of "...", I see what you're saying, if you want to implement it that way it would be fine, the only thing I would say is that in my opinion it would be a cleaner and more familiar syntax to just leave regex/glob patterns separate. Also I kind of see the "..." as a nice, clean and conveniant complementary "catch-all-thats-left" pattern.

[lukasgeiter]

Thanks for your detailed answer. I'm glad to see you agree with me on the direction of this feature. However, there are two parts of your comment I want to address:

Duplicate Filenames

There's one thing I don't agree with in your order of precedence list:

Explicit filenames above overrule explicit filenames below

MkDocs allows you to explicitly list the same file twice and will render it twice in the navigation. This somewhat breaks the highlighting of active menu entries (at least in mkdocs-material) but it still displays the item. I'm not planning t0 change this behavior.

Extension of ...

My goal is to make it very easy to understand how this feature works. Most importantly which files are checked against the pattern - because I think that's not necessarily obvious.

I would say is that in my opinion it would be a cleaner and more familiar syntax to just leave regex/glob patterns separate

The familiar syntax might actually lead to users misunderstanding how the feature works. Let me try to explain what I mean.

The config currently allows two types of entries: files and ... (excluding sections since they are not relevant for this). If a user now sees the entry foo-*.md they might think of it as just an easier way to list many files. Which would imply that the pattern just gets expanded into a list of file entries, which would not take in to account if any of the pages already appear in the config elsewhere.

Furthermore, if a pattern matches a file that's not even part of the navigation tree (e.g. because of mkdocs-exclude) a user would probably expect it to show up.

So I want to make it as clear as possible that the feature operates on the autogenerated navigation tree excluding any pages that are explicitly listed. This set of pages is already represented by ... so I believe it would make sense to present this feature as an extension of ....

[akharrou]

Alright man, sounds good to me, go for it. 👍🏼 And yeah, I totally forgot that Mkdocs does allow explicit listing of files more than once.

[akharrou]

Hey Lukas ! How are things coming along ?

[lukasgeiter]

Hey! I'm sorry, I've been busy with other things. I don't want to promise anything, but I'll try to finish it up this weekend. I'll let you know once the release is out.

[lukasgeiter]

I've just released version 2.5.0 with this feature. The syntax I settled on is ... | foo-*.md (or ... | glob=foo-*.md) for glob patterns and ... | regex=foo-[0-9]+.md for regex. You can find all details in the updated README.

[ojacques]

@lukasgeiter - I just wanted to send over a million thanks 🙏🙏🙏 for this feature.

This allows for example to hide specific files from the navigation:

nav:
    # Show everything except template<something> files
    - ... | regex=^(?!template).*$

I do have template.md files which I don't want to show in navigation, but still want to generate and refer to. Perfect!