How to Create Href Links to a Group Page?

[K4zoku]

Description

Linking to an entry on the same page is straightforward: just use #target. Linking to an entry on another page is also simple: another_page.md#target. However, when the target is inside a group (e.g., example_group), I am unsure how to create the link.

Things Tried

1. example_group#target

   • Did not work because it navigates to current_page/example_group#target.

2. /example_group/target_page.md#target

   • Did not work because MkDocs does not automatically replace target_page.md with the corresponding page.

3. Relative paths (e.g., ../example_group/target_page#target or ../example_group/#target for index.md)

   • Works but requires writing paths based on the structure of the MkDocs build output, which is inconvenient.

Request

How can I correctly link to a specific target inside a group in MkDocs without relying on the build output structure?

Thank you!

[lawmurray]

Good question @K4zoku, I agree this one is a bit of a nuisance, MkDocs has some implicit rules for links that are a little unintuitive to me.

You can use absolute links as you have in point 2, just link as if the file is a directory, as is the final published URL, rather than the .md file, so /example_group/target_page/#target will work in your case I think. The downside of this is that MkDocs may issue a warning about the link, even though it will work.

Otherwise use a relative path as in 3, but I agree that it's inconvenient to have to work out how the final output is structured.

Longer term, adding a @command for this may be the way to go. If Doxygen has any such thing already then basing it off that, for compatibility, would be ideal. Always open to contributions like that if it interests you.