Is it possible to hide a single file from nav?

[madjxatw]

I see that hide: true could hide a directory from the navigation, but is there any simple way to hide a single file? The regex syntax might be used to filter out a file with a specific name, but I couldn't find an example. Please advice, thanks.

[lukasgeiter]

Not really. The regex might be able to do the trick, but it's not what it was designed for. Can you describe your use-case for hiding a single file?

[madjxatw]

I have some extra documents as supplementary readings, they do not and should not belong to the docs of my project. I only want to reference them from a Markdown file using the Markdown link syntax [](), so I need to make them part of the site but not directly navigable.

I might hide more files and expect a mechanism that works in the similar way as .gitignore where I could simply prefix a symbol (e.g. !) to ignore a file. I am not sure if this feature could be implemented by a plugin, maybe it is not possible due to the limitation of mkdocs itself.

[VladimirFokow]

@madjxatw
Here's an example that I used to put the 'Home' tab first, and then everything else (except for the top-level index.md file):

nav:
  - ... | home/**  # first in the nav order is the 'Home' tab
  - ... | regex=^(?!index\.md$).*  # then, all paths that are not exactly "index.md" of the root

But for your use-case, why can't you put all the files you want to hide into a directory and then just hide this directory?

[madjxatw]

@VladimirFokow, it sounds a good workaround to have a dedicated directory if there is no other better way, thanks!

[madjxatw]

@lukasgeiter , another use case is when blog pattern is enabled, a tags.md file is placed in the docs to make tags in each blog post clickable. See https://squidfunk.github.io/mkdocs-material/plugins/tags/?h=tags#config.tags_file. I want to include everything excluding the tags file.

[VladimirFokow]

@madjxatw , as far as I understand, you specify

plugins:
  - tags:
      tags_file: tags.md

only once - in mkdocs.yml file.
So there is only one tags_file path that exists - only one page where you see all your tags.

If you want to exclude this page from nav - also put it into that hidden folder?
(just remember to update its path in mkdocs.yml)

[madjxatw]

@VladimirFokow , I am currently using dedicated directories as you suggested for what to be hidden in nav. My site has a complex directory structure, so I create a "hidden" folder in each subdirectory (section) as needed for better organization and managment. Really appreciate your suggestion and awesome-pages plugin!

BTW, I still kind of expect that MkDocs itself offers a feature similar to gitignore in the future instead of .pages files being scattered around. 😛

[lukasgeiter]

Thanks for helping out @VladimirFokow!

Indeed, at the moment a hidden folder is the easiest solution. I've been playing with the thought of adding exclude patterns before, so it's good to know that there's a need for that 👍

[PlasmaHH]

Just came here for the same reason. I like the suggestion earlier with the special char like ! or so.

My use case is that I have some external links pointing to something inside my docs where I want to show a special "not here anymore look elsehwere" page, but I don't want that page to be visible at all in the navigation.

Since I do not have control over those external links I cannot use the directory trick described.

[kamilkrzyskow]

@PlasmaHH
You can omit one file from the nav tree in .pages file and then use the mkdocs-redirects plugin to redirect the old missing unavailable path to the new page that contains special message.

nav:
    - Home:
        - ... | index.md
        # The not_here_anymore.md file is not included
    - dir_section

Just extract a specific file from the ...

If you're looking for a more automated approach perhaps you could modify our hook from here that uses GitPython and the renamed diff change to automatically create redirections in the plugin above:

• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/git_redirects.py

[PlasmaHH]

@PlasmaHH You can omit one file from the nav tree in .pages file and then use the mkdocs-redirects plugin to redirect the old missing unavailable path to the new page that contains special message.

nav:
    - Home:
        - ... | index.md
        # The not_here_anymore.md file is not included
    - dir_section

Just extract a specific file from the ...

If you're looking for a more automated approach perhaps you could modify our hook from here that uses GitPython and the renamed diff change to automatically create redirections in the plugin above:

• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/git_redirects.py

The redirect thing is really not an issue for me, there is nothing to redirect to. I am unsure at what your .pages file suggestion is hinting at, as it seems to just display the index.md file and nothing else. Or is the suggestion to hide one file to specify all the others manually?

To make it clearer, this is similar to how it looks like:

docs/
└── topic
    ├── .pages
    ├── deleted.md
    ├── entry1.md
    ├── entry2.md
    ├── entry3.md
    ├── entry4.md
    └── index.md

And in the end result I would like to have a simple entry in that .pages file that causes all the entry#.md and index.md to still be in the navbar, but just deleted.md should not be visible there.

[kamilkrzyskow]

@PlasmaHH
As per the docs:

• https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin?tab=readme-ov-file#rest-filter-patterns

You can use regex in the pattern matching, and regex allows for excluding values via the look ahead.

... | regex=^(?!deleted\.md)[\w\d]+\.md$

• ^ and $ (in global scope) mean start and end respectively
• (?!deleted\.md) excludes values that have deleted.md inside
• [\w\d]+ matches any a-zA-z0-9 characters, so it doesn't match -_ , or other values, needs to be adjusted here if you are using those in your file names.

Here is a working example using the example above:

• awesome-pages-exclude-one.zip

---

Though, if the file should be truly deleted then you should delete it, as this approach only hides it from nav, the file can be still accessed via the URL, and is added inside the sitemap.xml for search indexing ✌️

[lukasgeiter]

I've just released v3 of the plugin that should solve this issue!
Please note that the package has been renamed and there are some breaking changes - find out more in the docs.

---

In v3, you can specify ignore patterns, much like .gitignore, to hide pages from the navigation:

ignore: tags.md

Find out more in the docs

[mschrumpf]

This still is not working for me. I have tried several variants and workarounds.
I have the files .nav.yml and .nav.de.yml in the /docs directory. Both of them include the line

ignore: old-link.md

But I still get the warning:

WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - old-link.md

pretix/pretix-docs#75