Requesting more features for hide

[idnsunset]

I've seen that a .pages containing hide: true can have the entire directory hidden in the navigation. However, I often would prefer to hide a part of files in a directory. For example with a directory in which I have too many files that would make the navigation list way too long, so we would put a index.md file to well organize them and only have the index.md listed in the navigation while hiding all others.

I hope the plugin could hide all files that are not listed in the nav instead of the whole directory.

[lukasgeiter]

That's actually how nav behaves. You can create a .pages file with the following contents and only index.md will show up in the navigation:

nav:
    - index.md

[idnsunset]

That's actually how nav behaves. You can create a .pages file with the following contents and only index.md will show up in the navigation:

nav:
    - index.md

But while having hide: true in the same file, this directory is ignored.

[lukasgeiter]

Yes that's true, but if you want to include only index.md in the navigation you shouldn't need hide: true at all.

I think I might not understand your situation fully. Could you post an example? Please include the file structure and desired navigation structure.

[idnsunset]

I might be misunderstanding how hide works. Suppose the following docs structure.

docs
|______ index.md
|______ subdir/
              |_____ index.md
              |_____ subsubdir/
                           |_____ index.md
                           |_____ ....

docs/.pages contains:

nav:
  - index.md
  - subdir

docs/subdir/.pages contains:

nav:
  - index.md
  - subsubdir

docs/subdir/subsubdir/.pages contains:

nav:
  - index.md

The generated nav list takes subsubdir directory as a nav_item, being shown with the first character capitalized, i.e. Subsubdir.

• title of docs/subdir/index.md
• Subsubdir (produced by the directory name)
  • title of docs/subdir/subsubdir/index.md

BTW, i am using the material theme, perhaps it is a theme issue? I just want to drop the Subsubdir that acts as a nav_item. i.e.:

• title of docs/subdir/index.md
• title of docs/subdir/subsubdir/index.md

The subsubdir directory is used just for better organization, i don't really want to take it as a section container.

[idnsunset]

Let's see what mkdocs original nav generates with the following structure:

nav:
  - Home: index.md
  - subdir/index.md
  - subsubdir/index.md

It generates what I want, three items containing the title of the index.md files. However, it has a problem that other files are not built into the site except for these three index.md.

Given nav structure with explicit section definition:

nav:
  - Home: index.md
  - Subdir:
    - subdir/index.md
    - Subsubdir:
      - index.md

then Subdir and Subsubdir will be generated as sections, grouping all files belong to each of them. This behavior makes sense because I explicitly define section names. But, when placing a bunch of files in a subdircectory, the subdirectory itself should not be taken as a section item. To specify section for a directory, we can do something like below:

nav:
  - index.md
  - Subsubdir:  # explicit section
    - subsubdir # directory to load

I've learnt that I misused the hide key. however, it would be highly appreciated if directories can be handled in consistency with mkdocs original nav,

[lukasgeiter]

Thanks for the examples. I'm getting a clearer picture now. However there is one thing I don't understand...

nav:
  - Home: index.md
  - subdir/index.md
  - subsubdir/index.md

It generates what I want, three items containing the title of the index.md files. However, it has a problem that other files are not built into the site except for these three index.md.

What exactly do you mean by are not built into the site? As far as I'm aware, MkDocs still includes files under docs in the build output even if they are not listed in the navigation.

[idnsunset]

What exactly do you mean by are not built into the site? As far as I'm aware, MkDocs still includes files under docs in the build output even if they are not listed in the navigation.

Yes, it does. It always build all files and place the html pages in the site directory. However, the excluded files are not only visually unlisted in the navigation, but also lose association with the navigation. In my case, I still want to associate them somewhat to the index pages in the navigation.

I am using Material theme's navigation tabs and awesome-pages plugin, not nav is defined in the mydocs.yml. After build, the titles of all index files (included in .pages file in each directory) are rendered as horizontal tabs in a top bar. When opening a non-index page, I expect the corresponding tab (linking to the index page in the same directory where the current page resides) to be styled (e.g. highlighted or in bold). I've attempted to list only index files in mkdocs.yml but it doesn't work, while this plugin meets the expectation.

After digging a bit more:

• When nav is not defined in the mkdocs.yml, mkdocs automatically loads all files and sets subdirectories as section items.
• When nav is defined in the mkdocs.yml, no section will be automatically generated unless some is explicitly given.

