Building hidden pages

[jhamman]

Is it possible to tell mkdocs to build pages but not have them show up in the side bar? If it is possible, an example of how to do this in the documentation would be great.

I asked this question here as well: https://groups.google.com/forum/#!topic/mkdocs/ILW9-SIdERs

[keelii]

I have the same question
mkdocs only build specified .md files in yml. Sometimes i use relative path to reference md file, but it not working for me .

if there is a glob pattern to set, It would be better ^!^ :

mdFiles: docs/*/*.md

[waylan]

No this is not possible as this time. I am not aware that it is on the road-map either, although I am not the one to make such a decision. I would suggest that if such a feature was to be implemented, it would use the page meta-data to define a page as "hidden" (perhaps by adding a hidden: true key-value pair to the meta-data for the page). Then, when building the nav, it would simply be skipped.

[jhamman]

Thanks @waylan - Good to know.

Any thoughts on how difficult this feature would be to add? The hidden: true api is exactly what I was envisioning.

[mistresseve666]

I've ran across this same exact issue a few weeks ago, and adopted the same method that Docker used for their docs (they recently adopted Hugo):

• Set the Page Title in the mkdocs.yml file to a special value (they used HIDDEN).
• Update the Template to not include a pages with the above special value.

It feels very hacky, but it's working well enough for me right now. The docs base I'm maintaining is far smaller than Docker's so it's OK for now. I can imagine if you have a larger documentation base it might get annoying to maintain.

@waylan From trying to figure out how to get around this limitation, and reading older issues people opened on this topic it doesn't seem to be something that plans to be supported by mkdocs; and I would agree. mkdocs is intended to be used for simple documentation. Having dozens of hidden pages to be used for links only is a step above simple. Personally, I'd rather see this handled via a extension once API support is added.

[waylan]

According to a recent edit to the first comment on #689 this is addressed by the work there. That said, it is not clear to me how or when that work will be merged in.

In any event, I agree that this seems more like a feature for a plugin API.

[jhamman]

Thanks for the input @robodude666 and @waylan. I went ahead and modified the read-the-docs theme to exclude nav items == 'hidden'. That seems to be working locally and on read-the-docs.

This solution came from @martinzugnoni and works like a charm, albeit a bit hackish...

This is the original "base.html" file:
https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/base.html

mkdocs.yml

# Pages not available to end users
- 'hidden': 'internal_endpoints.md'

base.html

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        <ul class="current">
          {% for nav_item in nav %}
            {% if nav_item.title != "hidden" %}               <=== this is the important line
              <li>{% include "toc.html" %}<li>
            {% endif %}
          {% endfor %}
        </ul>
      </div>

Given that this was pretty easy to implement, and has nothing to do with the complexity of the site, I would still like to see this become part of the larger package.

[d0ugal]

Neat, good to see that you found a work around for this. I would like to see this work with the Markdown metadata. For example, you might add "hidden: true" to the top of the file and then it will be excluded from the nav. I am not sure how #689 is looking to add this. @tomchristie?

[tomchristie]

Rather than having to include them in the nav with 'hidden' it'd make more sense to just build all .md pages irrespective of if they're in 'pages' or not.

I am not sure how #689 is looking to add this

At the moment that'd build all md files, and warn if any of them are not in pages. For this behavior we'd simply want to turn that warning off.

[mistresseve666]

@tomchristie If pages is being used by a project I'd rather see mkdocs warn when a page is built but not in pages, and then add the ability to list only the filename/globs w/o a name.

For example:

pages:
- 'Introduction': 'index.md'
- 'User Guide': 'user-guide.md'
- 'About': 'about.md'
- hidden_file.md
- hidden/folder/*.md
- extension/generated/apis/*.md

This makes it explicit that these files are intended to be hidden, as no title is given to them (title can be extracted from filename/metadata in these cases).

It'll also help catch cases where the author or contributor creates a new file but forgets to update pages. This way they'll get a warning, which they can explicitly silence by adding it to the pages list.

It also makes it possible for extensions to generate pages that will be included, though albeit extensions would probably have access to modify the pages config...

[waylan]

This makes it explicit that these files are intended to be hidden, as no title is given to them (title can be extracted from filename/metadata in these cases).

My preference would be to always define the Title in the meta-data and never in the config. But according to the above proposal, that would make all my pages "hidden" which is not what I want.

All "hidden" means is that the page is excluded from the nav menu. Interestingly, if no pages config is provided, all pages are auto-discovered and included in the nav menu. All the pages config gives you is a clear way to define order and nesting of the nav menu (I see the ability to define a title as a convenient side effect). It would follow quite naturally then, that any pages not listed in the pages config would then not be listed in the nav menu. As #689 gives us this already (albeit with a warning), I don't see much room for improvement.

[mistresseve666]

My preference would be to always define the Title in the meta-data and never in the config.

I would agree with you, as I don't personally like my recommendation of excluding the title; it was just a simply example to illustrate explicitly hiding pages without having to add a whole bunch of new config options. If we would rather have a boolean flag in the metadata of a page, that would be fine too.

As #689 gives us this already (albeit with a warning), I don't see much room for improvement.

The improvement I'm suggesting is to only give warnings for pages that weren't explicitly hidden. If I have 100 API docs that I'm trying to hide from the navigation I don't want to see 100 warnings when I build my docs. That will make the warnings meaningless if I'm always going to ignore them as it makes it very easy for an important warning to go unnoticed.

[waylan]

I don't want to see 100 warnings when I build my docs.

Right, and as @tomchristie stated, those warnings should be able to be turned off. I assumed that that was clear and didn't restate it. Sounds like we are on the same page here.

[mistresseve666]

I'm trying to point out that they should only be turned off for specific pages, not all. If I mark 5 pages as hidden, and create a new *.md file I should get 1 warning. If that's understood then I'm okay 😄.