| Name | mkdocs-literate-nav JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | None |
| Summary | MkDocs plugin to specify the navigation in Markdown instead of YAML |
| upload_time | 2023-09-10 22:17:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
mkdocs
mkdocs-plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-literate-nav
**[Plugin][] for [MkDocs][] to specify the navigation in Markdown instead of YAML**
[](https://pypi.org/project/mkdocs-literate-nav/)
[](https://github.com/oprypin/mkdocs-literate-nav/blob/master/LICENSE.md)
[](https://github.com/oprypin/mkdocs-literate-nav/actions?query=event%3Apush+branch%3Amaster)
```shell
pip install mkdocs-literate-nav
```
Works well with **[section-index][]** and **[gen-files][]**. Supplants **[awesome-pages][]**.
[mkdocs]: https://www.mkdocs.org/
[plugin]: https://www.mkdocs.org/user-guide/plugins/
[section-index]: https://oprypin.github.io/mkdocs-section-index/
[gen-files]: https://oprypin.github.io/mkdocs-gen-files/
[awesome-pages]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
## Usage
Activate the plugin in **mkdocs.yml**:
```yaml
plugins:
- search
- literate-nav:
nav_file: SUMMARY.md
```
and **drop** the `nav` section if it's present there; it will be ignored now. ([Unless you want to keep it?](#hybrid-nav))
<table markdown="1"><tr>
<td>To get this navigation,</td>
<td>create the file <b>SUMMARY.md</b>:</td>
<td>(old YAML equivalent:)</td>
</tr><tr><td>
* [Frob](#index.md)
* [Baz](#baz.md)
* [Borgs](#borgs/index.md)
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```markdown
* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/index.md)
* [Bar](borgs/bar.md)
* [Foo](borgs/foo.md)
```
</td><td>
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- borgs/index.md
- Bar: borgs/bar.md
- Foo: borgs/foo.md
```
</td></tr></table>
IMPORTANT: The nav file must be put inside the [`docs` directory][docs_dir] -- at the root of it.
So, the plugin lets you specify your site's navigation with lists of links that are parsed according to normal Markdown rules.
Note that, the way we wrote the Markdown, a section seems to also have a page associated with it. MkDocs doesn't actually support that, and neither is it representable in YAML directly, so the plugin tries to do the next best thing: include the link as the first page of the section. However, this structure is perfectly suited for the *[section-index][]* plugin, which actually makes that work. Or you could just *not* associate a link with sections:
<table markdown="1"><tr>
<td>To get this navigation,</td>
<td>create the file <b>SUMMARY.md</b>:</td>
<td>(old YAML equivalent:)</td>
</tr><tr><td>
* [Frob](#index.md)
* [Baz](#baz.md)
* Borgs
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```markdown
* [Frob](index.md)
* [Baz](baz.md)
* Borgs
* [Bar](borgs/bar.md)
* [Foo](borgs/foo.md)
```
</td><td>
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- Bar: borgs/bar.md
- Foo: borgs/foo.md
```
</td></tr></table>
**[See syntax details about literate nav files.](https://oprypin.github.io/mkdocs-literate-nav/reference.html)**
You can find more examples of the "literate nav" syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav).
### Nav cross-link
But why stop there? Each directory can have its own decoupled navigation list (see how the trailing slash initiates a nav cross-link):
<table markdown="1"><tr>
<td>To get this navigation,</td>
<td>create the file <b>SUMMARY.md</b>:</td>
<td>(old YAML equivalent:)</td>
</tr><tr><td rowspan="3">
* [Frob](#index.md)
* [Baz](#baz.md)
* Borgs
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```markdown
* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/)
```
</td><td rowspan="3">
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- Bar: borgs/bar.md
- Foo: borgs/foo.md
```
</td></tr><tr>
<td>and the file <b>borgs/SUMMARY.md</b>:</td>
</tr><tr><td>
```markdown
* [Bar](bar.md)
* [Foo](foo.md)
```
</td></tr></table>
> NOTE: The nav file in the subdirectory is picked up *only* because its directory is explicitly mentioned in a parent nav file. **SUMMARY.md** (generally [`nav-file`](customizing-nav_file)) files are **not** picked up implicitly (only the root nav file is "implicit").
>
> So you might say that the nav construction approach is exactly the opposite from the *[awesome-pages][]* plugin.
>
> That said, an [inferred cross-linked directory](#inferred-sub-directory) (whether directly or through [wildcards](#wildcards)) gets resolved recursively, so that way you actually go back to implicit resolution.
#### Inferred sub-directory
Or perhaps you don't care about the order of the pages under the **borgs/** directory? Just drop the file __borgs/SUMMARY.md__ and let it be inferred (recursively, if applicable). For our particular example, the final result would be the same.
The fallback behavior follows the [default behavior of MkDocs when nav isn't specified][mkdocs-nav], except that you can leave out only some directory trees, rather than an all-or-nothing choice.
### Wildcards
Between the two extremes of entirely specifying a nav and entirely inferring it, there's the option of applying wildcards.
Instead of putting links like `[Foo 1](foo_1.md)`, `[Foo 2](foo_2.md)` into the nav list, you can write a wildcard item: `foo_*.md` (bare, not as a link). The asterisk indicates that any number of characters can go there, and the file name has to match the rest of the pattern.
A wildcard item is always required to have at least one `*` asterisk in it, because if it doesn't, then it's *just* a bare item, which are disallowed.
**[See details about wildcards.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#wildcards)**
So this can be used to fully specify order for items that matter and apply wildcards for all other cases. Example:
<table markdown="1"><tr>
<td>By writing this literate nav file,</td>
<td>you may get a nav like this:</td>
<td>(assuming the files exist:)</td>
</tr><tr><td>
```markdown
- [Welcome](index.md)
- Usage
- [Foo](usage/foo.md)
- usage/*.md
- */
- *.md
- [API docs](api/)
- [License](license.md)
```
</td><td>
```yaml
- Welcome: index.md
- Usage:
- Foo: usage/foo.md
- usage/bar.md
- usage/baz.md
- Tips:
- tips/other-stuff.md
- tips/stuff.md
- changelog.md
- credits.md
- API docs:
- api/Foo.md
- Bar:
- api/Bar/index.md
- api/Bar/Baz.md
- License: license.md
```
</td><td>
* index.md
* changelog.md
* credits.md
* usage / bar.md
* usage / baz.md
* usage / foo.md
* tips / stuff.md
* tips / other-stuff.md
* api / Foo.md
* api / Bar / index.md
* api / Bar / Baz.md
</td></tr></table>
TIP: Speaking of API docs... Want to fine-tune file ordering in a large directory tree? Check out [integrations with other plugins](#extras).
The paths are relative to the directory that the nav file is in. Matching files in subdirectories also works, in both ways: `*/foo.md` and `foo/*.md`.
As it's impossible for a user to specify the titles of items produced by a wildcard, they have to be inferred, based on [normal rules of MkDocs][mkdocs-nav].
> TIP: The ordering of items matches MkDocs' default, so first go all files, alphabetically (but with the index file first), then all directories. But, as an example, you could actually swap that, by writing:
>
> ```markdown
> - */
> - *
> ```
You can find more examples of the wildcard syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav/wildcard).
### Customizing `nav_file`
We've been using **SUMMARY.md** as the name of the file that specifies the nav (actually that is also the default value of `nav_file`), but naturally, you can use any other file name.
**[See details about the `nav_file` config.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#nav_file)**
The plugin takes care to not let MkDocs complain if you don't end up using the nav document as an actual page of your doc site.
#### Show off your nav on the front page
Or maybe you want the opposite -- make the nav page very prominent? You can actually use the index page, **README.md**, for the nav!
Why would one do this? Well, GitHub (or another source hosting) also displays the Markdown files, and it's quite a nice perk to show off your navigation right in the index page of a directory. Of course, then you'd probably refrain from using [wildcards](#wildcards). [Directory cross linking](#nav-cross-link) still looks great, though.
What's that, you ask? If the index page is taken up by navigation, we can't put any other content there, can we? Actually, we can! The nav list can just be put at the bottom of the page that also has whatever other content before that.
[See an example of all this in action](https://github.com/oprypin/crsfml/tree/master/docs/tutorials)
#### Explicit nav mark
If the plugin is confused where in the document the nav is, or if you want to explicitly put it in a particular location, please precede the Markdown list with this HTML comment (verbatim) on a line of its own:
```html
<!--nav-->
```
### Hybrid nav
Do the features of this plugin interest you but you're not on board with the idea of migrating your whole nav?
You can actually keep using [MkDocs' own nav specification][mkdocs-nav] at the root, *but* defer only some subdirectories to the *literate-nav* plugin. In that case make sure to *not* put a nav file at the [`docs` root][docs_dir], otherwise the native nav will be ignored.
<table markdown="1"><tr>
<td>To get this navigation,</td>
<td>put this into <b>mkdocs.yml</b>:</td>
<td>(old YAML equivalent:)</td>
</tr><tr><td rowspan="3">
* [Frob](#index.md)
* [Baz](#baz.md)
* Borgs
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs: borgs/
```
</td><td rowspan="3">
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- Bar: borgs/bar.md
- Foo: borgs/foo.md
```
</td></tr><tr>
<td>& create the file <b>borgs/SUMMARY.md</b>:</td>
</tr><tr><td>
```markdown
* [Bar](bar.md)
* [Foo](foo.md)
```
</td></tr></table>
The syntax to defer to a subdirectory, just like [in a literate nav](#nav-cross-link), is to write an item that *ends* with a slash.
NOTE: There is no way to use a YAML nav for a subdirectory, only a literate nav can be deferred.
Wildcards also work very similarly.
**[See details about syntax additions for MkDocs native nav.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#mkdocs-native-nav)**
You can find examples of the hybrid nav syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav/hybrid).
#### MkDocs native nav with inferred subdirectories
As before, whenever you have the option of using a literate nav file for a sub-directory, you can also *not* put any nav file there and infer the sub-directory instead. So, *not* creating the file **borgs/SUMMARY.md** would have yielded the same result in the above example.
So basically, you can use the *literate-nav* plugin just for its ability to infer only sub-directories, without ever writing any actual "literate navs".
#### Details about hybrid nav
As a final example, note that there are two ways to include a subdirectory, with significant difference:
<table markdown="1"><tr>
<td>To get this navigation,</td>
<td>put this into <b>mkdocs.yml</b>:</td>
<td>To get this navigation,</td>
<td>put this into <b>mkdocs.yml</b>:</td>
</tr><tr><td>
* [Frob](#index.md)
* [Baz](#baz.md)
* Borgs
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- Borgs: borgs/
```
</td><td>
* [Frob](#index.md)
* [Baz](#baz.md)
* [Bar](#borgs/bar.md)
* [Foo](#borgs/foo.md)
</td><td>
```yaml
nav:
- Frob: index.md
- Baz: baz.md
- borgs/*
```
</td></tr></table>
So, a directory item with a title becomes a section titled as such. And a wildcard (which can't have a title specified) gets inlined into the existing section. This simple example has no sub-sub-directories, but the relative subdirectory structure would be preserved in both cases if it did.
### Extras
#### Programmatic control over the nav
Let's say you need the ability to infer nav for a sub-directory, but are unhappy with the default naming/layout behavior, and you don't want to write all that out manually either. Then, definitely check out the ***[gen-files][]* plugin**. Its normal usage is to programmatically add files to the site during the build, but that also includes literate nav files! Moreover, you don't even have to teach your program to write Markdown. There's a more direct integration: `mkdocs_gen_files.Nav.build_literate_nav`.
[See an example that generates both the files and the navigation covering them](https://github.com/mkdocstrings/mkdocstrings/blob/5802b1ef5ad9bf6077974f777bd55f32ce2bc219/docs/gen_doc_stubs.py#L25).
#### Indent lists by 2 spaces, not 4
Configure it through [tab_length](https://oprypin.github.io/mkdocs-literate-nav/reference.html#tab_length) or [markdown_extensions](https://oprypin.github.io/mkdocs-literate-nav/reference.html#markdown_extensions)
#### Migrating from GitBook?
It might be very easy! Just beware of the stricter Markdown parser; it will *not* accept 2-space indentation for sub-lists.
And use this for **mkdocs.yml**:
<table><tr><td>
```yaml
use_directory_urls: false
```
```yaml
plugins:
- search
- same-dir
- section-index
- literate-nav:
nav_file: SUMMARY.md
```
</td><td>
```yaml
theme:
name: material
```
```yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.magiclink
- pymdownx.superfences
```
</td></tr></table>
[mkdocs-nav]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-literate-nav",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs,mkdocs-plugin",
"author": null,
"author_email": "Oleh Prypin <oleh@pryp.in>",
"download_url": "https://files.pythonhosted.org/packages/4d/f9/c48a04f3cf484f8016a343c1d7d99c3a1ef01dbb33ceabb1d02e0ecabda7/mkdocs_literate_nav-0.6.1.tar.gz",
"platform": null,
"description": "# mkdocs-literate-nav\n\n**[Plugin][] for [MkDocs][] to specify the navigation in Markdown instead of YAML**\n\n[](https://pypi.org/project/mkdocs-literate-nav/)\n[](https://github.com/oprypin/mkdocs-literate-nav/blob/master/LICENSE.md)\n[](https://github.com/oprypin/mkdocs-literate-nav/actions?query=event%3Apush+branch%3Amaster)\n\n```shell\npip install mkdocs-literate-nav\n```\n\nWorks well with **[section-index][]** and **[gen-files][]**. Supplants **[awesome-pages][]**.\n\n[mkdocs]: https://www.mkdocs.org/\n[plugin]: https://www.mkdocs.org/user-guide/plugins/\n[section-index]: https://oprypin.github.io/mkdocs-section-index/\n[gen-files]: https://oprypin.github.io/mkdocs-gen-files/\n[awesome-pages]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin\n\n## Usage\n\nActivate the plugin in **mkdocs.yml**:\n\n```yaml\nplugins:\n - search\n - literate-nav:\n nav_file: SUMMARY.md\n```\n\nand **drop** the `nav` section if it's present there; it will be ignored now. ([Unless you want to keep it?](#hybrid-nav))\n\n<table markdown=\"1\"><tr>\n<td>To get this navigation,</td>\n<td>create the file <b>SUMMARY.md</b>:</td>\n<td>(old YAML equivalent:)</td>\n</tr><tr><td>\n\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</td><td>\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</td><td>\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```\n\n</td></tr></table>\n\nIMPORTANT: The nav file must be put inside the [`docs` directory][docs_dir] -- at the root of it.\n\nSo, the plugin lets you specify your site's navigation with lists of links that are parsed according to normal Markdown rules.\n\nNote that, the way we wrote the Markdown, a section seems to also have a page associated with it. MkDocs doesn't actually support that, and neither is it representable in YAML directly, so the plugin tries to do the next best thing: include the link as the first page of the section. However, this structure is perfectly suited for the *[section-index][]* plugin, which actually makes that work. Or you could just *not* associate a link with sections:\n\n<table markdown=\"1\"><tr>\n<td>To get this navigation,</td>\n<td>create the file <b>SUMMARY.md</b>:</td>\n<td>(old YAML equivalent:)</td>\n</tr><tr><td>\n\n* [Frob](#index.md)\n* [Baz](#baz.md)\n* Borgs\n * [Bar](#borgs/bar.md)\n * [Foo](#borgs/foo.md)\n\n</td><td>\n\n```markdown\n* [Frob](index.md)\n* [Baz](baz.md)\n* Borgs\n * [Bar](borgs/bar.md)\n * [Foo](borgs/foo.md)\n```\n\n</td><td>\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs:\n - Bar: borgs/bar.md\n - Foo: borgs/foo.md\n```\n\n</td></tr></table>\n\n**[See syntax details about literate nav files.](https://oprypin.github.io/mkdocs-literate-nav/reference.html)**\n\nYou can find more examples of the \"literate nav\" syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav).\n\n### Nav cross-link\n\nBut why stop there? Each directory can have its own decoupled navigation list (see how the trailing slash initiates a nav cross-link):\n\n<table markdown=\"1\"><tr>\n<td>To get this navigation,</td>\n<td>create the file <b>SUMMARY.md</b>:</td>\n<td>(old YAML equivalent:)</td>\n</tr><tr><td rowspan=\"3\">\n\n* [Frob](#index.md)\n* [Baz](#baz.md)\n* Borgs\n * [Bar](#borgs/bar.md)\n * [Foo](#borgs/foo.md)\n\n</td><td>\n\n```markdown\n* [Frob](index.md)\n* [Baz](baz.md)\n* [Borgs](borgs/)\n```\n\n</td><td rowspan=\"3\">\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs:\n - Bar: borgs/bar.md\n - Foo: borgs/foo.md\n```\n\n</td></tr><tr>\n<td>and the file <b>borgs/SUMMARY.md</b>:</td>\n</tr><tr><td>\n\n```markdown\n* [Bar](bar.md)\n* [Foo](foo.md)\n```\n\n</td></tr></table>\n\n> NOTE: The nav file in the subdirectory is picked up *only* because its directory is explicitly mentioned in a parent nav file. **SUMMARY.md** (generally [`nav-file`](customizing-nav_file)) files are **not** picked up implicitly (only the root nav file is \"implicit\").\n>\n> So you might say that the nav construction approach is exactly the opposite from the *[awesome-pages][]* plugin.\n>\n> That said, an [inferred cross-linked directory](#inferred-sub-directory) (whether directly or through [wildcards](#wildcards)) gets resolved recursively, so that way you actually go back to implicit resolution.\n\n#### Inferred sub-directory\n\nOr perhaps you don't care about the order of the pages under the **borgs/** directory? Just drop the file __borgs/SUMMARY.md__ and let it be inferred (recursively, if applicable). For our particular example, the final result would be the same.\n\nThe fallback behavior follows the [default behavior of MkDocs when nav isn't specified][mkdocs-nav], except that you can leave out only some directory trees, rather than an all-or-nothing choice.\n\n### Wildcards\n\nBetween the two extremes of entirely specifying a nav and entirely inferring it, there's the option of applying wildcards.\n\nInstead of putting links like `[Foo 1](foo_1.md)`, `[Foo 2](foo_2.md)` into the nav list, you can write a wildcard item: `foo_*.md` (bare, not as a link). The asterisk indicates that any number of characters can go there, and the file name has to match the rest of the pattern.\n\nA wildcard item is always required to have at least one `*` asterisk in it, because if it doesn't, then it's *just* a bare item, which are disallowed.\n\n**[See details about wildcards.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#wildcards)**\n\nSo this can be used to fully specify order for items that matter and apply wildcards for all other cases. Example:\n\n<table markdown=\"1\"><tr>\n<td>By writing this literate nav file,</td>\n<td>you may get a nav like this:</td>\n<td>(assuming the files exist:)</td>\n</tr><tr><td>\n\n```markdown\n- [Welcome](index.md)\n- Usage\n - [Foo](usage/foo.md)\n - usage/*.md\n- */\n- *.md\n- [API docs](api/)\n- [License](license.md)\n```\n\n</td><td>\n\n```yaml\n- Welcome: index.md\n- Usage:\n - Foo: usage/foo.md\n - usage/bar.md\n - usage/baz.md\n- Tips:\n - tips/other-stuff.md\n - tips/stuff.md\n- changelog.md\n- credits.md\n- API docs:\n - api/Foo.md\n - Bar:\n - api/Bar/index.md\n - api/Bar/Baz.md\n- License: license.md\n```\n\n</td><td>\n\n* index.md\n* changelog.md\n* credits.md\n* usage / bar.md\n* usage / baz.md\n* usage / foo.md\n* tips / stuff.md\n* tips / other-stuff.md\n* api / Foo.md\n* api / Bar / index.md\n* api / Bar / Baz.md\n\n</td></tr></table>\n\nTIP: Speaking of API docs... Want to fine-tune file ordering in a large directory tree? Check out [integrations with other plugins](#extras).\n\nThe paths are relative to the directory that the nav file is in. Matching files in subdirectories also works, in both ways: `*/foo.md` and `foo/*.md`.\n\nAs it's impossible for a user to specify the titles of items produced by a wildcard, they have to be inferred, based on [normal rules of MkDocs][mkdocs-nav].\n\n> TIP: The ordering of items matches MkDocs' default, so first go all files, alphabetically (but with the index file first), then all directories. But, as an example, you could actually swap that, by writing:\n>\n> ```markdown\n> - */\n> - *\n> ```\n\nYou can find more examples of the wildcard syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav/wildcard).\n\n### Customizing `nav_file`\n\nWe've been using **SUMMARY.md** as the name of the file that specifies the nav (actually that is also the default value of `nav_file`), but naturally, you can use any other file name.\n\n**[See details about the `nav_file` config.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#nav_file)**\n\nThe plugin takes care to not let MkDocs complain if you don't end up using the nav document as an actual page of your doc site.\n\n#### Show off your nav on the front page\n\nOr maybe you want the opposite -- make the nav page very prominent? You can actually use the index page, **README.md**, for the nav!\n\nWhy would one do this? Well, GitHub (or another source hosting) also displays the Markdown files, and it's quite a nice perk to show off your navigation right in the index page of a directory. Of course, then you'd probably refrain from using [wildcards](#wildcards). [Directory cross linking](#nav-cross-link) still looks great, though.\n\nWhat's that, you ask? If the index page is taken up by navigation, we can't put any other content there, can we? Actually, we can! The nav list can just be put at the bottom of the page that also has whatever other content before that.\n\n[See an example of all this in action](https://github.com/oprypin/crsfml/tree/master/docs/tutorials)\n\n#### Explicit nav mark\n\nIf the plugin is confused where in the document the nav is, or if you want to explicitly put it in a particular location, please precede the Markdown list with this HTML comment (verbatim) on a line of its own:\n\n```html\n<!--nav-->\n```\n\n### Hybrid nav\n\nDo the features of this plugin interest you but you're not on board with the idea of migrating your whole nav?\n\nYou can actually keep using [MkDocs' own nav specification][mkdocs-nav] at the root, *but* defer only some subdirectories to the *literate-nav* plugin. In that case make sure to *not* put a nav file at the [`docs` root][docs_dir], otherwise the native nav will be ignored.\n\n<table markdown=\"1\"><tr>\n<td>To get this navigation,</td>\n<td>put this into <b>mkdocs.yml</b>:</td>\n<td>(old YAML equivalent:)</td>\n</tr><tr><td rowspan=\"3\">\n\n* [Frob](#index.md)\n* [Baz](#baz.md)\n* Borgs\n * [Bar](#borgs/bar.md)\n * [Foo](#borgs/foo.md)\n\n</td><td>\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs: borgs/\n```\n\n</td><td rowspan=\"3\">\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs:\n - Bar: borgs/bar.md\n - Foo: borgs/foo.md\n```\n\n</td></tr><tr>\n<td>& create the file <b>borgs/SUMMARY.md</b>:</td>\n</tr><tr><td>\n\n```markdown\n* [Bar](bar.md)\n* [Foo](foo.md)\n```\n\n</td></tr></table>\n\nThe syntax to defer to a subdirectory, just like [in a literate nav](#nav-cross-link), is to write an item that *ends* with a slash.\n\nNOTE: There is no way to use a YAML nav for a subdirectory, only a literate nav can be deferred.\n\nWildcards also work very similarly.\n\n**[See details about syntax additions for MkDocs native nav.](https://oprypin.github.io/mkdocs-literate-nav/reference.html#mkdocs-native-nav)**\n\nYou can find examples of the hybrid nav syntax [in the testcases directory](https://github.com/oprypin/mkdocs-literate-nav/tree/master/tests/nav/hybrid).\n\n#### MkDocs native nav with inferred subdirectories\n\nAs before, whenever you have the option of using a literate nav file for a sub-directory, you can also *not* put any nav file there and infer the sub-directory instead. So, *not* creating the file **borgs/SUMMARY.md** would have yielded the same result in the above example.\n\nSo basically, you can use the *literate-nav* plugin just for its ability to infer only sub-directories, without ever writing any actual \"literate navs\".\n\n#### Details about hybrid nav\n\nAs a final example, note that there are two ways to include a subdirectory, with significant difference:\n\n<table markdown=\"1\"><tr>\n<td>To get this navigation,</td>\n<td>put this into <b>mkdocs.yml</b>:</td>\n<td>To get this navigation,</td>\n<td>put this into <b>mkdocs.yml</b>:</td>\n</tr><tr><td>\n\n* [Frob](#index.md)\n* [Baz](#baz.md)\n* Borgs\n * [Bar](#borgs/bar.md)\n * [Foo](#borgs/foo.md)\n\n</td><td>\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - Borgs: borgs/\n```\n\n</td><td>\n\n* [Frob](#index.md)\n* [Baz](#baz.md)\n* [Bar](#borgs/bar.md)\n* [Foo](#borgs/foo.md)\n\n</td><td>\n\n```yaml\nnav:\n - Frob: index.md\n - Baz: baz.md\n - borgs/*\n```\n\n</td></tr></table>\n\nSo, a directory item with a title becomes a section titled as such. And a wildcard (which can't have a title specified) gets inlined into the existing section. This simple example has no sub-sub-directories, but the relative subdirectory structure would be preserved in both cases if it did.\n\n### Extras\n\n#### Programmatic control over the nav\n\nLet's say you need the ability to infer nav for a sub-directory, but are unhappy with the default naming/layout behavior, and you don't want to write all that out manually either. Then, definitely check out the ***[gen-files][]* plugin**. Its normal usage is to programmatically add files to the site during the build, but that also includes literate nav files! Moreover, you don't even have to teach your program to write Markdown. There's a more direct integration: `mkdocs_gen_files.Nav.build_literate_nav`.\n\n[See an example that generates both the files and the navigation covering them](https://github.com/mkdocstrings/mkdocstrings/blob/5802b1ef5ad9bf6077974f777bd55f32ce2bc219/docs/gen_doc_stubs.py#L25).\n\n#### Indent lists by 2 spaces, not 4\n\nConfigure it through [tab_length](https://oprypin.github.io/mkdocs-literate-nav/reference.html#tab_length) or [markdown_extensions](https://oprypin.github.io/mkdocs-literate-nav/reference.html#markdown_extensions)\n\n#### Migrating from GitBook?\n\nIt might be very easy! Just beware of the stricter Markdown parser; it will *not* accept 2-space indentation for sub-lists.\n\nAnd use this for **mkdocs.yml**:\n\n<table><tr><td>\n\n```yaml\nuse_directory_urls: false\n```\n```yaml\nplugins:\n - search\n - same-dir\n - section-index\n - literate-nav:\n nav_file: SUMMARY.md\n```\n\n</td><td>\n\n```yaml\ntheme:\n name: material\n```\n```yaml\nmarkdown_extensions:\n - pymdownx.highlight\n - pymdownx.magiclink\n - pymdownx.superfences\n```\n\n</td></tr></table>\n\n\n\n[mkdocs-nav]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation\n[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs plugin to specify the navigation in Markdown instead of YAML",
"version": "0.6.1",
"project_urls": {
"Documentation": "https://oprypin.github.io/mkdocs-literate-nav/",
"History": "https://github.com/oprypin/mkdocs-literate-nav/releases",
"Issues": "https://github.com/oprypin/mkdocs-literate-nav/issues",
"Source": "https://github.com/oprypin/mkdocs-literate-nav"
},
"split_keywords": [
"mkdocs",
"mkdocs-plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "513be00d839d3242844c77e248f9572dd34644a04300839a60fe7d6bf652ab19",
"md5": "cc23329179a0ab93b17f2eeba1efb63b",
"sha256": "e70bdc4a07050d32da79c0b697bd88e9a104cf3294282e9cb20eec94c6b0f401"
},
"downloads": -1,
"filename": "mkdocs_literate_nav-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc23329179a0ab93b17f2eeba1efb63b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13182,
"upload_time": "2023-09-10T22:17:18",
"upload_time_iso_8601": "2023-09-10T22:17:18.751200Z",
"url": "https://files.pythonhosted.org/packages/51/3b/e00d839d3242844c77e248f9572dd34644a04300839a60fe7d6bf652ab19/mkdocs_literate_nav-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4df9c48a04f3cf484f8016a343c1d7d99c3a1ef01dbb33ceabb1d02e0ecabda7",
"md5": "588e658a0b02bbdb7ea324e7a596defe",
"sha256": "78a7ab6d878371728acb0cdc6235c9b0ffc6e83c997b037f4a5c6ff7cef7d759"
},
"downloads": -1,
"filename": "mkdocs_literate_nav-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "588e658a0b02bbdb7ea324e7a596defe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16437,
"upload_time": "2023-09-10T22:17:16",
"upload_time_iso_8601": "2023-09-10T22:17:16.815748Z",
"url": "https://files.pythonhosted.org/packages/4d/f9/c48a04f3cf484f8016a343c1d7d99c3a1ef01dbb33ceabb1d02e0ecabda7/mkdocs_literate_nav-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-10 22:17:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oprypin",
"github_project": "mkdocs-literate-nav",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-literate-nav"
}
