website/developer-docs: add a baby Style Guide (#9900)
* draft style guide * broken links * rename partial file * added content to style guide, more links * sidebar and link * polish * typo * forgot to save * kens formatting trick * typo * Jens' edits * tweak * simplify formatting for variables * edits from 4d62 * fixed link * more edits * tweak re formatting command * tweak re formatting command --------- Co-authored-by: Tana M Berry <tana@goauthentik.com>
This commit is contained in:
Tana M Berry
@ -2,16 +2,19 @@
|
||||
title: Writing documentation
|
||||
---
|
||||
|
||||
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. Here are a few guidelines to ensure
|
||||
the documentation is easy to read and uses similar phrasing.
|
||||
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project.
|
||||
|
||||
## Setup
|
||||
## Set up your local build
|
||||
|
||||
Requirements:
|
||||
|
||||
- Node.js 16 (or greater)
|
||||
- Node.js 20 (or greater, we use Node.js 22)
|
||||
|
||||
The documentation site is situated in the `/website` folder of the authentik GitHub repository.
|
||||
The docs and the code are in the same Github repo, at https://github.com/goauthentik/authentik, so if you have cloned the repo, you already have the docs.
|
||||
|
||||
You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR.
|
||||
|
||||
The documentation site is situated in the `/website` folder of the repo.
|
||||
|
||||
The site is built using npm, below are some useful make commands:
|
||||
|
||||
@ -19,57 +22,36 @@ The site is built using npm, below are some useful make commands:
|
||||
|
||||
This command is required before running any of the following commands, and after upgrading any dependencies.
|
||||
|
||||
- **Formatting**: `make website` or `make website-lint-fix`
|
||||
- **Formatting**: `make website`, `make website-lint-fix`, or `npm run prettier`
|
||||
|
||||
Run this command before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting.
|
||||
Run the appropriate formatting command for your set up before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting.
|
||||
|
||||
- **Live editing**: `make website-watch`
|
||||
|
||||
For real time viewing of changes, as you make them.
|
||||
|
||||
:::info
|
||||
Be sure to run the formatter before committing changes.
|
||||
Be sure to run a formatting command before committing changes.
|
||||
:::
|
||||
|
||||
## General guidelines
|
||||
## Writing guidelines
|
||||
|
||||
- The product name authentik should always be stylized as `authentik` (with a lower-case "a" and ending with a "k").
|
||||
- Documentation should use American English.
|
||||
- You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions.
|
||||
- Use abbreviations where it makes sense (for commonly used terms like SAML and OAuth) for common terms. If an abbreciation is less-known, spell it out in parentheses after the first use.
|
||||
- Phrasing should almost always be in present tense and active voice:
|
||||
Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
|
||||
|
||||
- DON'T: "The Applications page will be loaded."
|
||||
Whenever possible, use one of our [doc templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent.
|
||||
|
||||
- DO: "The Applications page displays."
|
||||
Make sure to add the new pages to the appropriate place in `/website/sidebars.js`. Otherwise, the content will not appear in the table of contents to the left.
|
||||
|
||||
- Phrasing should never blame the user, and should be subjective:
|
||||
Following the guidelines will make getting your PRs merged much easier and faster, with fewer edits needed. We appreciate our community contributors helping us keep the Docs consistent, easy-to-use, and high quality.
|
||||
|
||||
- DON'T: "Never modify the default file."
|
||||
## Documentation for Integrations
|
||||
|
||||
- DO: "We recommend not modifying the default file."
|
||||
In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.
|
||||
|
||||
- When referring to UI text or UI components in authentik, use **bold** text.
|
||||
- When referring to other objects in authentik code or functionality, use _cursive_ text, and link to the corresponding documentation if possible.
|
||||
- When referring to external tools, give an example how to use the tools or explain how the user can use them.
|
||||
- Make sure to add the documentation to the sidebar, if adding a new page.
|
||||
- Test how the documentation renders using the Netlify Deploy Preview, especially when using Docusaurus-specific features. Or build it locally and test, using the `make website-watch` command.
|
||||
For new integration documentation, please use the Integrations template in our [Github repo](https://github.com/goauthentik/authentik) at `/website/integrations/_template/service.md`.
|
||||
|
||||
If you find any documentation that doesn't match these guidelines, feel free to either open an [Issue](https://github.com/goauthentik/authentik/issues) or a [PR](https://github.com/goauthentik/authentik/pulls) so they can be fixed.
|
||||
|
||||
## Integration guidelines
|
||||
|
||||
These guidelines apply in addition to the ones above.
|
||||
|
||||
See the template in `/website/integrations/_template/service.md`.
|
||||
|
||||
- For placeholders, use angle brackets and italicize the text inside the brackets, to indicate that it is a variable (`_<placeholder-name>_`).
|
||||
|
||||
Make sure to also define if the placeholder is something the user needs to define, is something another system defines, or is randomly generated.
|
||||
|
||||
If you're adding configuration snippets to the documentation, and the snippet is in a language that supports comments, other placeholders may be used, for example comments referencing an earlier step.
|
||||
- Make sure to add the service to a fitting category in `/website/sidebarsIntegrations.js`. If this is not done the service will not appear in the table of contents to the left.
|
||||
|
||||
- For placeholder domains, use `authentik.company` and `app-name.company`, where `app-name` is the name of the application that you are writing documentation for.
|
||||
- Try to order the documentation in the order that makes it easiest for the user to configure.
|
||||
|
||||
- Make sure to add the service to a fitting category in `/website/sidebarsIntegrations.js`
|
||||
- Try to order the documentation sections in an order that makes it easiest for the user to configure.
|
||||
|
||||
Reference in New Issue
Block a user