section names vs file names

[vsimko]

I've got the following directory structure:

docs/
  Situations/
    index.md
    situation01.md
    situation02.md
    situation03.md
  Solutions/
    index.md
    solution01.md
    solution02.md
    solution03.md
  index.md

Now, in every file, I've got a section name (level 1) e.g.

In file docs/Situations/index.md:

# About situtations
This section contains a list of situations that you might want to resolve.
Use the **search box** to find the right one.

In file docs/Situations/situation02.md:

# Second situation
bla bla ...

I've noticed that when clicking through the documentation the section names within the generated pages change as follows:

Browser at http://127.0.0.1:8000/Situations/

Browser at http://127.0.0.1:8000/Situations/situation01/

Browser at http://127.0.0.1:8000/Situations/situation02/

What I would expect instead

I would expect to see the same section names in all cases:

[waylan]

Currently a page title is obtained from either (1) the config, (2), the first H1 in the file, or (3) the filename (in that order). To be able to use a page title derived from the first H1 (step 2 above), then the page's Markdown needs to be processed before determining the title. Of course, when generating a page, only that page and previously generated pages are available and all pages not yet processed can only get there titles from either 1 or 3, which explains the progressive behavior you describe from page to page.

#316 discusses making some changes to how page titles are determined. In that discussion a case is made by some that there should be no need for any such mechanism as all pages can have their titles defined in the config. While there are some valid counterarguments (for why users would not want to use the config), the fact is, using the config is the only consistent way to define titles at this time. That's how MkDocs has worked from the beginning with the other methods being tacked on later. In fact, #316 hasn't been implemented yet because it would result in the same inconsistent behavior you are experiencing (if it had been up to me, I would not have added the incomplete support for H1 derived titles either).

My point is twofold: (2) This won't get fixed until we do a low-level refactor that allows us to properly implement #316 as well. (1) Until then, define you page titles in the config if you want consistency.

Btw, the fix for this is to step through the pages twice. Once to read the contents and a second time to generate the output (pass the pages to their templates). Of course, that means holding all of the content of all pages in memory between those two steps.

[vsimko]

Thanks for the explanation.
In the two-pass scenario, you don't have to store the content of all pages in memory.
You could make a quick first pass just to extract the first H1 from each file.

[waylan]

In the two-pass scenario, you don't have to store the content of all pages in memory.
You could make a quick first pass just to extract the first H1 from each file.

Except that that could be very finicky. By the time you have a solution that accounts for all of Markdown's edge cases, you might as well just run the Markdown parser.

[vsimko]

In the meantime, I created a quick and dirty hack in shell script that generates the "pages" section sorted on filename. It works for my project and might be useful for others until this is resolved in official mkdocs.
https://gist.github.com/vsimko/696e09cfcfbe77ad232e4cdb2481f814

I run the script as follows:

$ cd my-project-root
$ ./fix-mkdocs-pages.sh mkdocs.yml

[waylan]

I suppose that works as long as you have no inline markup (bold, italic, etc.) in your headers... which is why that won't work for an official solution. Regardless, thanks for sharing. Your script could be potentially helpful to anyone with a large number of documents who doesn't want to manually build a pages config from scratch.

[vsimko]

I just commented the code properly so that anyone can use and extend it if they like.

[waylan]

It was just brought to my attention when looking into #1382 that the title generating code was refactored in #1180. It may be (I haven't confirmed) that that refactor introduced this bug, which could be viewed as a regression. However, the only two fixes are to revert the change or to move forward with the refactor discussed in #699 (see this comment).

[lukasgeiter]

I just published mkdocs-awesome-pages-plugin that solves this issue and more. It's uses a similar approach as @vsimko's script but is implemented as an MkDocs plugin which allows it to generate the pages configuration on the fly when building. Additionally you can easily set the title for folders and define the order in which pages appear in the navigation without having to maintain a pages configuration.

[vsimko]

@lukasgeiter looks great!
The only problem I have with the plugin is the unnecessary nesting of pages.
I would like to keep each page in a separate directory that contains a single index.md together with all images used on that page. Here is an example

docs/
docs/section1/page11/index.md (# My Page1 in Section1)
docs/section1/page11/image1.png (used from docs/section1/page11/index.md)
docs/page2/index.md (# My Page2)
docs/page2/image2.png (used from docs/page2/index.md)
docs/index.md (# About)

I would like to see this:

pages:
  - About: index.md
  - My Page2: page2/index.md
  - Section 1:
    - My Page1 in Section1: section1/page11/index.md

Instead, I see the following (unnecessary nesting of page2):

pages:
  - About: index.md
  - Page2:
    - My Page2: page2/index.md
  - Section 1:
    - My Page1 in Section1: section1/page11/index.md

is there an option to automatically "collapse" sections that have just a single nested page ?

[waylan]

@lukasgeiter great to see the Plugin API used for that sort of thing!