From 76c70d85ecb5e24c7e5a59404a75135ecd539e1a Mon Sep 17 00:00:00 2001 From: David Runge Date: Tue, 12 Dec 2023 15:14:25 +0100 Subject: [PATCH] Add contributing guidelines for adding explicit targets Signed-off-by: David Runge --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bfb5e07..3bc6334 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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