Understanding links with mkdocs and autoref

[mdbenito]

I don't know about everybody else, but I'm having a bit of trouble elucidating the rules for linking with autorefs. I guess I'm confused by what plugins we have and what they do, and where.

Markdown links are clear, e.g. link to local file with [this type of link](other-file#anchor)

In principle one can link to most things with [this type of link][unique anchor], but I'm not sure what counts as a unique-anchor.

For instance, auto-anchors do not work for all headings, but they seem to work for the title of a page

Let's say I have a file influence/index.md with:

---
title: The influence function
alias:
  name: influence-function
  text: Computing Influence Values
---

# The influence function

## Some section { #special-anchor }

Blah blah

Autoref to the H1 in that file inside a docstring takes preference over aliases of all kinds, including file names. Of all these, only the first works:

	[The Influence function][the-influence-function]
	[The Influence function][influence-function]
	[The Influence function][influence]

Inside docstrings, none do: double brackets do not work for refs to markdown files:

	[[the-influence-function]]
	[[influence-function]]
	[[influence]]

However, inside markdown files double brackets work with:

	[[influence-function]]

But not with:

	[[the-influence-function]]

Autoref to the H2 does not work with

	[[special-anchor]]
	[[some-section]]

[AnesBenmerzoug]

There seems to be quite a bit confusion about how the links works. Let me try to clarify things a bit:

• As you said, markdown links work exactly as expected so there is no issue there.
• We use mkdocs-alias to create aliases for pages defined in the frontmatter and use the syntax [[<alias>]] or [[<alias>|link title]] to link to them and this works, at least for me, exactly as expected.
• We also use mkdocs-autorefs that:
  • generates anchors for each heading but there is a risk of collision between anchors if the headings are not unique. Given a heading # Heading Example 1, we would link to it using the syntax [Link Title][heading-example-1]
  • and supports defining markdown anchors with the syntax ## Some section { #special-anchor } and then linking to them using [Link Title][special-anchor]. This is a newer feature of this plugin that I did not know about (it was added as part of version 1.0.0 released in 2024-02-27)

Inside docstrings nothing works because of mkdocstrings and not because of the plugins. When it processes the files that refer to code, it renders them directly to HTML. it skips the step that renders them as an intermediate representation that would allow other plugins to to modify them before the final conversion (See this issue for more details). See the mkdocs events for more details on how it works internally.

I noticed that you seemed confused in your last big PR related to documentation but I assumed that there was indeed something wrong with the plugins. But now I think it was just confusion about the different linking methods supported by mkdocs which I agree can be confusing if you're not used to it and if it isn't clearly documented anywhere.

I hope this clears things up.

[mdbenito]

It totally does, thanks so much. So, rule of thumb: do not use double brackets. Which makes me wonder: do we need mkdocs-alias? 😄

[AnesBenmerzoug]

I don't think it gets in the way. It has its uses and it doesn't get in the way. I think using aliases is better than defining anchors everywhere.

[mdbenito]

Just a short update / clarification. At least as of mkdocstrings 0.27.0 and mkdocs-autorefs 1.3.0, linking to markdown anchors defined as ## Some section { #special-anchor } from within a docstring does work. 🤷🏽