configuration of mkdocs 'nav' entries has issues

[PanRe]

First of all thanks for this awesome project! I was really looking for something like this!

I found a couple of issues concerning the configuration of mkdocs. If i add the following configuration to the pyproject.toml file:

nav = ["docs/index.md", "docs/page2.md"]

i get kind of the desired result. There are two issues coming up if i do this:

1. The very first page is see (when rendering the pages by "portray in_browser") is the rendered page of my README.md file (although i did not list it in nav)! If i navigate to a different page, this first README page is not reachable any more as there is, as desired, no link to README in the navigation bar on the left.

2. The reference entry in the navigation bar, which usually contains the API documentation, is missing completely. Do i need to do some extra configs in order to get it again?

Concerning the 'nav' entry, there is an additional problem. Originally mkdocs uses a .yml file for its configuration. In yaml, it is valid to have a list (array) of mixed types e.g.:

nav:
- Overview: index.md
- page2.md

which is a list of a key-value type and a string type. mkdocs uses this as the keys in the array are used to name the pages generated. In this example, index.md would be named 'Overview' and page2 would be name either as page2 or like the caption defined in page two (if any given).

Right now, the only format which is accepted by portray is to give a list of strings (as done above). Thus it is not possible to name your pages differently. In TOML you would need to accept something like

nav = {Overview = "index.md", ABC = "page2.md"}

which is a list of key-value pairs.

The problem is, that TOML does not allow for mixed types in arrays (up to my knowledge, please correct me if i am wrong about this). Thus, you would need two lists in the pyproject.toml file, one as a plain list of strings and one as key-value pair, to achieve the same functionality as possbile with the .yml file. Or you force the user to go for one of the two possibilities.

Anyway, i really would like to use this functionality!
Thanks in advance!

[timothycrosley]

Hi @PanRe,

Thanks for reaching out! I've done my best to address this in the just released 1.3.0 release of portray. You can see documentation on how to set the navigation, including nesting, under the updated configuration quick start.

Let me know if you think this should be further addressed in any way.

Thanks!

~Timothy

[PanRe]

Hi Timothy,

Thanks a lot! I read through your docs and this sections covers all neatly. I just would add a link to the toml GitHub doc since this nested list of tables may shock people new to toml. (just an idea). Otherwise thumbs up!

[timothycrosley]

Hi @PanRe,

Thanks for reading it over :). Good call! I've updated the documentation to directly link to the TOML documentation you shared

Thanks!

~Timothy

[PanRe]

Perfect! Nice work!