website/docs/developer-docs/docs/style-guide.mdx
This Style Guide provides guidelines to ensure that the authentik documentation is consistent, clear, and easy to follow. It standardizes aspects like phrasing, formatting, tone, and structure across all documentation.
We appreciate all contributions to our documentation — whether it's fixing a typo, adding new content, or writing an entirely new topic. To help us review and merge your contributions more efficiently, please follow our writing documentation guidelines. If you notice any inconsistencies, feel free to open an Issue or submit a Pull Request to fix them.
Documentation should be structured to follow the natural order of tasks, making it easier for users to follow. Organize sections in a manner that reflects the actual workflow used to complete tasks.
When writing procedural documentation (How Tos) the steps should follow the workflow in the UI, specifying the exact pages to navigate and the precise fields, tabs, etc., to select or complete. Present the UI components in the document in the same order they appear in the UI.
Use headings (sub-titles) to break up large blocks of text, making it easier for users to navigate the content and find specific sections quickly.
In general, the visual, aesthetics of the technical documentation is intended to be lean and clean. Both the content (shorter sentences, concise instructions, etc) and the layout strive to have a clean, uncluttered look, with restrained use of colors and large callouts or announcements. Relatedly, the colors used for our Info and Warning callouts, light blue and light yellow respectively, are reserved for those purposes only.
Always include cross-references to related content. If a concept is referenced elsewhere in the documentation, link to the relevant section to provide users with additional context or instructions.
Use relative paths when linking to other documentation files. This will ensure links are automatically updated if file paths change in the future. If you are linking between another authentik resource that is not in the same repository and our regular technical docs, then use an absolute path.
The standard file type for documentation is .md. Use .mdx only if React components, such as interactive elements, are required.
Try to write procedural (How To) docs generically enough that it does not endorse or force a specific operating system. If it is necessary to specify a specific OS be sure to label it clearly. Consider using tabs (with MDX) to show the different OSes.
The product name authentik should always be written with a lowercase "a" and a "k" at the end, even if it begins a sentence.
The company name is Authentik Security, Inc., but for non-legal documentation, you may shorten it to Authentik Security.
When referring to the authentik Admin interface, capitalize "Admin" like it is in the UI, but do not bold the phrase "Admin interface" unless in a sentence that explicitly says "Click on Admin interface". However, if you are referring to a user or role that is an administrator, or has administrative rights, then do not capitalize it and spell out the full word "administrator" or "administrative".
The tone of the authentik documentation should be friendly but professional. It should be approachable, yet not overly casual. When appropriate, address the reader directly using second-person pronouns (e.g., "Next, you need to configure the login settings").
The documentation uses American English spelling conventions (e.g., "customize" instead of "customise").
Use active voice and present tense for clear, direct communication.
Avoid phrasing that blames the user. Be subjective and polite when providing instructions.
For Ken's sake, and many others, try to not use too many commas (avoid commaitis). Use a comma when needed to separate clauses, or for "slowing the pace" or clarity. Please do use the Serial comma (also known as the Oxford comma).
In lists, add a period at the end of a bulleted item if it is a complete sentence. Try not to mix incomplete and complete sentences in the same list.
Titles and headers (H1, H2, H3, etc.) should follow sentence case capitalization, meaning only the first word is capitalized, except for proper nouns or product names. For more information, see below.
Whether to capitalize after a colon depends on the context. Typically, we do not capitalize the first word after a colon unless it's a proper noun or if it is the start of a complete sentence. If the colon introduces a list, do not capitalize the first word unless it's a proper noun. In headings and titles, capitalize the first word after the colon.
It's important to use "that" as a conjunction to introduce a dependent clause, or as a "connection" between a noun and a verb ("The provider that you created in Step 3."). Including "that" as a conjunction helps non-native English speakers more easily parse phrases, and improves output for translation tools.
The easiest way to remember when to use "which" versus "that" is:
For more information, see this guide.
When writing about a status or anything that is causal ("this happened because of that"), use the word "because". Use the word "since" for time-based topics (this will be rare in technical writing).
When writing out steps in a procedural topic, avoid starting with "Once...". Instead, you can say "After you have created the scope mapping...".
When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting, and do not capitalize. Link to the relevant documentation when possible.
When referring to authentik functionality and features, such as flows, stages, sources, or policies, do not capitalize and do not use bold or italic text. When possible link to the corresponding documentation.
Use bold to highlight:
Use italic for:
Use code formatting for:
kubectl get nodes)./usr/local/bin/)..env).Add a period at the end of a bulleted item if it is a complete sentence. Try not to mix incomplete and complete sentences in the same list.
If there is a colon used in a bulleted list item, follow the capitalization rules.
We use Info, Warning, and Danger boxes, to provide supplemental information. Info boxes can optionally have a title, but do not use a title with Warning or Danger boxes.
Use the following syntax for these components:
Info:
::: info add-title-here
This is a tip or general note.
:::
Warnings:
:::warning
This level is for more serious situations: an action cannot be undone, a process might be canceled, etc.
:::
Critical warnings (for irreversible actions):
:::danger
This level is for extremely serious situations, such as an action permanently removing data.
:::
< >) and use underscores between words. See more about variables below (#variables).To clearly indicate terms or values that are placeholders and require user input, enclose any variables inside angle brackets (< >) and use underscores between words to clearly indicate that these are placeholders that require user input.
Examples:
https://authentik.company/application/o/<slug>/.well-known/openid-configuration<first_name>."Titles and headers (H1, H2, H3) should follow sentence case capitalization, meaning only the first word is capitalized, except for proper nouns or product names.
Ensure that titles and headers are descriptive and clearly convey the purpose of the section. Avoid vague titles like "Overview." Instead, opt for something more specific, like "About authentik policies."
Use the imperative verb form in procedural topics, not gerunds. For example, use "Configure your instance" instead of "Configuring your instance."
When you want to show an example (say, a code snippet), start on a new line, use bold text for the word "Example", and a colon, like this:
Example:
This expression policy uses an expression based on the user's name:
```python
if request.context["pending_user"].username == "marie":
return True
return False
```
When you want to show sections of code use Code blocks to provide syntax highlighting, a copy button, line numbering and line highlighting:
` ` ` yaml showLineNumbers {5} title="/etc/wazuh-indexer/opensearch-security/roles_mapping.yml"
all_access:
reserved: true
hidden: false
backend_roles:
- "wazuh-admin"
- "admin"
hosts: []
users: []
and_backend_roles: []
description: "Maps admin to all_access"
` ` `
Which is rendered as:
all_access:
reserved: true
hidden: false
backend_roles:
- "wazuh-admin"
- "admin"
hosts: []
users: []
and_backend_roles: []
description: "Maps admin to all_access"
yaml defines the language used for syntax highlighting. Other languages can be used such asjsx, python, bash, and text`.Optional configurations:
showLineNumbers: enables line numbering.title=" ": defines the title displayed at the top (e.g., filenames).{5}: highlights specific lines. Ranges and lists are allowed (e.g., {5, 7, 9-11}).// highlight-next-line: highlights the next line within a code block.// highlight-start and // highlight-end: highlight multiple lines.For more details, see the Docusaurus code block documentation.
Use tables to compare options, list parameters, or summarize information. Ensure tables are concise and avoid nesting complex content. Only use a table when there are 4 or more items. For only 2 or 3 items, use a bullet list.
Use Tabs to display different configurations (e.g., setting up authentication with OIDC vs. SAML) to help users navigate between options. Default to the easier or more common option. For example:
import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";
<Tabs
defaultValue="oidc"
values={[
{ label: "OIDC", value: "oidc" },
{ label: "SAML", value: "saml" },
]}
>
<TabItem value="oidc">OIDC configuration details go here.</TabItem>
<TabItem value="saml">SAML configuration details go here.</TabItem>
</Tabs>;
When documenting errors, follow this structure:
Example:
Error message:
Error: Authentication failed. Invalid credentials.
Possible causes:
Solutions:
https://authentik.company/static/dist/assets/icons/icon.svgFront matter: Include a title and optional summary. You can also add badge metadata in the front matter:
---
title: Getting Started
description: Install and configure authentik in 5 minutes.
authentik_version: "2025.4" # Semantic version when feature was introduced (Optional)
authentik_preview: true # For preview features (Optional)
authentik_enterprise: true # For enterprise features (Optional)
support_level: "authentik" # For integrations: Support level: "authentik" (tested by team) or "community" (community maintained)
---
Note: Badges should be defined in the front matter, not in the markdown content. The system will automatically display the appropriate badges based on the front matter metadata.
Directives: You can also use directives in your markdown content to add badges inline:
:ak-version[2025.4] - Shows when a feature was introduced (requires semantic version):ak-preview - Indicates preview features:ak-enterprise - Indicates features in our Enterprise offeringExample usage in a heading:
# New Feature :ak-version[2025.4] :ak-preview
Note: When using directives, they should be placed at the end of the heading or paragraph where they apply.
SEO: Use keywords in titles and headings to improve searchability. Include relevant terms that users might search for, but avoid keyword stuffing. Focus on natural, descriptive language that accurately represents the content.