mkdocs-literate-nav

Plugin for MkDocs to specify the navigation in Markdown instead of YAML

pip install mkdocs-literate-nav

Works well with section-index and gen-files. Supplants awesome-pages.

Usage

Activate the plugin in mkdocs.yml:

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

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

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

IMPORTANT: The nav file must be put inside the docs directory -- 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:

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

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

See syntax details about literate nav files.

You can find more examples of the "literate nav" syntax in the testcases directory.

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

* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/)

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

* [Bar](bar.md)
* [Foo](foo.md)

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) 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 (whether directly or through 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, 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.

So this can be used to fully specify order for items that matter and apply wildcards for all other cases. Example:

- [Welcome](index.md)
- Usage
    - [Foo](usage/foo.md)
    - usage/*.md
- */
- *.md
- [API docs](api/)
- [License](license.md)

- 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

TIP: Speaking of API docs... Want to fine-tune file ordering in a large directory tree? Check out integrations with other plugins.

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.

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:

- */
- *

You can find more examples of the wildcard syntax in the testcases directory.

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.

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. Directory cross linking 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

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:

<!--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 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, otherwise the native nav will be ignored.

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs: borgs/

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

* [Bar](bar.md)
* [Foo](foo.md)

The syntax to defer to a subdirectory, just like in a literate nav, 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.

You can find examples of the hybrid nav syntax in the testcases directory.

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:

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs: borgs/

nav:
  - Frob: index.md
  - Baz: baz.md
  - borgs/*

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.

Indent lists by 2 spaces, not 4

Configure it through tab_length or 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:

use_directory_urls: false

plugins:
  - search
  - same-dir
  - section-index
  - literate-nav:
      nav_file: SUMMARY.md

theme:
  name: material

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.magiclink
  - pymdownx.superfences