mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-12 11:04:25 +00:00
ef3b7482cd
* chore: cleanup old docs folder * remove docs path trigger * wip docs structure * chore: ignore site changes in ci * add manuals route * new structure * structure * Use correct title * remove trigger for code scan for static site generator * change names * add lorem ipsum to test styling * use h3 to deeplink * add site to dependabot * lint readme.md * remove not needed file * ignore site on pull request code scan * add initial contrib * Minor correction * Added section Developer & Integration * Changed link list layout, added labels, added translations * Added missing <li> tags * Added correct link to section Developer & Integration * Fixing list style * Overhauling description texts and translations * outline * teaser go * outline * wip * rework * wip * wip * wip * hop * wip * first draft for "administrate" done * init outline * fix deploy step * lint * commit wip * commit wip * md lint * Link * fix: path to edit (#711) * wip * wip * wip * what are... * use only features * wip docs * Update 00-user.en.md * project * uppercase en * wip * wip * wip * policies rework * improve text * correct typo * update readme * correct styling * add link to docs guides * make the linter happy * rename * wip * move api to own file * correct links and lint * wip roles and integration * add pkce * reduce padding and margin * wip scope and claims * wip claim & scopes * make the linter happy * insert links where possible * wip * wip roles & providers * Update README.md * Update 00-user.en.md * minor text improvements * use master branch to deploy * use proper ci file * Apply suggestions from code review Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com> Co-authored-by: Matthias M. Schneider <mati@matimax.info> Co-authored-by: Max Peintner <max@caos.ch> Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>
70 lines
4.0 KiB
Markdown
70 lines
4.0 KiB
Markdown
# How to contribute to ZITADEL's documentation
|
|
|
|
Before you start your editing process please take some time to familiarise yourself with the rules for contributing to the documentation of ZITADEL.
|
|
|
|
## File format
|
|
|
|
ZITADEL's static site generator uses a Markdown file format. The flavour of the Markdown is specified in the [CAOS Static Site Generator](/docs/cssg.md) document.
|
|
|
|
## Using headings
|
|
|
|
Make use of headings to structure and organise the document. The static site generator will make sure that the headings are rendered as a means of navigation for the site's content.
|
|
|
|
## Headings capitalisation conventions
|
|
|
|
In order to keep consistency across the documentation we urge you to only write the very first word of a heading with a capital letter. The styling of the static site generator will then guarantee the consistent rendering of first caps, all caps, word caps or whatever style is chosen for the output.
|
|
|
|
## Using captions
|
|
|
|
We urge you to always add captions to listings, code snippets, tables, graphics and images, *unless* the image is a logo or icon of any type. Also, inline graphics and images don't require captions due to readability.
|
|
|
|
Numbering is **required** for captions. See next section.
|
|
|
|
## Numbering of captions
|
|
|
|
Numbering has to be continuous using Arabic style numbers. The caption is composed of a prefix and a descriptive text. The prefix is composed of the item type (Listing, Table, Image, Graphic), an incrementing number in Arabic style followed by a period and a description.
|
|
|
|
If the description consists of **one term** only you must omit any trailing punctuation. If the description represents a complete sentence you must terminate it with a period.
|
|
|
|
Examples:
|
|
|
|
* Snippet 3. Example of a protobuf interface deriving ZITADEL's OIDC connector.
|
|
* Figure 1. Inside the ESO Atacama Large Millimetre/submillimetre Array.
|
|
* Table 21. Representation of all supported quantum-singularity proximation algorithms.
|
|
* Image 13. Higgs Boson
|
|
|
|
## Inline graphics and images
|
|
|
|
Use sparsely. You should always make sure that inline images do not exceed 48 by 48 pixels (or the equivalent scale for HDPI displays).
|
|
|
|
## Keyboard shortcuts
|
|
|
|
When documenting the usage of UI components don't forget to include the keyboard shortcuts available. Use the `kbd:` macro or `<kbd>` HTML tag to style the keys accordingly. To ensure platform-independent documentation always include the modifier-keys for **all** supported platforms, i.e. `[kbd:]Ctrl` or `[kbd:]Opt [kbd:]C`, which renders `<kbd>Ctrl</kbd>` or `<kbd>Opt</kbd> <kbd>C</kbd>`.
|
|
|
|
## File name conventions
|
|
|
|
### File name
|
|
|
|
If and when the file name of a Markdown file consist of more than **one** contiguous word you must use a hyphen `-` to separate the word elements.
|
|
|
|
Examples:
|
|
|
|
* content.md
|
|
* distribution-guide.md
|
|
* programming-examples.md
|
|
* explaining-the-code-snippets.md
|
|
|
|
### File extension
|
|
|
|
For reasons of consistency the static site generator only accepts Markdown files with the `.md` file extension.
|
|
|
|
### Internationalisation (I18N)
|
|
|
|
Writing documentation in country specific languages is highly endorsed. The static site generator makes use of a simple naming convention for Markdown files which are available in different languages:
|
|
|
|
`{filename}[.{language-id}].md`
|
|
|
|
Where `filename` represents the name of the file (see section [File name](#file-name)), `language-id` is an *optional* language identifier (see the list of [ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)), and the mandatory file extension `.md`.
|
|
|
|
**Note:** If a file name does not specify a language identifier we consider the file name to be implicitly written in English language (defaulting to `.en`). This is also important for the rendering of the language-dependent content navigation as the content navigations always will only include pages in their respective language they represent. This means that Markdown files without language identifier will **only** be rendered in the content navigation of the English documentation variant and will **not be visible at all** in the content navigations of other language variants.
|