Skip to main content

MkDocs plugin to allow clickable sections that lead to an index page

Project description

mkdocs-section-index

Plugin for MkDocs to allow clickable sections that lead to an index page

PyPI GitHub GitHub Workflow Status

pip install mkdocs-section-index

Example

Screencast with comparison

With this nav in mkdocs.yml (or without nav but with an equivalent directory structure):

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs:
    - borgs/index.md
    - Bar: borgs/bar.md
    - Foo: borgs/foo.md

plugins:
  - section-index

The borgs/index.md page is merged as the index of the "Borgs" section. Normally sections in MkDocs cannot be clickable as pages themselves, but this plugin makes that possible.

See also: a realistic demo site.

Theme support

This plugin requires per-theme overrides (implemented within the plugin), or support from themes themselves.

Currently supported themes are:

Usage notes

The kind of nav as shown above also happens to be what MkDocs produces when nav is omitted; it detects index.md and README.md pages and automatically puts them as the first item.

To make writing this kind of nav more natural (in YAML there's no better option), consider using the literate-nav plugin along with this; then the above nav might be written like this:

* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/index.md)
    * [Bar](borgs/bar.md)
    * [Foo](borgs/foo.md)

Implementation

"Protocol"

Normally in MkDocs nav, the items can be one of:

  • a Section, which has a title and children.
    • (url is always None)
  • a Page, which has a title and url.
    • (title can be omitted, and later deduced from the page content)
    • (children is always None)
  • a Link (inconsequential for our purposes).

This plugin introduces a hybrid kind of Page, which has all of these properties:

  • title: str
  • url: str
  • children: list
  • is_page = True
  • is_section = True

Such a special item gets put into a nav in the place of a Section which has a Page with an intentionally omitted title as its first child. Those two are naturally combined into a special section-page that's a hybrid of the two.

Implementation within themes

Then all that a theme's template needs to do is to meaningfully support such nav items -- ones that have both a url and children. The item should be directly clickable to go to the corresponding page, and also be able to house sub-items.

Of course, currently templates don't expect such a case; or if they did, it would be purely by chance. So currently this plugin "hacks into" templates of supported themes, patching their source on the fly to fit its needs. The hope is that, once this plugin gains enough traction, theme authors will be happy to directly support this scenario (which is totally non-intrusive and backwards-compatible), and then the patches could be dropped.

"Alternatives considered"

Even if all the template patches are gone, this plugin will still remain as the implementation of this special nav "protocol", and as the opt-in mechanism. In the author's view, such an approach is advantageous, because:

  • This is too controversial to be enabled by default, or even be part of MkDocs at all. This has been discussed in the past and dropped. The main reason is that in MkDocs there's no requirement for a nav's structure to follow the actual directory structure of the doc files. Consequently, there's no natural way to deduce that a document should become the index page of a section just from its location, even if it's named index.md. Although if the nav is omitted & generated, then yes, such an assumption works. It also works in the vast majority of actual usages with a nav, but that doesn't help.

  • Themes themselves also probably shouldn't directly try to detect logic such as "first child of a section if it has no title" and manually collapse the child within Jinja template code, as that's too messy. This also shouldn't be enabled by default. And even though templates could also make this opt-in, a centralized approach like this one ensures that accessing this feature is done uniformly. Not to mention that templates might never implement this themselves.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs-section-index-0.3.3.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

mkdocs_section_index-0.3.3-py3-none-any.whl (8.1 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs-section-index-0.3.3.tar.gz.

File metadata

  • Download URL: mkdocs-section-index-0.3.3.tar.gz
  • Upload date:
  • Size: 8.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.10.1 Linux/5.15.11-arch2-1

File hashes

Hashes for mkdocs-section-index-0.3.3.tar.gz
Algorithm Hash digest
SHA256 434c7c2378a7c2a7ce15f642fcb0cd04af741a7d157eab47e6c02c3eb8a52a98
MD5 cfe655bf21d6f3ca26b3389114df32f1
BLAKE2b-256 a80c8f2ae28867d05eaee2e728590cc49b02cac660fecea56ae392f16f0b22cf

See more details on using hashes here.

Provenance

File details

Details for the file mkdocs_section_index-0.3.3-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_section_index-0.3.3-py3-none-any.whl
Algorithm Hash digest
SHA256 a79d8b6e21b5d9d4edf056246ea1d1d4f6c8705469c20bbe06e3ecd5b30fc4e7
MD5 9b55c2f6e06947d5224a3d70bdf02747
BLAKE2b-256 9851bac56da80327458c3ce77ab763a7adc98c65bd2fba50330ecfb0d30e2c5a

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page