mirror of
https://codeberg.org/openpgp/notes.git
synced 2025-09-09 11:19:41 +02:00
Add contributing guidelines for adding explicit targets
Signed-off-by: David Runge <dave@sleepmap.de>
This commit is contained in:
parent
b575bbfaf7
commit
76c70d85ec
1 changed files with 3 additions and 0 deletions
|
@ -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
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue