New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

section names vs file names #1347

Closed
vsimko opened this Issue Nov 13, 2017 · 10 comments

Comments

Projects
3 participants
@vsimko

vsimko commented Nov 13, 2017

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/
image

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

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

What I would expect instead

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

@waylan

This comment has been minimized.

Member

waylan commented Nov 13, 2017

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

This comment has been minimized.

vsimko commented Nov 13, 2017

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

This comment has been minimized.

Member

waylan commented Nov 13, 2017

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.

@waylan waylan added the Bug label Nov 14, 2017

@waylan waylan added this to the 1.0.0 milestone Nov 14, 2017

@vsimko

This comment has been minimized.

vsimko commented Nov 15, 2017

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

This comment has been minimized.

Member

waylan commented Nov 15, 2017

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

This comment has been minimized.

vsimko commented Nov 15, 2017

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

@waylan

This comment has been minimized.

Member

waylan commented Jan 17, 2018

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).

@waylan waylan added this to To do in Pages Refactor Feb 5, 2018

@lukasgeiter

This comment has been minimized.

lukasgeiter commented Feb 7, 2018

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

This comment has been minimized.

vsimko commented Feb 7, 2018

@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

This comment has been minimized.

Member

waylan commented Feb 7, 2018

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

@waylan waylan moved this from To do to In progress in Pages Refactor Jun 8, 2018

@waylan waylan closed this in 34ef3ca Jun 28, 2018

Pages Refactor automation moved this from In progress to Done Jun 28, 2018

speg03 added a commit to speg03/speg03.github.io that referenced this issue Jun 30, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment