search

mkdocstrings / autorefs

Automatically link across pages in MkDocs.
https://mkdocstrings.github.io/autorefs/
ISC License
50 stars 7 forks source link

bug: Problems linking to generated targets #58

Open pekkaklarck opened 4 hours ago

pekkaklarck commented 4 hours ago

I might be submitting this to a wrong project, but because I don't know any better place, and this is at least related to autorefs, I decided to submit it here. Feel free to close this if the place is wrong. If you know a better place, please let me know.

Let's first assume I have the following content:

# Welcome

## Just testing

When I have autorefs installed, I can very conveniently link to the Welcome section using this syntax:

This is a link to the [welcome][] section.

This is very similar, and equally convenient, than the syntax I'm used to with reStructuredText and Sphinx:

This is a link to the `welcome`_ section.

The problem is that I'd typically like to refer to sections so that the name starts with a capital letter as below, but in this case auto-linking doesn't work:

This is a link to the [Welcome][] section.

There's also a problem with headings having spaces. For example, this doesn't work:

I'm [just testing][].

I know I can get both of the above to work by including the actual link target as below:

This is a link to the [Welcome][welcome] section. I'm [just testing][just-testing].

The problem with adding those link targets is that it requires writing redundant content, makes document source less readable and is inconsistent. Inconsistency also means you can easily forget to add the target when in some cases it is not needed. Notice that with reStructuredText and Sphinx these work out-of-the-box:

This is a link to the `Welcome`_ section. I'm `just testing`_.

My first problem that [Welcome][] isn't handled case-insensitively feels like a bug to me, because according to the original Markdown spec, reference targets are case-insensitive. There is, for example, an example like this:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

The odd thing is that the above example is handled fine by MkDocs. It's strange that [Google][] works when the references target is [google]:, but [Welcome][] doesn't work when the reference target ought to be something similar.

My second problem that [just testing][] is not linked to the generated just-testing target is something where my wish is against the Markdown spec. This example from the spec wouldn't work if spaces would be automatically replaces with hyphens:

Visit [Daring Fireball][] for more information.

[Daring Fireball]: http://daringfireball.net/

Although I'm fighting against the spec, I feel that this syntax would be really convenient. Is it something autorefs could support? If there are backwards compatibility concerns, it didn't need to be enabled by default, but having an option to enable this behavior would be awesome. If this is something autorefs cannot do or it doesn't belong to its scope, do you have ideas how I could enable the behavior otherwise? I'm willing to implement a plugin if needed and would also be ready to provide a PR to autorefs if this feature could be added to it.

pawamoy commented 4 hours ago

Thank you for the bug report / feature request @pekkaklarck, I think it makes a lot of sense. We can definitely consider "slugifying" titles when no identifier is provided (and after having tried with the actual title as id, probably). At first glance, this shouldn't cause any issue if we do this by default, but I'll have a deeper look :slightly_smiling_face:

pekkaklarck commented 2 hours ago

That would be awesome! And yes, should first check is there a match with the original title before sluggifying.