My expectation is to have fine control over directories, letting them handled as same as regular files. That is, if no explicit section keys are given to a directory in .pages, simply loads all files inside it (of course depending on its .pages file as well). When you really want to treat a directory as a section, just put a section key.

[lukasgeiter]

Okay now I think I fully understand your problem. Unfortunately I'm not sure I can help you with it.

You see, this plugin works by modifying MkDocs data structure storing the navigation tree. It makes it easier to customize the navigation without manually listing every file in mkdocs.yml. However, it does not actually add anything new to how the navigation is interpreted. Because MkDocs doesn't have the concept of hidden navigation items, the plugin has to remove a page from the navigation tree to "hide" it.

To render the active navigation entries for a page, MkDocs navigates from the page upwards in the navigation tree and marks all parents as active as well. But if the page is not in the tree, there are no parents to mark as active.

---

Right now I can't think of any way to achieve your desired result. I also don't see a way that my plugin could be augmented to do so. In order to support existing themes I have to stick to the MkDocs API which, as far as I can tell, simply doesn't account for pages to be hidden from the navigation in this way.

I believe this would have to be addressed in either MkDocs, the theme or both.

[madjxatw]

I started using mkdocs for one of my doc project some day ago and encountered very similar issue as yours. As a Sphinx user I think I exactly understand what you mean. That is, directories are just for organizing files and never should be used as a context for producing navigation (global toc).

As you mentioned, taking subdirectories as sections is actually a behavior of mkdocs itself, this plugin doesn't break the rule. If you stick to a certain theme for your project that has a specific directory structure, it would be better to tweak the theme's templates. But mkdocs doesn't provide enough template variables for tweaking, so for complicated features you may have to write our own plugin.

[madjxatw]

No pages need to to removed, he only wants the sections (not pages) generated from the subdirectories to be removed. A section links to nothing but just groups all the pages belonging to it. What he wants is if I didn't specify a section name for a directory, do not generate this section, but just load all files from it.

The navigation may be like as below with a certain theme

Section >

Note that the Seciton entry is actually generated from a subdirectory named section. When you expand the section, it becomes:

Section
  title of 1st page
  title of 2nd page
  ...

Now he wants:

title of 1st page
title of 2nd page

no section marker at all.

[lukasgeiter]

@madjxatw I don't think that's what @idnsunset wants. Here's an excerpt from the opening comment (emphasis mine):

For example with a directory in which I have too many files that would make the navigation list way too long, so we would put a index.md file to well organize them and only have the index.md listed in the navigation while hiding all others.

I'd prefer if you left explaining what @idnsunset wants to them. Of course you're welcome to contribute your own ideas and suggestions for a solution though. If the feature you're describing is something you want, please create a separate issue for it.

[madjxatw]

I need the same feature as he does. I only need pages from a directory but don't want any directory to produce section in the navigation, unless I specifically request one. I work this around by tweaking a certain theme, though it is not a common approach, as this should have be done inside mkdocs itself.

[madjxatw]

@idnsunset actually misused the 'hide feature of your plugin, hence the issue was titled in this way. But after discussion, the problem boils down to the directory as section. Anyway, I will create one of my own, thanks!

[andzejsp]

Could i request another feature for hide? I mean i want to hide section or say a folder from navigation in the header but i also want to be able to access that page with its contents if i know the link.

Example i have:

docs
|______ index.md
|______ subdir/
              |_____ index.md
              |_____ subsubdir/
                           |_____ index.md
                           |_____ ....
|______ subdir2/
              |_____ index.md
              |_____ subsubdir22/
                           |_____ index.md
                           |_____ ....
                           |_____ subsubdir222/
                                       |_____ index.md
                                       |_____ ....

And i want to hide subsubdir22 from main navigation in the header, but i want to open the subsubdir22 link (knowing it in advance, like put a hidden button somewhere in the page) and see all the contents of subsubdir22 and subsubdir222 in the navigation or toc so that i could navigate using generated toc.

[albertkun]

I agree that this type of feature would be helpful, as I'm using Netify-CMS ontop of mkdocs material, but setting the page to draft still makes it show up on the left side navigation. 😢

[Noobzik]

I second this feature request about andwejsp, maybe we shall create a separate feature request ?

[lukasgeiter]

@Noobzik Yes, a separate feature request would make sense! Please also include what problem you're trying to solve 🙂