docs: use autorefs for section references

Author: sisp

docs/comparisons.md

@@ -35,10 +35,7 @@ docs! We don't want to be biased, but it's easy that we tend to be:
 [jinja]: https://jinja.palletsprojects.com/
 [ejs]: https://ejs.co/
 
-[^1]:
-    The file itself can
-    [include other YAML files](configuring.md#include-other-yaml-files).
-
+[^1]: The file itself can [include other YAML files][include-other-yaml-files].
 [^2]:
     Git repo is recommended to be able to use advanced features such as template tagging
     and smart updates.

docs/configuring.md

@@ -13,32 +13,32 @@ It is important that you understand how Copier works. It has 2 kinds of configur
 Copier reads **settings** from these sources, in this order of priority:
 
 1. Command line or API arguments.
-1. [The `copier.yml` file](#the-copieryml-file). Settings here always start with an
+1. [The `copier.yml` file][the-copieryml-file]. Settings here always start with an
    underscore (e.g. `_min_copier_version`).
 
 !!! info
 
     Some settings are _only_ available as CLI arguments, and some others _only_ as
     template configurations. Some behave differently depending on where they are
-    defined. [Check the docs for each specific setting](#available-settings).
+    defined. [Check the docs for each specific setting][available-settings].
 
 Copier obtains **answers** from these sources, in this order of priority:
 
 1. Command line or API arguments.
 1. Asking the user. Notice that Copier will not ask any questions answered in the
    previous source.
-1. [Answer from last execution](#the-copier-answersyml-file).
-1. Default values defined in [the `copier.yml` file](#the-copieryml-file).
+1. [Answer from last execution][the-copier-answersyml-file].
+1. Default values defined in [the `copier.yml` file][the-copieryml-file].
 
 ## The `copier.yml` file
 
 The `copier.yml` (or `copier.yaml`) file is found in the root of the template, and it is
 the main entrypoint for managing your template configuration. It will be read and used
 for two purposes:
 
--   [Prompting the user for information](#questions).
--   [Applying template settings](#available-settings) (excluding files, setting
-    arguments defaults, etc.).
+-   [Prompting the user for information][questions].
+-   [Applying template settings][available-settings] (excluding files, setting arguments
+    defaults, etc.).
 
 ### Questions
 
@@ -156,7 +156,7 @@ Supported keys:
     long, you can use
     [YAML anchors](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html).
 -   **secret**: When `true`, it hides the prompt displaying asterisks (`*****`) and
-    doesn't save the answer in [the answers file](#the-copier-answersyml-file). When
+    doesn't save the answer in [the answers file][the-copier-answersyml-file]. When
     `true`, a default value is required.
 -   **placeholder**: To provide a visual example for what would be a good value. It is
     only shown while the answer is empty, so maybe it doesn't make much sense to provide
@@ -455,12 +455,12 @@ your_template
 
 !!! important
 
-    Note that the chosen [template suffix](#templates_suffix)
+    Note that the chosen [template suffix][templates_suffix]
     **must** appear outside of the Jinja condition,
     otherwise the whole file won't be considered a template and will
     be copied as such in generated projects.
 
-You can even use the answers of questions with [choices](#advanced-prompt-formatting):
+You can even use the answers of questions with [choices][advanced-prompt-formatting]:
 
 ```yaml title="copier.yml"
 ci:
@@ -483,7 +483,7 @@ your_template
 
 !!! important
 
-    Contrary to files, directories **must not** end with the [template suffix](#templates_suffix).
+    Contrary to files, directories **must not** end with the [template suffix][templates_suffix].
 
 !!! warning
 
@@ -627,14 +627,14 @@ your_template
         ...
 ```
 
-Then, make sure to [exclude](#exclude) this folder
+Then, make sure to [exclude][exclude] this folder
 
 ```yaml title="copier.yml"
 _exclude:
     - includes
 ```
 
-or use a [subdirectory](#subdirectory), e.g.:
+or use a [subdirectory][subdirectory], e.g.:
 
 ```yaml title="copier.yml"
 _subdirectory: template
@@ -655,11 +655,11 @@ reason, Copier provides a function
 
 ## Available settings
 
-Template settings alter how the template is rendered.
-[They come from several sources](#configuration-sources).
+Template settings alter how the template is rendered. [They come from several
+sources][configuration-sources].
 
-Remember that **the key must be prefixed with an underscore if you use it in
-[the `copier.yml` file](#the-copieryml-file)**.
+Remember that **the key must be prefixed with an underscore if you use it in [the
+`copier.yml` file][the-copieryml-file]**.
 
 ### `answers_file`
 
@@ -675,7 +675,7 @@ the project root.
     Remember to add that file to your Git template if you want to support
     [updates](updating.md).
 
-Don't forget to read [the docs about the answers file](#the-copier-answersyml-file).
+Don't forget to read [the docs about the answers file][the-copier-answersyml-file].
 
 !!! example
 
@@ -691,7 +691,7 @@ Don't forget to read [the docs about the answers file](#the-copier-answersyml-fi
 -   Default value: `True`
 
 When Copier creates the destination path, if there's any failure when rendering the
-template (either in the rendering process or when running the [tasks](#tasks)), Copier
+template (either in the rendering process or when running the [tasks][tasks]), Copier
 will delete that folder.
 
 Copier will never delete the folder if it didn't create it. For this reason, when
@@ -806,7 +806,7 @@ to know available options.
 -   Default value:
     `["copier.yaml", "copier.yml", "~*", "*.py[co]", "__pycache__", ".git", ".DS_Store", ".svn"]`
 
-[Patterns](#patterns-syntax) for files/folders that must not be copied.
+[Patterns][patterns-syntax] for files/folders that must not be copied.
 
 The CLI option can be passed several times to add several patterns.
 
@@ -827,7 +827,7 @@ The CLI option can be passed several times to add several patterns.
 
 !!! info
 
-    When the [`subdirectory`](#subdirectory) parameter is defined and its value is the
+    When the [`subdirectory`][subdirectory] parameter is defined and its value is the
     path of an actual subdirectory (i.e. not `""` or `"."` or `"./"`), then the default
     value of the `exclude` parameter is `[]`.
 
@@ -853,8 +853,8 @@ The CLI option can be passed several times to add several patterns.
 
 Overwrite files that already exist, without asking.
 
-Also don't ask questions to the user; just use default values
-[obtained from other sources](#configuration-sources).
+Also don't ask questions to the user; just use default values [obtained from other
+sources][configuration-sources].
 
 !!! info
 
@@ -871,7 +871,7 @@ Use default answers to questions.
 !!! attention
 
     Any question that does not have a default value must be answered
-    [via CLI/API](#data). Otherwise, an error is raised.
+    [via CLI/API][data]. Otherwise, an error is raised.
 
 !!! info
 
@@ -885,7 +885,7 @@ Use default answers to questions.
 
 Overwrite files that already exist, without asking.
 
-[obtained from other sources](#configuration-sources).
+[obtained from other sources][configuration-sources].
 
 !!! info
 
@@ -977,7 +977,7 @@ on them, so they are always installed when Copier is installed.
         enhances the extension loading mechanism to allow templates writers to put their
         extensions directly in their templates. It also allows to modify the rendering context
         (the Jinja variables that you can use in your templates) before
-        rendering templates, see [using a context hook](faq.md#how-can-i-alter-the-context-before-rendering-the-project).
+        rendering templates, see [using a context hook][how-can-i-alter-the-context-before-rendering-the-project].
     -   [`jinja_markdown.MarkdownExtension`](https://github.com/jpsca/jinja-markdown):
         provides a `markdown` tag that will render Markdown to HTML using
         [PyMdown extensions](https://facelessuser.github.io/pymdown-extensions/).
@@ -1001,13 +1001,13 @@ on them, so they are always installed when Copier is installed.
 -   Default value: `""`
 
 A message to be printed after [generating](generating.md) or
-[regenerating](generating.md#regenerating-a-project) a project _successfully_.
+[regenerating][regenerating-a-project] a project _successfully_.
 
 If the message contains Jinja code, it will be rendered with the same context as the
-rest of the template. A [Jinja include](#importing-jinja-templates-and-macros)
-expression may be used to import a message from a file.
+rest of the template. A [Jinja include][importing-jinja-templates-and-macros] expression
+may be used to import a message from a file.
 
-The message is suppressed when Copier is run in [quiet mode](#quiet).
+The message is suppressed when Copier is run in [quiet mode][quiet].
 
 !!! example
 
@@ -1034,9 +1034,8 @@ The message is suppressed when Copier is run in [quiet mode](#quiet).
 -   CLI flags: N/A
 -   Default value: `""`
 
-Like [`message_after_copy`](#message_after_copy) but printed _before_
-[generating](generating.md) or [regenerating](generating.md#regenerating-a-project) a
-project.
+Like [`message_after_copy`][message_after_copy] but printed _before_
+[generating](generating.md) or [regenerating][regenerating-a-project] a project.
 
 !!! example
 
@@ -1058,7 +1057,7 @@ project.
 -   CLI flags: N/A
 -   Default value: `[]`
 
-Migrations are like [tasks](#tasks), but each item in the list is a `dict` with these
+Migrations are like [tasks][tasks], but each item in the list is a `dict` with these
 keys:
 
 -   **version**: Indicates the version that the template update has to go through to
@@ -1175,8 +1174,8 @@ Suppress status output.
 -   Default value: `[]`
 
 Question variables to mark as secret questions. This is especially useful when questions
-are provided in the [simplified prompt format](#questions). It's equivalent to
-configuring `secret: true` in the [advanced prompt format](#advanced-prompt-formatting).
+are provided in the [simplified prompt format][questions]. It's equivalent to
+configuring `secret: true` in the [advanced prompt format][advanced-prompt-formatting].
 
 !!! example
 
@@ -1194,7 +1193,7 @@ configuring `secret: true` in the [advanced prompt format](#advanced-prompt-form
 -   CLI flags: `-s`, `--skip`
 -   Default value: `[]`
 
-[Patterns](#patterns-syntax) for files/folders that must be skipped if they already
+[Patterns][patterns-syntax] for files/folders that must be skipped if they already
 exist.
 
 !!! example
@@ -1349,7 +1348,7 @@ Suffix that instructs which files are to be processed by Jinja as templates.
     ```
 
 An empty suffix is also valid, and will instruct Copier to copy and render _every file_,
-except those that are [excluded by default](#exclude). If an error happens while trying
+except those that are [excluded by default][exclude]. If an error happens while trying
 to read a file as a template, it will fallback to a simple copy (it will typically
 happen for binary files like images). At the contrary, if such an error happens and the
 templates suffix is _not_ empty, Copier will abort and print an error message.
@@ -1378,9 +1377,9 @@ templates suffix is _not_ empty, Copier will abort and print an error message.
 
 Copier templates can use dangerous features that allow arbitrary code execution:
 
--   [Jinja extensions](#jinja_extensions)
--   [Migrations](#migrations)
--   [Tasks](#tasks)
+-   [Jinja extensions][jinja_extensions]
+-   [Migrations][migrations]
+-   [Tasks][tasks]
 
 Therefore, these features are disabled by default and Copier will raise an error (and
 exit from the CLI with code `2`) when they are found in a template. In this case, please
@@ -1463,18 +1462,19 @@ _exclude:
 ## The `.copier-answers.yml` file
 
 If the destination path exists and a `.copier-answers.yml` file is present there, it
-will be used to load the last user's answers to the questions made in
-[the `copier.yml` file](#the-copieryml-file).
+will be used to load the last user's answers to the questions made in [the `copier.yml`
+file][the-copieryml-file].
 
 This makes projects easier to update because when the user is asked, the default answers
 will be the last ones they used.
 
 The file **must be called exactly `{{ _copier_conf.answers_file }}.jinja`** (or ended
-with [your chosen suffix](#templates_suffix)) in your template's root folder) to allow
-[applying multiple templates to the same subproject](#applying-multiple-templates-to-the-same-subproject).
+with [your chosen suffix][templates_suffix]) in your template's root folder) to allow
+[applying multiple templates to the same
+subproject][applying-multiple-templates-to-the-same-subproject].
 
-The default name will be `.copier-answers.yml`, but
-[you can define a different default path for this file](#answers_file).
+The default name will be `.copier-answers.yml`, but [you can define a different default
+path for this file][answers_file].
 
 The file must have this content:
 
@@ -1486,11 +1486,11 @@ The file must have this content:
 !!! important
 
     Did you notice that `NEVER EDIT MANUALLY` part?
-    [It is important](updating.md#never-change-the-answers-file-manually).
+    [It is important][never-change-the-answers-file-manually].
 
 The builtin `_copier_answers` variable includes all data needed to smooth future updates
 of this project. This includes (but is not limited to) all JSON-serializable values
-declared as user questions in [the `copier.yml` file](#the-copieryml-file).
+declared as user questions in [the `copier.yml` file][the-copieryml-file].
 
 As you can see, you also have the power to customize what will be logged here. Keys that
 start with an underscore (`_`) are specific to Copier. Other keys should match questions
@@ -1524,9 +1524,9 @@ All 3 templates are completely independent:
     matter their pre-commit configuration or the framework they rely on.
 
 Well, don't worry. Copier has you covered. You just need to use a different answers file
-for each one. All of them contain a `{{ _copier_conf.answers_file }}.jinja` file
-[as specified above](#the-copier-answersyml-file). Then you apply all the templates to
-the same project:
+for each one. All of them contain a `{{ _copier_conf.answers_file }}.jinja` file [as
+specified above][the-copier-answersyml-file]. Then you apply all the templates to the
+same project:
 
 ```shell
 mkdir my-project

docs/creating.md

@@ -3,9 +3,9 @@
 A template is a directory: usually the root folder of a Git repository.
 
 The content of the files inside the project template is copied to the destination
-without changes, **unless they end with `.jinja`** (or
-[your chosen suffix](configuring.md#templates_suffix)). In that case, the templating
-engine will be used to render them.
+without changes, **unless they end with `.jinja`** (or [your chosen
+suffix][templates_suffix]). In that case, the templating engine will be used to render
+them.
 
 Jinja2 templating is used. Learn more about it by reading
 [Jinja2 documentation](https://jinja.palletsprojects.com/).
@@ -84,7 +84,7 @@ Copier includes:
         context.
 
 -   `_copier_answers` includes the current answers dict, but slightly modified to make
-    it suitable to [autoupdate your project safely](configuring.md#the-answers-file):
+    it suitable to [autoupdate your project safely][the-copier-answersyml-file]:
     -   It doesn't contain secret answers.
     -   It doesn't contain any data that is not easy to render to JSON or YAML.
     -   It contains special keys like `_commit` and `_src_path`, indicating how the last

docs/faq.md

@@ -3,8 +3,8 @@
 ## Can Copier be applied over a preexisting project?
 
 Yes, of course. Copier understands this use case out of the box. That's actually what
-powers features such as [updating](updating.md) or the ability of
-[applying multiple templates to the same subproject](configuring.md#applying-multiple-templates-to-the-same-subproject).
+powers features such as [updating](updating.md) or the ability of [applying multiple
+templates to the same subproject][applying-multiple-templates-to-the-same-subproject].
 
 !!! example
 
@@ -56,8 +56,8 @@ templates, so that you can add, change or remove variables.
     https://github.com/copier-org/copier-templates-extensions#context-hook-extension
 
 In order for Copier to be able to load and use the extension when generating a project,
-it must be installed alongside Copier itself. More details in the
-[`jinja_extensions` docs](configuring.md#jinja_extensions).
+it must be installed alongside Copier itself. More details in the [`jinja_extensions`
+docs][jinja_extensions].
 
 You can then configure your Jinja extensions in Copier's configuration file:
 
@@ -144,9 +144,9 @@ repository.
 
 ## While developing, why the template doesn't include dirty changes?
 
-Copier follows [a specific algorithm](configuring.md#templates-versions) to choose what
-reference to use from the template. It also
-[includes dirty changes in the `HEAD` ref while developing locally](configuring.md#copying-dirty-changes).
+Copier follows [a specific algorithm][templates-versions] to choose what reference to
+use from the template. It also [includes dirty changes in the `HEAD` ref while
+developing locally][copying-dirty-changes].
 
 However, did you make sure you are selecting the `HEAD` ref for copying?
 

docs/generating.md

@@ -48,8 +48,8 @@ modifications made, Copier will use this modified working copy of the template t
 development of new template features.
 
 If you would like to override the version of template being installed, the
-[`--vcs-ref`](configuring.md/#vcs_ref) argument can be used to specify a branch, tag or
-other reference to use.
+[`--vcs-ref`][vcs_ref] argument can be used to specify a branch, tag or other reference
+to use.
 
 For example to use the latest master branch from a public repository: