apenwarr / mkdocs-exclude

A mkdocs plugin that lets you exclude files or trees from your output.
Apache License 2.0
86 stars 10 forks source link

include nav changes in the exclude filter? #1

Closed DutchessNicole closed 5 years ago

DutchessNicole commented 5 years ago

Currently, the plugin correcly globs the directories that I want excluded from a build. Would it also be possible to have it exclude those same patterns from the nav section?

For instance, say I have a yaml like so:

nav:
  path_a: 
    file1: path_a/file.md
    file2: path_a/file2.md
  path_b:
    file3: path_b/file.md
    file4: path_b/file2.md

with the associated exclude mapping

exclude:
  - glob:
      - path_b*

Then the plugin will correctly filter out the actual path items, but it will still leave the navigation menu intact.

Ideally any paths that also match the patterns in the nav section (and their parents, if they end up being empty) would also be removed.

This way we don't end up with a menu full of dangling links to files that don't exist.

Thanks for the plugin!

apenwarr commented 5 years ago

Hi, I see what you mean but I'm not sure that's a good idea. Since you're already editing the mkdocs.yml to add exclude: entries, why not just remove the unwanted entries from the nav: section? It seems like if we implemented the feature you're requesting, it would result in a very misleading mkdocs.yml where the nav: section talks about files that don't exist.

DutchessNicole commented 5 years ago

The nav: section wouldn't actually be edited I don't think.

Rather the filter would simply also affect the items in it in the same way that the actual files are filtered.

The reason for this is that I have a CI system running at the moment, where I want to build the same code base twice: once with a certain category visible and available, and once where that category (represented by a file glob) is not present in the build.

However if the files are not there (because they are filtered out of the build) but the navigation still points to them, that is untidy.

An alternative would be to check whether the exclude patterns are there and then run a bash script or something to filter out the yaml corresponding to the filters. I could do that.

However, it seems more logical to have the plugin take care of both the file exclusion as well as the associated, now no-longer useful navigation items.

Remember, I don't mean that we edit the mkdocs.yaml, merely that we apply the same filters to the nav: section that are applied to the files themselves at build time only

apenwarr commented 5 years ago

The thing is, you are either manually or automatically producing a mkdocs.yml that says "here's a navbar that contains X; exclude X." That doesn't sound like a good idea. If you are manually editing mkdocs.yml to add the excludes, you can manually edit the navbar too. If you are running a script that automatically adds the excludes, you can have it automatically edit the navbar at the same time.

Inconsistent config files (which claim one thing, ie. a navbar for X, but then do something else) eventually turn into some future developer's debugging nightmare.

DutchessNicole commented 5 years ago

I don't automatically create the mkdocs.yml It's pretty much set once and only the actual docs are updated.

Our developers are creating documents, for which each needs a nav entry, yes. But once the files are there their location is unlikely to change.

Basically as I see it, right now files are being excluded from the build while their links are left dangling. That to me doesn't make sense.

Perhaps this is a difference in perspective. I'd rather have the complete set of nav structures, and take away the parts I don't need, rather than create a subset of whatever documents there are and turn them into a structure dynamically.

I'd like for the mkdocs.yml to be as static as possible.

apenwarr commented 5 years ago

Presumably if you have multiple variants of your build, which have different settings for the mkdocs-exclude plugin, then you must have different mkdocs.yml files for each variant, right?