.copier-answers.yml

@@ -1,12 +1,12 @@
 # Changes here will be overwritten by Copier
-_commit: 0.16.5
+_commit: 1.2.3
 _src_path: gh:pawamoy/copier-pdm
-author_email: pawamoy@pm.me
+author_email: dev@pawamoy.fr
 author_fullname: Timothée Mazzucotelli
 author_username: pawamoy
 copyright_date: '2019'
 copyright_holder: Timothée Mazzucotelli
-copyright_holder_email: pawamoy@pm.me
+copyright_holder_email: dev@pawamoy.fr
 copyright_license: ISC License
 insiders: false
 project_description: Automatically link across pages in MkDocs.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,61 @@
+---
+name: Bug report
+about: Create a bug report to help us improve.
+title: "bug: "
+labels: unconfirmed
+assignees: [pawamoy]
+---
+
+### Description of the bug
+<!-- Please provide a clear and concise description of what the bug is. -->
+
+### To Reproduce
+<!-- Please provide a Minimal Reproducible Example (MRE) if possible.
+     Try to boil down the problem to a few lines of code.
+     Your code should run by simply copying and pasting it.
+
+     Example:
+
+     ```
+     git clone https://github.com/username/repro
+     cd repro
+     python -m venv .venv
+     . .venv/bin/activate
+     pip install -r requirements.txt
+     ...  # command or code showing the issue
+     ```
+-->
+
+```
+WRITE MRE / INSTRUCTIONS HERE
+```
+
+### Full traceback
+<!-- Please provide the full error message / traceback if any, by pasting it in the code block below.
+     No screenshots! -->
+
+<details><summary>Full traceback</summary>
+
+```python
+PASTE TRACEBACK HERE
+```
+
+</details>
+
+### Expected behavior
+<!-- Please provide a clear and concise description of what you expected to happen. -->
+
+### Environment information
+<!-- Please run the following command in your repository and paste its output below it,
+     redacting sensitive information. -->
+
+```bash
+python -m mkdocs_autorefs.debug  # | xclip -selection clipboard
+```
+
+PASTE OUTPUT HERE
+
+### Additional context
+<!-- Add any other relevant context about the problem here,
+     like links to other issues or pull requests, screenshots, etc.
+-->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+- name: I have a question / I need help
+  url: https://github.com/mkdocstrings/autorefs/discussions/new?category=q-a
+  about: Ask and answer questions in the Discussions tab.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project.
+title: "feature: "
+labels: feature
+assignees: pawamoy
+---
+
+### Is your feature request related to a problem? Please describe.
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]. -->
+
+### Describe the solution you'd like
+<!-- A clear and concise description of what you want to happen. -->
+
+### Describe alternatives you've considered
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+### Additional context
+<!-- Add any other context or screenshots about the feature request here. -->

.github/workflows/ci.yml

@@ -23,13 +23,13 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Fetch all tags
       run: git fetch --depth=1 --tags
 
     - name: Set up PDM
-      uses: pdm-project/setup-pdm@v3
+      uses: pdm-project/setup-pdm@v4
       with:
         python-version: "3.8"
 
@@ -74,10 +74,10 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Set up PDM
-      uses: pdm-project/setup-pdm@v3
+      uses: pdm-project/setup-pdm@v4
       with:
         python-version: ${{ matrix.python-version }}
         allow-python-prereleases: true

.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Fetch all tags
       run: git fetch --depth=1 --tags
     - name: Setup Python

.gitignore

@@ -1,4 +1,5 @@
 .idea/
+.vscode/
 __pycache__/
 *.py[cod]
 dist/

CHANGELOG.md

