Problem with nav when using ../ and ../sibling

[habazut]

My .nav.yml (deep down in my docu tree) looks like:

nav:
  - Up: ../
  - Sibling: ../sibling/

Which results in

WARNING - A reference to '../' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING - A reference to '../sibling/' is included in the 'nav' configuration, which is not found in the documentation files.

The directories ../ and ../sibling exist.

For fun I tested as well:

  - Myself: ./

Which resulted in the rebuild of mkdocs serve crashing with a really long Traceback and

ERROR - [11:52:22] An error happened during the rebuild. The server will appear stuck until build errors are resolved.

So this is clearly pointing into the direction of one or several bugs in the handling of ./ and ../.

As there is an example with ../ in the documentation I'd expected that to work, it is a useful feature to have relative path. ../sibling/file.md does not work either.

Look like Up points to the document-root (instead of one level up) and Sibling points to document-root/sibling instead of the sibling of the current path which both are wrong.

$ cat requirements.txt 
mkdocs==1.6.1
mkdocs-awesome-nav==3.3.0
mkdocs-git-revision-date-localized-plugin==1.4.7
mkdocs-material==9.6.14
mkdocs-open-in-new-tab==1.0.8
mkdocs-rss-plugin==1.17.3
pymdown-extensions==10.15
python-frontmatter==1.1.0
setuptools==80.9.0

If needed I can prepare a branch of our docu repo which shows this in detail.

Regards,
Harald.

[lukasgeiter]

awesome-nav is currently unable to resolve paths with upwards traversal. That means paths like ../ and ../sibling/ end up as-is in the navigation structure of mkdocs. In other words, it's as if you had written it in the nav entry of mkdocs.yml.

I see that the example in the docs can be misleading. What I had in mind was an mkdocs site that is hosted under a path like example.com/docs. The link ../ would then lead to the main site example.com.

What is your use case for wanting to link to parent and sibling pages in the navigation?

[habazut]

currently unable to resolve paths with upwards traversal

Not exited about that. Please fix. You will have to revisit that code anyway so that you don't crash and burn with ./. If you don't plan to accept ../ in links in the future, please give a proper error message.

What is your use case for wanting to link to parent and sibling pages in the navigation?

Is that not obvious?

Typically the document tree gets very deep with time and if you reorganize you have to revisit all absolute path names, for example
if you have:

doc/product/product01/manual 
doc/product/product01/drivers

Then you would like to have ../drivers in manual so that if you in one year rename

doc/product/product01 -> doc/product/discontinued/product01

you don't have to revisit all of product01.

Just one example. Same reason why both absolute and relative links exist in HTML, even pointing up. What would HTML be without such links?

Regards,
Harald.

[lukasgeiter]

I'm not asking why you want relative instead of absolute links. I would like to understand why you want the navigation of one of your sections to link to another section. I can only help you if I understand your use case. The more realistic the example, the better (file structure + how you want the navigation to look).

Is this about ease of navigation and you want the same relative links everywhere? (e.g. an "Up" link). In that case, adding those links to the navigation structure is the wrong approach. That's something that should be implemented on the templating level, for example using the breadcrumbs feature of mkdocs-material.

[Asbelos]

I simply wanted the same page to appear in both siblings navigators.

Everywhere else ( links , images, os files etc) the ../ means up one level and / means start from top. It seems gratuitous and confusing that the meaning suddenly changes in the nav.

[lukasgeiter]

I simply wanted the same page to appear in both siblings navigators.

Referencing the same page multiple times in the navigation is not well supported by mkdocs. I suggest you add a relative link to the page content instead.

[tomaszalusky]

Well, you asked for use case, here is mine (simplified, I ran into similar problem and found this issue):

Project setup

I have project with 3 subprojects: application_project, etl_project (loads data for application) and doc_project. Each subproject has its own mkdocs documentation for good reasons - documentation is as close as possible to code, doc_project's purpose is both of providing general documentation and collecting subprojects' documentation using multirepo plugin (which essentially merges content of their docs directories under doc_project/docs directory using temporary copy).

I try to describe the structure mimicking the great syntax which is used in project tests:

doc_project/
	docs/
		intro.md
		mkdocs.yml
		| ...
		| plugins:
		|   multirepo:
		|     repos:
		|       - section: etl
		|         import_url: 'https://git.intranet/etl_project'
		|       - section: application
		|         import_url: 'https://git.intranet/application_project'
		.nav.yml
		| - nav:
		|   - intro.md
		|   - Application: application

etl_project/
	docs/
		data/
			model.md

application_project/
	docs/
		business-logic/
			description.md
		.nav.yml
		| - nav:
		|   - data: ../etl_project/data
		|   - Business logic: business-logic

Menu requirement

The key point is, the structure of documentation tree is specified by user (according to what is friendly to him) rather than developer. User is not aware of technical fragmentation to subprojects, he just wants data model to be documented as part of the application.
User wants to get the menu which looks like this:

- Intro
- Application
    - Data
        - etl_project/data/model.md
    - Business logic
        - application_project/business-logic/description.md

Notice the expression ../etl_project/data in application_project's .nav.yml - it essentially says: "please build me a menu here from this part of project", which I find useful. But it does not work.
(I assume the documentation is built in context of superior project - if the application_project documentation were built independently, the link would be broken, which is OK.)

Workaround

Unroll necessary parts of application_project documentation into doc_project's .nav.yml menu at multiple levels (tried and proved):

.nav.yml
| - nav:
|   - intro.md
|   - Application:
|     - Data: etl/data
|     - Business logic: application/business-logic

Drawbacks:

• duplication of Application node in doc_project
• violating the decentralization philosophy of awesome-nav plugin

Conclusion

I can live with these drawbacks at the moment (the real case is not much more complicated) hence the workaround is sufficient for me. Anyway the request itself looks legitimate however the correct implementation would be probably harder than it seems at first glance. It would have to check and deal with attempts of adding cycles into menu tree (@habazut 's example with ./ path is just trivial instance of such problem).

[lukasgeiter]

@tomaszalusky thanks for the detailed description of your use case. This plugin, and I would argue mkdocs as a whole, is built around the idea that the navigation structure follows the file structure. That said, I understand that in some scenarios that is not possible or not desired because the documentation lives alongside other files.

You are correct in pointing out that a correct implementation is not that easy as we have to avoid cycles. Another challenge is the fact that mkdocs doesn't like the same page appearing twice in the navigation. Adding upwards traversal complicates the algorithm that decides in which order navigation entries need to be processed to get predictable results.