Add contributing guidelines for adding explicit targets

Signed-off-by: David Runge <dave@sleepmap.de>
This commit is contained in:
David Runge 2023-12-12 15:14:25 +01:00
parent b575bbfaf7
commit 76c70d85ec
No known key found for this signature in database
GPG key ID: 90D4B9641E092971

View file

@ -81,6 +81,8 @@ Use the `{literalcode}` directive to include files:
There are a few guidelines when it comes to cross-referencing, which work around oddities with [sphinx] and [MyST-parser]:
* When adding [explicit targets], use [kebab case].
* Do not rename already released [explicit targets], as it will break deep linking by downstreams relying on these targets.
* When referencing chapters by file, use `[](/my-chapter)`, instead of relying on [explicit targets] for a top-level heading.
* To reference a figure by its title, use `[](#my-figure)` for a figure with the `:name:` attribute `my-figure` (and e.g. the title `My Figure`).
* To reference a figure by number (e.g. `Fig. 1`), use ```{numref}`my-figure` ``` for a figure with the `:name:` attribute `my-figure`.
@ -117,6 +119,7 @@ Configuration file contributions fall under the terms of the [CC0-1.0].
[codespell]: https://github.com/codespell-project/codespell
[lychee]: https://lychee.cli.rs
[explicit targets]: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#creating-explicit-targets
[kebab case]: https://en.wikipedia.org/wiki/Letter_case#Kebab_case
[Figure]: https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#figures-images-with-captions
[accessibility]: https://en.wikipedia.org/wiki/Computer_accessibility
[glossary]: https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#definition-lists-and-glossaries