Hi all! This is a feature request. Briefly: The page objects exposed through the template language have a property is_index, returning a boolean based on the page's input filename. I suspect this being visible to template code is an accident, but I think it's useful and would like to argue for documenting it and treating it as a stable interface.
So, thanks for hearing me out. I'm writing a theme, and I found a scenario where I wanted to determine whether a given page was an index page or not. Specifically, I wanted to treat it differently in a breadcrumb bar, collapsing redundant information when the name of an index page would otherwise appear right after the name of the section it's part of.
I'm fully aware that this is somewhat quirky behavior which would not be appropriate for every document. In fact, it's definitely inappropriate for documents that are encyclopedia-like, where sections don't necessarily have introductions, and the first page in a section might be just one of many similar entries. However, it is a thing some authors, including myself, might reasonably want for documents that have some sort of narrative structure whereby there's front matter at the beginning of a section that contextualizes the later pages in the section. Also, a single document might have both kinds of sections, so a project-level setting isn't an appropriate solution.
I feel like this is super abstract, so I'm going to offer an example.
- Core concepts
- Introduction
- Thing One
- Thing Two
- Alphabetical list of dragons
- Blue dragon
- Green dragon
- Red dragon
... If we imagine that "core concepts > introduction" is an index page, it makes sense to want to treat it specially navigation-wise. However, "blue dragon" should not receive the same treatment; it's not an index page, just a page that is coincidentally the first in its section.
I hope that makes sense.
My impression is that MkDocs is trying to be a general-purpose tool, so I think a feature like this is appropriate. That way it can be up to theme and document authors to decide when to use it, and perhaps most won't, but I know I'm planning to. If this is out of scope for MkDocs, that's fine and I'm not hurt. The code for is_index is already written, so nominally it seems easy enough to treat it as an official feature... anyway, I thought I'd ask!
Hi all! This is a feature request. Briefly: The page objects exposed through the template language have a property is_index, returning a boolean based on the page's input filename. I suspect this being visible to template code is an accident, but I think it's useful and would like to argue for documenting it and treating it as a stable interface.
So, thanks for hearing me out. I'm writing a theme, and I found a scenario where I wanted to determine whether a given page was an index page or not. Specifically, I wanted to treat it differently in a breadcrumb bar, collapsing redundant information when the name of an index page would otherwise appear right after the name of the section it's part of.
I'm fully aware that this is somewhat quirky behavior which would not be appropriate for every document. In fact, it's definitely inappropriate for documents that are encyclopedia-like, where sections don't necessarily have introductions, and the first page in a section might be just one of many similar entries. However, it is a thing some authors, including myself, might reasonably want for documents that have some sort of narrative structure whereby there's front matter at the beginning of a section that contextualizes the later pages in the section. Also, a single document might have both kinds of sections, so a project-level setting isn't an appropriate solution.
I feel like this is super abstract, so I'm going to offer an example.
... If we imagine that "core concepts > introduction" is an index page, it makes sense to want to treat it specially navigation-wise. However, "blue dragon" should not receive the same treatment; it's not an index page, just a page that is coincidentally the first in its section.
I hope that makes sense.
My impression is that MkDocs is trying to be a general-purpose tool, so I think a feature like this is appropriate. That way it can be up to theme and document authors to decide when to use it, and perhaps most won't, but I know I'm planning to. If this is out of scope for MkDocs, that's fine and I'm not hurt. The code for is_index is already written, so nominally it seems easy enough to treat it as an official feature... anyway, I thought I'd ask!