Package: docums-literate-nav
docums-literate-navPluginforDocumsto specify the navigation in Markdown instead of YAMLpipinstalldocums-literate-navUsageActivate the plugin indocums.yml:plugins:-search-literate-nav:nav_file:SUMMARY.mdanddropthenavsection if it's present there; it will be ignored now. (Unless you want to keep it?)To get this navigation,create the fileSUMMARY.md:(old YAML equivalent:)FrobBazBorgsBarFoo*[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.mdIMPORTANT: The nav file must be put inside thedocsdirectory-- 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. Docums 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 justnotassociate a link with sections:To get this navigation,create the fileSUMMARY.md:(old YAML equivalent:)FrobBazBorgsBarFoo*[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.mdNav cross-linkBut why stop there? Each directory can have its own decoupled navigation list (see how the trailing slash initiates a nav cross-link):To get this navigation,create the fileSUMMARY.md:(old YAML equivalent:)FrobBazBorgsBarFoo*[Frob](index.md)*[Baz](baz.md)*[Borgs](borgs/)nav:-Frob:index.md-Baz:baz.md-Borgs:-Bar:borgs/bar.md-Foo:borgs/foo.mdand the fileborgs/SUMMARY.md:*[Bar](bar.md)*[Foo](foo.md)NOTE: The nav file in the subdirectory is picked uponlybecause its directory is explicitly mentioned in a parent nav file.SUMMARY.md(generallynav-file) files arenotpicked 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, aninferred cross-linked directory(whether directly or throughwildcards) gets resolved recursively, so that way you actually go back to implicit resolution.Inferred sub-directoryOr perhaps you don't care about the order of the pages under theborgs/directory? Just drop the fileborgs/SUMMARY.mdand let it be inferred (recursively, if applicable). For our particular example, the final result would be the same.The fallback behavior follows thedefault behavior of Docums when nav isn't specified, except that you can leave out only some directory trees, rather than an all-or-nothing choice.WildcardsBetween 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'sjusta bare item, which are disallowed.So this can be used to fully specify order for items that matter and apply wildcards for all other cases. Example:By writing this literate nav file,you may get a nav like this:(assuming the files exist:)-[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.mdindex.mdchangelog.mdcredits.mdusage / bar.mdusage / baz.mdusage / foo.mdtips / stuff.mdtips / other-stuff.mdapi / Foo.mdapi / Bar / index.mdapi / Bar / Baz.mdTIP: Speaking of API docs... Want to fine-tune file ordering in a large directory tree? Check outintegrations 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.mdandfoo/*.md.As it's impossible for a user to specify the titles of items produced by a wildcard, they have to be inferred, based onnormal rules of Docums.TIP: The ordering of items matches Docums' 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:-*/-*Customizingnav_fileWe've been usingSUMMARY.mdas the name of the file that specifies the nav (actually that is also the default value ofnav_file), but naturally, you can use any other file name.The plugin takes care to not let Docums 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 pageOr 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 usingwildcards.Directory cross linkingstill 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 actionExplicit nav markIf 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 navDo 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 usingDocums' own nav specificationat the root,butdefer only some subdirectories to theliterate-navplugin. In that case make sure tonotput a nav file at thedocsroot, otherwise the native nav will be ignored.To get this navigation,put this intodocums.yml:(old YAML equivalent:)FrobBazBorgsBarFoonav:-Frob:index.md-Baz:baz.md-Borgs:borgs/nav:-Frob:index.md-Baz:baz.md-Borgs:-Bar:borgs/bar.md-Foo:borgs/foo.md& create the fileborgs/SUMMARY.md:*[Bar](bar.md)*[Foo](foo.md)The syntax to defer to a subdirectory, just likein a literate nav, is to write an item thatendswith 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.Docums native nav with inferred subdirectoriesAs before, whenever you have the option of using a literate nav file for a sub-directory, you can alsonotput any nav file there and infer the sub-directory instead. So,notcreating the fileborgs/SUMMARY.mdwould have yielded the same result in the above example.So basically, you can use theliterate-navplugin just for its ability to infer only sub-directories, without ever writing any actual "literate navs".Details about hybrid navAs a final example, note that there are two ways to include a subdirectory, with significant difference:To get this navigation,put this intodocums.yml:To get this navigation,put this intodocums.yml:FrobBazBorgsBarFoonav:-Frob:index.md-Baz:baz.md-Borgs:borgs/FrobBazBarFoonav:-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.ExtrasProgrammatic control over the navLet'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:docums_gen_files.Nav.build_literate_nav.Indent lists by 2 spaces, not 4Configure it throughtab_lengthormarkdown_extensionsMigrating from GitBook?It might be very easy! Just beware of the stricter Markdown parser; it willnotaccept 2-space indentation for sub-lists.And use this fordocums.yml:use_directory_urls:falseplugins:-search-same-dir-section-index-literate-nav:nav_file:SUMMARY.mdtheme:name:materialmarkdown_extensions:-pymdownx.highlight-pymdownx.magiclink-pymdownx.superfences