| Name | mkdocs-section-index JSON |
| Version |
0.3.9
JSON |
| download |
| home_page | None |
| Summary | MkDocs plugin to allow clickable sections that lead to an index page |
| upload_time | 2024-04-20 14:40:58 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
mkdocs
mkdocs-plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-section-index
**[Plugin][] for [MkDocs][] to allow clickable sections that lead to an index page**
[](https://pypi.org/project/mkdocs-section-index/)
[](https://github.com/oprypin/mkdocs-section-index/blob/master/LICENSE.md)
[](https://github.com/oprypin/mkdocs-section-index/actions?query=event%3Apush+branch%3Amaster)
```shell
pip install mkdocs-section-index
```
[mkdocs]: https://www.mkdocs.org/
[plugin]: https://www.mkdocs.org/user-guide/plugins/
## [Example](example/)
With this `nav` in *mkdocs.yml* (or without `nav` but with [an equivalent directory structure](example/docs/)):
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- borgs/index.md
- Bar: borgs/bar.md
- Foo: borgs/foo.md
plugins:
- search
- 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](https://oprypin.github.io/crystal-book/syntax_and_semantics/literals/).**
## Theme support
This plugin requires per-theme overrides (implemented within the plugin), or [support from themes themselves](#implementation-within-themes).
Currently supported [themes][] are:
* [material](https://github.com/squidfunk/mkdocs-material)
* [readthedocs](https://www.mkdocs.org/user-guide/styling-your-docs/#readthedocs)
* [nature](https://github.com/waylan/mkdocs-nature)
[themes]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
## 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`][nav-gen] 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](https://github.com/mkdocs/mkdocs/pull/1042#issuecomment-290787554)), consider using the **[literate-nav][] plugin** along with this; then the above *nav* might be written like this:
```markdown
* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/index.md)
* [Bar](borgs/bar.md)
* [Foo](borgs/foo.md)
```
[literate-nav]: https://oprypin.github.io/mkdocs-literate-nav/
## [Implementation](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/plugin.py)
### "Protocol"
Normally in MkDocs [`nav`][nav], the items can be one of:
* a [`Section`][Section], which has a `title` and `children`.
* (`url` is always `None`)
* a [`Page`][Page], which has a `title` and `url`.
* (`title` can be omitted, and later deduced from the page content)
* ([`children`][children] is always `None`)
* a [`Link`][Link] (inconsequential for our purposes).
This plugin introduces a [hybrid kind of `Page`](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/__init__.py), 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](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/__init__.py) that's a hybrid of the two.
[nav]: https://www.mkdocs.org/user-guide/custom-themes/#nav
[Section]: https://www.mkdocs.org/user-guide/custom-themes/#section
[Page]: https://www.mkdocs.org/user-guide/custom-themes/#page
[children]: https://github.com/mkdocs/mkdocs/blob/2f833a1a29095733e53a04d062d315629d974ebe/mkdocs/structure/pages.py#L26
[Link]: https://www.mkdocs.org/user-guide/custom-themes/#link
### 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](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/rewrites.py) 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](https://github.com/mkdocs/mkdocs/pull/1042#issuecomment-260813540). 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][nav-gen], 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.
[nav-gen]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-section-index",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin",
"author": null,
"author_email": "Oleh Prypin <oleh@pryp.in>",
"download_url": "https://files.pythonhosted.org/packages/86/09/3cfcfec56740fba157991cd098c76dd08ef9c211db292c7c7d820d16c351/mkdocs_section_index-0.3.9.tar.gz",
"platform": null,
"description": "# mkdocs-section-index\n\n**[Plugin][] for [MkDocs][] to allow clickable sections that lead to an index page**\n\n[](https://pypi.org/project/mkdocs-section-index/)\n[](https://github.com/oprypin/mkdocs-section-index/blob/master/LICENSE.md)\n[](https://github.com/oprypin/mkdocs-section-index/actions?query=event%3Apush+branch%3Amaster)\n\n```shell\npip install mkdocs-section-index\n```\n\n[mkdocs]: https://www.mkdocs.org/\n[plugin]: https://www.mkdocs.org/user-guide/plugins/\n\n## [Example](example/)\n\n\n\nWith this `nav` in *mkdocs.yml* (or without `nav` but with [an equivalent directory structure](example/docs/)):\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs:\n - borgs/index.md\n - Bar: borgs/bar.md\n - Foo: borgs/foo.md\n\nplugins:\n - search\n - section-index\n```\n\nThe *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.\n\n**See also: [a realistic demo site](https://oprypin.github.io/crystal-book/syntax_and_semantics/literals/).**\n\n## Theme support\n\nThis plugin requires per-theme overrides (implemented within the plugin), or [support from themes themselves](#implementation-within-themes).\n\nCurrently supported [themes][] are:\n\n* [material](https://github.com/squidfunk/mkdocs-material)\n* [readthedocs](https://www.mkdocs.org/user-guide/styling-your-docs/#readthedocs)\n* [nature](https://github.com/waylan/mkdocs-nature)\n\n[themes]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes\n\n## Usage notes\n\nThe kind of *nav* as shown above also happens to be what MkDocs produces when `nav` is omitted; it detects [`index.md` and `README.md`][nav-gen] pages and automatically puts them as the first item.\n\nTo make writing this kind of `nav` more natural ([in YAML there's no better option](https://github.com/mkdocs/mkdocs/pull/1042#issuecomment-290787554)), consider using the **[literate-nav][] plugin** along with this; then the above *nav* might be written like this:\n\n```markdown\n* [Frob](index.md)\n* [Baz](baz.md)\n* [Borgs](borgs/index.md)\n * [Bar](borgs/bar.md)\n * [Foo](borgs/foo.md)\n```\n\n[literate-nav]: https://oprypin.github.io/mkdocs-literate-nav/\n\n## [Implementation](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/plugin.py)\n\n### \"Protocol\"\n\nNormally in MkDocs [`nav`][nav], the items can be one of:\n\n* a [`Section`][Section], which has a `title` and `children`.\n * (`url` is always `None`)\n* a [`Page`][Page], which has a `title` and `url`.\n * (`title` can be omitted, and later deduced from the page content)\n * ([`children`][children] is always `None`)\n* a [`Link`][Link] (inconsequential for our purposes).\n\nThis plugin introduces a [hybrid kind of `Page`](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/__init__.py), which has all of these properties:\n\n* `title`: `str`\n* `url`: `str`\n* `children`: `list`\n* `is_page` = `True`\n* `is_section` = `True`\n\nSuch 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](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/__init__.py) that's a hybrid of the two.\n\n[nav]: https://www.mkdocs.org/user-guide/custom-themes/#nav\n[Section]: https://www.mkdocs.org/user-guide/custom-themes/#section\n[Page]: https://www.mkdocs.org/user-guide/custom-themes/#page\n[children]: https://github.com/mkdocs/mkdocs/blob/2f833a1a29095733e53a04d062d315629d974ebe/mkdocs/structure/pages.py#L26\n[Link]: https://www.mkdocs.org/user-guide/custom-themes/#link\n\n### Implementation within themes\n\nThen 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.\n\nOf 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](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/rewrites.py) 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.\n\n### \"Alternatives considered\"\n\nEven 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:\n\n* 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](https://github.com/mkdocs/mkdocs/pull/1042#issuecomment-260813540). 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][nav-gen], then yes, such an assumption works. It also works in the vast majority of actual usages *with* a *nav*, but that doesn't help.\n\n* 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.\n\n[nav-gen]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs plugin to allow clickable sections that lead to an index page",
"version": "0.3.9",
"project_urls": {
"Documentation": "https://oprypin.github.io/mkdocs-section-index/",
"History": "https://github.com/oprypin/mkdocs-section-index/releases",
"Issues": "https://github.com/oprypin/mkdocs-section-index/issues",
"Source": "https://github.com/oprypin/mkdocs-section-index"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d21916f6368f69949ea2d0086197a86beda4d4f27f09bb8c59130922f03d335d",
"md5": "4d0acfd470fd87e51a21f5d46abc3dbf",
"sha256": "5e5eb288e8d7984d36c11ead5533f376fdf23498f44e903929d72845b24dfe34"
},
"downloads": -1,
"filename": "mkdocs_section_index-0.3.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d0acfd470fd87e51a21f5d46abc3dbf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8728,
"upload_time": "2024-04-20T14:40:56",
"upload_time_iso_8601": "2024-04-20T14:40:56.864147Z",
"url": "https://files.pythonhosted.org/packages/d2/19/16f6368f69949ea2d0086197a86beda4d4f27f09bb8c59130922f03d335d/mkdocs_section_index-0.3.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86093cfcfec56740fba157991cd098c76dd08ef9c211db292c7c7d820d16c351",
"md5": "4238b06ca69663710beb510d9b57b079",
"sha256": "b66128d19108beceb08b226ee1ba0981840d14baf8a652b6c59e650f3f92e4f8"
},
"downloads": -1,
"filename": "mkdocs_section_index-0.3.9.tar.gz",
"has_sig": false,
"md5_digest": "4238b06ca69663710beb510d9b57b079",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13941,
"upload_time": "2024-04-20T14:40:58",
"upload_time_iso_8601": "2024-04-20T14:40:58.164323Z",
"url": "https://files.pythonhosted.org/packages/86/09/3cfcfec56740fba157991cd098c76dd08ef9c211db292c7c7d820d16c351/mkdocs_section_index-0.3.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-20 14:40:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oprypin",
"github_project": "mkdocs-section-index",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-section-index"
}
