📚 DOC: Update auto-generated header anchors section (#524)

Author: choldgraf

CHANGELOG.md

@@ -8,6 +8,8 @@ Full Changelog: [v0.16.1...v0.17.0](https://github.com/executablebooks/MyST-Pars
 
 ### ‼️ Markdown link resolution improvements
 
+**WARNING: This is a breaking change for links that rely on auto-generated anchor links**. You should now [manually enable auto-generated anchor links](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors) if you see errors like `WARNING reference target not found`.
+
 Markdown links are of the format `[text](link)`.
 MyST-Parser looks to smartly resolve such links, by identifying if they are:
 
@@ -30,6 +32,8 @@ See [Markdown Links and Referencing](docs/syntax/syntax.md#markdown-links-and-re
 
 ### ‼️ Dollarmath is now disabled by default
 
+**WARNING: This is a breaking change for dollar math**. You should now manually enable dollar math (see below).
+
 The default configuration is now `myst_enable_extensions=()`, instead of `myst_enable_extensions=("dollarmath",)`.
 If you are using math enclosed in `$` or `$$` in your documents, you should enable `dollarmath` explicitly.
 

docs/syntax/optional.md

@@ -489,12 +489,36 @@ Also see [](syntax/html-admonition).
 
 ## Auto-generated header anchors
 
-A common, extended Markdown syntax is to use header bookmark links, locally; `[](#header-anchor)`, or cross-file `[](path/to/file.md#header-anchor)`.
-To achieve this, section headings must be assigned anchors, which can be achieved in `myst-parser`,
-by setting `myst_heading_anchors = 2` in your `conf.py`.
-This configures heading anchors to be assigned to both `h1` and `h2` level headings.
-The anchor "slugs" created aim to follow the [GitHub implementation](https://github.com/Flet/github-slugger); lower-case text, removing punctuation, replacing spaces with `-`, uniqueness *via* suffix enumeration `-1`.
-To change the slug function, set `myst_heading_slug_func` in your `conf.py` to a function that accepts a string and returns a string.
+The MyST Parser can automatically generate label "slugs" for header anchors so that you can reference them from markdown links.
+For example, you can use header bookmark links, locally; `[](#header-anchor)`, or cross-file `[](path/to/file.md#header-anchor)`.
+To achieve this, use the `myst_heading_anchors = DEPTH` configuration option, where `DEPTH` is the depth of header levels for which you wish to generate links.
+
+For example, the following configuration in `conf.py` tells the `myst_parser` to generate labels for heading anchors for `h1`, `h2`, and `h3` level headings (corresponding to `#`, `##`, and `###` in markdown).
+
+```python
+myst_heading_anchors = 3
+```
+
+You can then insert markdown links directly to anchors that are generated from your header titles in your documentation.
+For example `[](#auto-generated-header-anchors)`: [](#auto-generated-header-anchors).
+
+The paths to other files should be relative to the current file, for example
+`[**link text**](./syntax.md#the-myst-syntax-guide)`: [**link text**](./syntax.md#the-myst-syntax-guide).
+
+
+### Anchor slug structure
+
+The anchor "slugs" created aim to follow the [GitHub implementation](https://github.com/Flet/github-slugger):
+
+- lower-case text
+- remove punctuation
+- replace spaces with `-`
+- enforce uniqueness *via* suffix enumeration `-1`
+
+To change the slug generation function, set `myst_heading_slug_func` in your `conf.py` to a function that accepts a string and returns a string.
+
+### Inspect the links that will be created
+
 You can inspect the links that will be created using the command-line tool:
 
 ```console
@@ -508,11 +532,6 @@ $ myst-anchors -l 2 docs/syntax/optional.md
 <h2 id="direct-latex-math"></h2>
 ```
 
-For example `[](#auto-generated-header-anchors)`: [](#auto-generated-header-anchors).
-
-The paths to other files should be relative to the current file, for example
-`[**link text**](./syntax.md#the-myst-syntax-guide)`: [**link text**](./syntax.md#the-myst-syntax-guide).
-
 (syntax/definition-lists)=
 
 ## Definition Lists