links to other doc pages are not working as expected

[meleu]

Hi,

I've been using mkdocs-material since 2018 and I'm really grateful with all the nice work being done here.

Currently I'm working to update my mkdocs.yml in order to use the new version of mkdocs-material and add some automation to build my documentation site. Thanks to the upgrade guide I was able to upgrade it.

However I'm now facing an issue. Let's say I have a nav like this:

# NOTE: all .md files are in the same directory (no subdirs)
nav:
  - FirstTab:
    - home.md
    - subsection:
      - subsection-page.md

In home.md I have a link like this:

Here's a [link to the subsection page](subsection-page).

In the old version of mkdocs-material, the generated link points to subsection-page/.

In the current version of the generated link is pointing to home/subsection-page.

In the screenshots below you can seed the difference.

Expected behavior

This one was created with an old version of mkdocs-material (and can be seen alive here):

Current behavior

This one was created with the mkdocs-material container image available in the Docker Hub (and can be seen alive here):

---

Is this a bug or am I missing something in the configs

[squidfunk]

It's likely some configuration issue as I haven't seen anything like this before. However, it's much easier to help you if you could narrow the problem down and provide a minimal reproducible case on a mint Material for MkDocs installation.

[meleu]

I've created a minimum reproducible case in this repo: https://github.com/meleu/docs-debug

steps to reproduce:

git clone https://github.com/meleu/docs-debug
cd docs-debug/
# check the mkdocs.yml
docker container run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build

Now, inside the site/ dir, every index.html file that is inside a subdirectory, when they have a link to another pages, they are not linked to ../Another-Page. Instead, they are linked to Another-Page, meaning that it actually goes to Current-Page/Another-Page.

I'm starting to wonder if it's a problem in the upstream, specifically with the use_directory_urls option...

In the README of that repo there's a detailed explanation of the problem.

[squidfunk]

Does this also happen with the default MkDocs theme?

[meleu]

Yeah, it's happening with the default theme too... I'm gonna check if there's an open issue for it in the mkdocs repo.

Here's the generated line: https://github.com/meleu/docs-debug/blob/master/no-material-site/Home-pt_BR/index.html#L123

I used this config file and built the site with

mkdocs build -f no-material-mkdocs.yml

[squidfunk]

Thanks for checking! If it happens with the default theme, it’s an issue with MkDocs itself, not Material for MkDocs 😊

[waylan]

In home.md I have a link like this:

Here's a [link to the subsection page](subsection-page).

As explained in the documentation, you much link to the md page. MkDocs will then properly convert the link for you. Therefore you link should be:

Here's a [link to the subsection page](subsection-page.md).

[meleu]

Thanks for checking @waylan !

I confirm that using the trailing .md makes it work as expected.

But now I'm curious to know why it worked fine without the trailing .md in the past but it's not working anymore.

My "fancy-doc-generation-pipeline" involves getting the pages from a github wiki as input and then generate the documentation site (I do it this way to make it easier to get contributions from non-programmers).

In the wiki we can use links like this: [Some Page](Some-Page).

I implemented such method in 2018 and it worked fine, but I never touched my code neither updated mkdocs/material-theme since then.

By the way, while googling about my issue I've found that @cmitu implemented this: https://github.com/cmitu/mkdocs-altlink-plugin

It'll probably solve my problem.