@@ -5,6 +5,20 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.0.0](https://github.com/mkdocstrings/autorefs/releases/tag/1.0.0) - 2024-02-27
+
+<small>[Compare with 0.5.0](https://github.com/mkdocstrings/autorefs/compare/0.5.0...1.0.0)</small>
+
+### Features
+
+- Add Markdown anchors and aliases ([a215a97](https://github.com/mkdocstrings/autorefs/commit/a215a97a057b54e11ebec8865c64e93429edde63) by Timothée Mazzucotelli). [Replaces-PR-#20](https://github.com/mkdocstrings/autorefs/pull/20), [Related-to-PR-#25](https://github.com/mkdocstrings/autorefs/pull/25), [Related-to-issue-#35](https://github.com/mkdocstrings/autorefs/issues/35), Co-authored-by: Oleh Prypin <oleh@pryp.in>, Co-authored-by: tvdboom <m.524687@gmail.com>
+- Preserve HTML data attributes (from spans to anchors) ([0c1781d](https://github.com/mkdocstrings/autorefs/commit/0c1781d7e3d6bffd55802868802bcd1ec9e8bbc7) by Timothée Mazzucotelli). [Issue-#41](https://github.com/mkdocstrings/autorefs/issues/41), [PR-#42](https://github.com/mkdocstrings/autorefs/pull/42), Co-authored-by: Oleh Prypin <oleh@pryp.in>
+- Support ``[`identifier`][]`` with pymdownx.inlinehilite enabled ([e7f2228](https://github.com/mkdocstrings/autorefs/commit/e7f222894c70627c70e6a14e453a10a81e3f8957) by Oleh Prypin). [Issue-#34](https://github.com/mkdocstrings/autorefs/issues/34), [PR-#40](https://github.com/mkdocstrings/autorefs/pull/40), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+
+### Bug Fixes
+
+- Recognize links with multi-line text ([225a6f2](https://github.com/mkdocstrings/autorefs/commit/225a6f275069bcdfb3411e80d4a7fa645b857b88) by Oleh Prypin). [Issue #31](https://github.com/mkdocstrings/autorefs/issues/31), [PR #32](https://github.com/mkdocstrings/autorefs/pull/32)
+
 ## [0.5.0](https://github.com/mkdocstrings/autorefs/releases/tag/0.5.0) - 2023-08-02
 
 <small>[Compare with 0.4.1](https://github.com/mkdocstrings/autorefs/compare/0.4.1...0.5.0)</small>

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-pawamoy@pm.me.
+dev@pawamoy.fr.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

CONTRIBUTING.md

@@ -44,8 +44,9 @@ on multiple Python versions, you run the task directly with `pdm run duty TASK`.
 The Makefile detects if a virtual environment is activated,
 so `make` will work the same with the virtualenv activated or not.
 
-If you work in VSCode,
-[see examples of tasks and run configurations](https://pawamoy.github.io/copier-pdm/work/#vscode-setup).
+If you work in VSCode, we provide
+[an action to configure VSCode](https://pawamoy.github.io/copier-pdm/work/#vscode-setup)
+for the project.
 
 ## Development
 

Makefile

@@ -2,6 +2,7 @@
 SHELL := bash
 DUTY := $(if $(VIRTUAL_ENV),,pdm run) duty
 export PDM_MULTIRUN_VERSIONS ?= 3.8 3.9 3.10 3.11 3.12
+export PDM_MULTIRUN_USE_VENVS ?= $(if $(shell pdm config python.use_venv | grep True),1,0)
 
 args = $(foreach a,$($(subst -,_,$1)_args),$(if $(value $a),$a="$($a)"))
 check_quality_args = files
@@ -18,7 +19,8 @@ BASIC_DUTIES = \
 	docs \
 	docs-deploy \
 	format \
-	release
+	release \
+	vscode
 
 QUALITY_DUTIES = \
 	check-quality \

README.md

@@ -5,13 +5,14 @@
 [![pypi version](https://img.shields.io/pypi/v/mkdocs-autorefs.svg)](https://pypi.org/project/mkdocs-autorefs/)
 [![conda version](https://img.shields.io/conda/vn/conda-forge/mkdocs-autorefs.svg)](https://anaconda.org/conda-forge/mkdocs-autorefs)
 [![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/autorefs)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mkdocstrings/autorefs)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#autorefs:gitter.im)
 
 Automatically link across pages in MkDocs.
 
 ## Installation
 
 With `pip`:
+
 ```bash
 python3 -m pip install mkdocs-autorefs
 ```
@@ -48,4 +49,97 @@ This works the same as [a normal link to that heading](../doc1.md#hello-world).
 
 Linking to a heading without needing to know the destination page can be useful if specifying that path is cumbersome, e.g. when the pages have deeply nested paths, are far apart, or are moved around frequently. And the issue is somewhat exacerbated by the fact that [MkDocs supports only *relative* links between pages](https://github.com/mkdocs/mkdocs/issues/1592).
 
-Note that this plugin's behavior is undefined when trying to link to a heading title that appears several times throughout the site. Currently it arbitrarily chooses one of the pages.
+Note that this plugin's behavior is undefined when trying to link to a heading title that appears several times throughout the site. Currently it arbitrarily chooses one of the pages. In such cases, use [Markdown anchors](#markdown-anchors) to add unique aliases to your headings.
+
+### Markdown anchors
+
+The autorefs plugin offers a feature called "Markdown anchors". Such anchors can be added anywhere in a document, and linked to from any other place.
+
+The syntax is:
+
+```md
+[](){#id-of-the-anchor}
+```
+
+If you look closely, it starts with the usual syntax for a link, `[]()`, except both the text value and URL of the link are empty. Then we see `{#id-of-the-anchor}`, which is the syntax supported by the [`attr_list`](https://python-markdown.github.io/extensions/attr_list/) extension. It sets an HTML id to the anchor element. The autorefs plugin simply gives a meaning to such anchors with ids. Note that raw HTML anchors like `<a id="foo"></a>` are not supported.
+
+The `attr_list` extension must be enabled for the Markdown anchors feature to work:
+
+```yaml
+# mkdocs.yml
+plugins:
+  - search
+  - autorefs
+
+markdown_extensions:
+  - attr_list
+```
+
+Now, you can add anchors to documents:
+
+```md
+Somewhere in a document.
+
+[](){#foobar-paragraph}
+
+Paragraph about foobar.
+```
+
+...making it possible to link to this anchor with our automatic links:
+
+```md
+In any document.
+
+Check out the [paragraph about foobar][foobar-pararaph].
+```
+
+If you add a Markdown anchor right above a heading, this anchor will redirect to the heading itself:
+
+```md
+[](){#foobar}
+## A verbose title about foobar
+```
+
+Linking to the `foobar` anchor will bring you directly to the heading, not the anchor itself, so the URL will show `#a-verbose-title-about-foobar` instead of `#foobar`. These anchors therefore act as "aliases" for headings. It is possible to define multiple aliases per heading:
+
+```md
+[](){#contributing}
+[](){#development-setup}
+## How to contribute to the project?
+```
+
+Such aliases are especially useful when the same headings appear in several different pages. Without aliases, linking to the heading is undefined behavior (it could lead to any one of the headings). With unique aliases above headings, you can make sure to link to the right heading.
+
+For example, consider the following setup. You have one document per operating system describing how to install a project with the OS package manager or from sources:
+
+```tree
+docs/
+  install/
+    arch.md
+    debian.md
+    gentoo.md
+```
+
+Each page has:
+
+```md
+## Install with package manager
+...
+
+## Install from sources
+...
+```
+
+You don't want to change headings and make them redundant, like `## Arch: Install with package manager` and `## Debian: Install with package manager` just to be able to reference the right one with autorefs. Instead you can do this:
+
+```md
+[](){#arch-install-pkg}
+## Install with package manager
+...
+
+[](){#arch-install-src}
+## Install from sources
+...
+```
+
+...changing `arch` by `debian`, `gentoo`, etc. in the other pages.

config/git-changelog.toml

@@ -0,0 +1,8 @@
+bump = "auto"
+convention = "angular"
+in-place = true
+output = "CHANGELOG.md"
+parse-refs = false
+parse-trailers = true
+sections = ["build", "deps", "feat", "fix", "refactor"]
+template = "keepachangelog"

config/ruff.toml

@@ -1,5 +1,5 @@
 target-version = "py38"
-line-length = 132
+line-length = 120
 exclude = [
     "fixtures",
     "site",
@@ -77,6 +77,9 @@ ignore = [
 "src/*/cli.py" = [
     "T201",  # Print statement
 ]
+"src/*/debug.py" = [
+    "T201",  # Print statement
+]
 "scripts/*.py" = [
     "INP001",  # File is part of an implicit namespace package
     "T201",  # Print statement
@@ -99,3 +102,7 @@ known-first-party = ["mkdocs_autorefs"]
 
 [pydocstyle]
 convention = "google"
+
+[format]
+docstring-code-format = true
+docstring-code-line-length = 80

config/vscode/launch.json

@@ -0,0 +1,36 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "python (current file)",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
+        {
+            "name": "test",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "justMyCode": false,
+            "args": [
+                "-c=config/pytest.ini",
+                "-vvv",
+                "--no-cov",
+                "--dist=no",
+                "tests",
+                "-k=${input:tests_selection}"
+            ]
+        }
+    ],
+    "inputs": [
+        {
+            "id": "tests_selection",
+            "type": "promptString",
+            "description": "Tests selection",
+            "default": ""
+        }
+    ]
+}