Book-links in secondary navigation #1

New issue

Closed

opened 2020-02-05 06:52:32 +00:00 by liska · 0 comments

liska commented

2020-02-05 06:52:32 +00:00

Owner

There is not much use for having links to the subbooks in the primary navigation because that's essentially the same structure you can have with one MkDocs book. However, it can be useful for dependent customized styling, somewhat cleaner coding of the navigation structure (not inside a main mkdocs.yml file), and the possibility of splitting work in separate repositories (contributor privileges).

However, not having the sibling books linked at all (having to go through the main book page to access the other subbooks is not practical and - more important - somewhat confusing.

One solution that makes sense when Material's (?) tabs option is used is to add the sibling links to the secondary navigation (the left column), like so:

"Home"  TL1    TL2    TL3
-------------------------
- L2a
- L2b
  - L3A
- L2c
- "Other Books"
  - "Home"
  - sibling 1
  - sibling 2

Alternatively that block can be inserted at the top of the left column
I'm not sure if "Home" has to be present in that list, or if it should be optional
This has to be inserted in the 2nd-level navigation for each top-level item.
This probably means that the navigation files should not simply be read by lines but parsed as YAML

I'd say this should be done by modifying the link_to_siblings option by understanding more options:

false
top (current behaviour: insert as top-level navigation)
secondary_first
secondary_last

There is not *much* use for having links to the subbooks in the primary navigation because that's essentially the same structure you can have with *one* MkDocs book. However, it can be useful for dependent customized styling, somewhat cleaner coding of the navigation structure (not inside a main `mkdocs.yml` file), and the possibility of splitting work in separate repositories (contributor privileges). However, *not* having the sibling books linked at all (having to go through the main book page to access the other subbooks is not practical and - more important - somewhat confusing. One solution that makes sense when Material's (?) `tabs` option is used is to add the sibling links to the secondary navigation (the left column), like so: ``` "Home" TL1 TL2 TL3 ------------------------- - L2a - L2b - L3A - L2c - "Other Books" - "Home" - sibling 1 - sibling 2 ``` * Alternatively that block can be inserted at the *top* of the left column * I'm not sure if "Home" has to be present in that list, or if it should be optional * This has to be inserted in the 2nd-level navigation for *each* top-level item. * This probably means that the navigation files should not simply be read by lines but parsed as YAML I'd say this should be done by *modifying* the `link_to_siblings` option by understanding more options: * `false` * `top` (current behaviour: insert as top-level navigation) * `secondary_first` * `secondary_last`