Add priority option

[percevalw]

Hi,

This PR addresses the need for priority handling when a heading title appears several times throughout the site. The new priority parameter can be set to decide which page will be linked in such cases.

From the updated README:

If a heading title that appears several times throughout the site, set the priority parameter to decide which page will be linked. The priority list follows the gitignore syntax and is tested in reverse: each anchor will be assigned the lowest priority amongst all of its matches.

plugins:
  - search
  - autorefs:
    priority:
      - '*' # priority to all files
      - reference # except reference/... files 

Let me know if these changes work for you.

[pawamoy]

Hello, thanks for the PR!

Note that it is generally better to open an issue first, so we can discuss the feature request. It's more respectful of both maintainers and contributors time.

I'll try to review your PR and the issue/idea behind it as soon as possible 🙂

[pawamoy]

Hey @percevalw, we just merged #39 which allows to define aliases above headings. With this feature, even if you have the same heading appearing in multiple pages, you can set a unique alias that points to it. I believe that almost entirely solves the use-case described here. The only thing that is maybe not solved is the case where the headings are generated by other plugins/extensions and you don't have control over them. In mkdocstrings case, we will be able to use these new aliases to solve this issue too.