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.
Pay now to fund the work behind this issue.
Get updates on progress being made.
Maintainer is rewarded once the issue is completed.
You're funding impactful open source efforts
You want to contribute to this effort
You want to get funding like this too