From cfa1f37aec17ab0ab72e2bfb51b3ba7c949c68e4 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Mon, 3 Feb 2025 19:58:43 -0500 Subject: [PATCH 01/17] website/docs: style guide: revamp --- .../docs/developer-docs/docs/style-guide.mdx | 239 +++++++++++------- 1 file changed, 152 insertions(+), 87 deletions(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 39e74ddede3c..8c45c17402e5 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -2,151 +2,216 @@ title: Style Guide --- -The Style Guide provides guidelines to ensure that the authentik documentation is easy to read and uses similar phrasing, formatting, and tone. +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 contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic. To make the review and merging of your contributions faster and easier, please follow the [writing documentation](./writing-documentation.md) guidelines. +If you notice any inconsistencies, feel free to open an [Issue](https://github.com/goauthentik/authentik/issues) or submit a [Pull Request](https://github.com/goauthentik/authentik/pulls) to address them. -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. +- [General Style Guidelines](#general-style-guidelines) +- [Terminology](#terminology) +- [Writing Style](#writing-style) +- [Word Choices](#word-choices) +- [Formatting Guidelines](#formatting-guidelines) +- [Component-Based Formatting](#component-based-formatting) +- [Error Message Formatting & Troubleshooting](#error-messages) +- [Accessibility Best Practices](#accessibility) +- [React Component Imports](#react-component-imports) +- [Notes and Warnings](#notes-and-warnings) -## General style guidelines - -- Try to order the documentation sections in the order that makes it easiest for the user to follow. That is, order the sections in the same order as the actual workflow used to accomplish the task. - -- Use headings (sub-titles) to break up long documents, and make it easier to find a specific section. +--- -- Add cross-reference links to related content whenever possible. +## General Style Guidelines -- You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions. +- **Logical Order:** 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. +- **Headings:** 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. +- **Cross-References:** 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. +- **Relative Paths:** Use relative paths when linking to documentation files. This will ensure links are automatically updated if file paths change in the future. +- **Markdown File Type:** The standard file type for documentation is `.md`. Use `.mdx` only if React components, such as interactive elements, are required. ## Terminology -### authentik names +### authentik Naming Conventions -- The product name authentik should always start with a lower-case "a" and end with a "k". Even if it is the first word in a sentence. :-) +- The product name **authentik** should always be written with a lowercase "a" and a "k" at the end, even if it begins a sentence. This consistent style should be followed throughout the documentation. +- The company name is **Authentik Security, Inc.**, but for non-legal documentation, you may shorten it to **Authentik Security**. -- Our company name is Authentik Security, Inc. but in non-legal documentation you can shorten it to Authentik Security. +### Industry Terms and Technology Names -### Industry terms, technology, and other tools +- When referring to external tools or industry terms, always use the exact capitalization and naming conventions that the product or company uses. Refer to their website or official documentation for the proper formatting. For example, use "OAuth", "SAML", or "Docker" as per the official conventions. +- Avoid abbreviations unless they are well-known and widely recognized (e.g., SSO, MFA, RBAC). +- If an acronym is used less frequently, spell out its full meaning when first mentioned, followed by the acronym in parentheses. For instance, "Security Assertion Markup Language (SAML)". -- When referring to external tools, or an industry term or technology, always follow the exact capitalization that the product or company itself uses on their website, in their official documentation, or what the industry uses in consensus. +## Writing Style -- Try to avoid using abbreviations if possible. +- **Tone:** 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"). +- **Language:** The documentation uses **American English** spelling conventions (e.g., "customize" instead of "customise"). +- **Voice:** Use **active voice** and present tense for clear, direct communication. + - **DON'T:** "The Applications page will be loaded." + - **DO:** "The Applications page displays." +- **User-friendly phrasing:** Avoid phrasing that blames the user. Be subjective and polite when providing instructions. + - **DON'T:** "Never modify the default file." + - **DO:** "We recommend that you do not modify the default file, as doing so may result in unexpected issues." -- Use acronyms where it makes sense (for commonly used terms like SAML or RBAC). If an acronym is less-known, spell it out in parentheses after the first use. +## Word Choices -## Writing style +### "May" versus "Might" versus "Can" -- authentik documentation strives for a friendly, but not overly so, tone. It's ok to be a little bit conversational, and to address the reader in second person: "Next, you need to configure the log in settings." +- Typically, avoid using the word "may" in technical writing, as it implies permission rather than ability to perform an action. Instead, use **"can"** to suggest possibility. +- **"Might"** should be used to indicate that something could happen under certain conditions, but use it sparingly. It implies unpredictability, which can be undesirable in software documentation. -- Our documentation uses American English ("z" not "s"). + - **DON'T:** "You may use an Expression policy to enforce MFA adherence." + - **DO:** "You can use an Expression policy to enforce MFA adherence." + - **DO:** "Values might differ depending on the source of the property mappings." -- Use the present tense and active voice in almost all cases: +### "Login", "Log in", and "Log in to" - - DON'T: "The Applications page will be loaded." +- As a noun or descriptive term, use **login** (e.g., "The login panel"). +- As a verb, use **"log in"** (e.g., "This stage prompts the user to log in"). +- As a verb followed by the proposition **"to"**, use **"log in to"** (e.g., "Log in to the application"). - - DO: "The Applications page displays." +## Formatting Guidelines -- Phrasing should never blame the user, and should be subjective: +### Fonts and Font Styling - - DON'T: "Never modify the default file." +- Use **bold** to highlight: - - DO: "We recommend that you do not modify the default file, because this can result in unexpected issues." + - UI elements such as field names, labels, buttons, or options (e.g., **Save** button, **Username** field). + - Key actions in instructions (e.g., **Click Next**). + - Important terms or concepts on first mention in a section. -## Formatting +- Use _italic_ for: -Formatting in documentation is important; it improves comprehension and readability, and allows the brain to more quickly determine what is a command or a configuration setting, what is a field name, or what is a variable. + - Variables or placeholders to indicate that the value should be replaced by the user (e.g., _your-domain.com_). + - Emphasis, but sparingly, to avoid overuse. -### Fonts and font styling +- Use `code formatting` for: -- When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use **bold** text. + - Commands (e.g., `docker run`). + - File paths, file names, and directory names (e.g., `/usr/local/bin/`). + - Inline code snippets (e.g., `.env`). -- When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting. Link to the relevant documentation when possible. +- When handling URLs: + - For URLs that users need to enter as values, apply `code formatting` and _italicize_ the placeholder variables to indicate user-defined inputs (e.g., `https://your-domain/application/oauth/callback/`). + - When referring to URLs within sentences or instructions, do not use code formatting. Instead, use regular text (e.g., "Navigate to https://example.com to begin the configuration process"). -- Use `code` format when referring to: +### Titles and Headers - - commands - - file paths - - file names - - directory names - - code snippets (single line or a block of code) +- 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. -- Use _italic_ font for variables or placeholders to make it clear they need to be replaced. Choose placeholder names that highlight their purpose, ensuring users understand what to update. + - **DO:** "Configure the Google Workspace provider" + - **DON'T:** "CONFIGURE THE GOOGLE WORKSPACE PROVIDER" + - **DON'T:** "Configure The Google Workspace Provider" -- When handling URLs: +- Ensure 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." - - For URLs entered as values or defined in fields, apply `code formatting` and _italicize_ any variables within them to emphasize that placeholders require user input. Example: `https://company-domain/source/oauth/callback/source-slug`. - - When mentioning URLs in text or within procedural instructions, omit code formatting. For instance: "In your browser, go to https://example.com." +- Use the **imperative verb form** in procedural topics. For example, use "Configure your instance" instead of "Configuring your instance." - Clearly indicate whether variables in code snippets need to be defined by the user, are system-provided, or generated. +### Examples -- 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. +When showing an example, use a new line, **bold** text, and a semi-colon to mark it as an example: -### Titles and headers +**Example**: +This expression policy checks the user's name before taking action. -- Both titles and headers (H1, H2, H3) use sentence style capitalization, meaning that only the first word is capitalized. However, if the title or header includes a proper noun (name of a product, etc) then capitalize those words. - Examples: +``` +if request.context["pending_user"].username == "marie": + return True +return False +``` - - Configure your provider - - Configure the Google Workspace provider +## Component-Based Formatting -- Make sure the title/header is descriptive, and tells the reader what that section is about. Try to avoid titles or headers like "Overview". Instead say "About authentik policies". +### Multiline Code Blocks -- Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance". +For displaying multiline code blocks, especially when variables need to be defined, use the **`IntegrationsMultilineCodeblock`** React component: -### Examples +```jsx +import IntegrationsMultilineCodeblock from "@site/src/components/Integrations/IntegrationsCodeblock"; + + + {` +OIDC_DISCOVERY_URL=https://authentik.company/application/o/your-application-slug/ +`} +; +``` -When you want to show an example (say, a code snippet), use a new line, bold text, and a semi-colon, like this: +This is especially useful for configuration files like JSON, YAML, or `.env` files, where placeholders must be replaced. - **Example**: - This expression policy uses an expression based on the user's name. - ``` - if request.context["pending_user"].username == "marie": - return True - return False - ``` +### Tabs for Multiple Configurations -### Notes and warnings +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. -Use the following convention for a note: +```jsx +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + OIDC configuration details go here. + SAML configuration details go here. +; ``` -:::info -Write your note here. -::: + +Tabs improve readability when presenting different configurations or setup options. + +## React Component Imports + +When importing React components (e.g.: Tabs), imports must be placed at the top of the file. + +## Error Message Formatting & Troubleshooting + +When documenting error messages: + +- Display the expected error message format. +- Explain possible causes. +- Offer solutions. + +Example: + +```sh +Error: Authentication failed. Invalid credentials. ``` -:::info -Write your note here. -::: +**Possible causes:** + +- Incorrect username or password. +- Account is locked due to too many failed login attempts. + +**Solution:** + +- Verify your username and password. +- Reset your password if necessary. +- Contact an administrator if your account is locked. -For a warning, use this: +## Accessibility Best Practices + +- Avoid using color as the sole method of conveying information (e.g., "Click the red button"). Instead, use descriptive labels to ensure accessibility. +- Provide **descriptive link text**. Avoid using generic terms like "Click here". Be specific about where the link will take the user. + - **DON'T:** "Click here." + - **DO:** "See the [Authentication Settings](/) for more details." + +## Notes and Warnings + +For notes and important information: + +**Notes** are formatted using: ``` -:::warning +:::info Write your note here. ::: ``` +**Warnings** are formatted using: + +``` :::warning Write your warning here. ::: - -``` - ``` -## Word choices - -- **May** versus **might** versus **can** - Typically, the word "may" is not used in technical writing, because it implies permission (rather than ability) to do something. Instead use the word "can". Use "might" when the scenario could be different in certain environments. Be sparing with your use of "might"; this word implies unpredictability, not our favorite thing with software. - - - DON'T: "You may use an Expression policy to enforce MFA adherence." - - - DO: "You can use an Expression policy to enforce MFA adherence." - - - Do: "Values might differ depending on the source of the property mappings."" - -- **Login**, **log in**, and **log in to** - As a descriptive term, use one word: "login". (The login panel.) - As a verb, use "log in", with two words. (This stage prompts the user to log in.) - As a verb with the proposition "to", use "log in to". (Log in to the application.) +Use these conventions to ensure that the reader's attention is drawn to crucial information. From 88b91c1f485226f3144373b30730786438b32def Mon Sep 17 00:00:00 2001 From: Dominic R Date: Mon, 3 Feb 2025 20:21:44 -0500 Subject: [PATCH 02/17] fix anchor --- website/docs/developer-docs/docs/style-guide.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 8c45c17402e5..0e007d8c59ad 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -12,8 +12,8 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - [Word Choices](#word-choices) - [Formatting Guidelines](#formatting-guidelines) - [Component-Based Formatting](#component-based-formatting) -- [Error Message Formatting & Troubleshooting](#error-messages) -- [Accessibility Best Practices](#accessibility) +- [Error Message Formatting and Troubleshooting](#error-message-formatting-and-troubleshooting) +- [Accessibility Best Practices](#accessibility-best-practices) - [React Component Imports](#react-component-imports) - [Notes and Warnings](#notes-and-warnings) @@ -162,7 +162,7 @@ Tabs improve readability when presenting different configurations or setup optio When importing React components (e.g.: Tabs), imports must be placed at the top of the file. -## Error Message Formatting & Troubleshooting +## Error Message Formatting and Troubleshooting When documenting error messages: From 6d58abee2e597c535163a749aad68e6ecef5b705 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:38:04 -0500 Subject: [PATCH 03/17] Update style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 0e007d8c59ad..9049b4c76034 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -29,7 +29,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c ## Terminology -### authentik Naming Conventions +### authentik product naming conventions - The product name **authentik** should always be written with a lowercase "a" and a "k" at the end, even if it begins a sentence. This consistent style should be followed throughout the documentation. - The company name is **Authentik Security, Inc.**, but for non-legal documentation, you may shorten it to **Authentik Security**. From c5e2a8a4a4e595aa963d6c14005c8cac1fb91fc1 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:38:27 -0500 Subject: [PATCH 04/17] Update style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 9049b4c76034..9f4d2c7fadc0 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -34,7 +34,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - The product name **authentik** should always be written with a lowercase "a" and a "k" at the end, even if it begins a sentence. This consistent style should be followed throughout the documentation. - The company name is **Authentik Security, Inc.**, but for non-legal documentation, you may shorten it to **Authentik Security**. -### Industry Terms and Technology Names +### Industry terms and technology names - When referring to external tools or industry terms, always use the exact capitalization and naming conventions that the product or company uses. Refer to their website or official documentation for the proper formatting. For example, use "OAuth", "SAML", or "Docker" as per the official conventions. - Avoid abbreviations unless they are well-known and widely recognized (e.g., SSO, MFA, RBAC). From 01f6108d7e6aeda85a236d8ceed0a64eaa2931c6 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:38:39 -0500 Subject: [PATCH 05/17] Update style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 9f4d2c7fadc0..d033bc7013fa 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -19,7 +19,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c --- -## General Style Guidelines +## General style guidelines - **Logical Order:** 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. - **Headings:** 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. From 1da921d38b3d5dc365da92aedda5ec69cd5f56f8 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:39:07 -0500 Subject: [PATCH 06/17] Update website/docs/developer-docs/docs/style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index d033bc7013fa..60dd8694640c 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -40,7 +40,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - Avoid abbreviations unless they are well-known and widely recognized (e.g., SSO, MFA, RBAC). - If an acronym is used less frequently, spell out its full meaning when first mentioned, followed by the acronym in parentheses. For instance, "Security Assertion Markup Language (SAML)". -## Writing Style +## Writing style - **Tone:** 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"). - **Language:** The documentation uses **American English** spelling conventions (e.g., "customize" instead of "customise"). From 865b29c1bf987bc24783fba1185efa02acd786a8 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:39:20 -0500 Subject: [PATCH 07/17] Update website/docs/developer-docs/docs/style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 60dd8694640c..bc06a86a8dbc 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -51,7 +51,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - **DON'T:** "Never modify the default file." - **DO:** "We recommend that you do not modify the default file, as doing so may result in unexpected issues." -## Word Choices +## Word choices ### "May" versus "Might" versus "Can" From a78df478a7481c931be13a45d9f9078293fb2616 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:40:18 -0500 Subject: [PATCH 08/17] Update website/docs/developer-docs/docs/style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index bc06a86a8dbc..d2ed0b2954ec 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -68,7 +68,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - As a verb, use **"log in"** (e.g., "This stage prompts the user to log in"). - As a verb followed by the proposition **"to"**, use **"log in to"** (e.g., "Log in to the application"). -## Formatting Guidelines +## Formatting guidelines ### Fonts and Font Styling From dab34b9f8d50c7aa9be287ded4d133d46ef8016f Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 08:42:29 -0500 Subject: [PATCH 09/17] Update website/docs/developer-docs/docs/style-guide.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index d2ed0b2954ec..a28e70228778 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -93,7 +93,7 @@ If you notice any inconsistencies, feel free to open an [Issue](https://github.c - For URLs that users need to enter as values, apply `code formatting` and _italicize_ the placeholder variables to indicate user-defined inputs (e.g., `https://your-domain/application/oauth/callback/`). - When referring to URLs within sentences or instructions, do not use code formatting. Instead, use regular text (e.g., "Navigate to https://example.com to begin the configuration process"). -### Titles and Headers +### Titles and headers - 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. From 55b10a0290959455ea03102b61e7cc998e786096 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 11:31:27 -0500 Subject: [PATCH 10/17] Tana's suggested format Signed-off-by: Dominic R --- website/integrations/template/service.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/website/integrations/template/service.md b/website/integrations/template/service.md index 92b9b5169910..8e4f263d5956 100644 --- a/website/integrations/template/service.md +++ b/website/integrations/template/service.md @@ -21,17 +21,27 @@ The following placeholders are used in this guide: This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. ::: -## Service configuration +## authentik configuration -Insert Service configuration +To support the integration of *Service* with authentik, you need to create an application/provider pair in authentik. -1. Write first step here... +*Any specific info about this integration can go here.* -2. Continue with steps.... +**Create an application and provider in authentik** -## authentik configuration +In the authentik Admin Interface, navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create.)** + +- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - *If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example.* +- **Choose a Provider type** + - *If there is a specific provider type required, state that here.* +- **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - *If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example.* +- **Configure Bindings** *(optional):* you can create a [binding](https://docs.goauthentik.io/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user’s **My applications** page. -Insert authentik configuration +## Service configuration + +Insert Service configuration 1. Write first step here... From 375fc18ac1ff4ab0feee2577fb8b6e2313cde1a2 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Feb 2025 11:39:28 -0500 Subject: [PATCH 11/17] lint --- website/integrations/template/service.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/integrations/template/service.md b/website/integrations/template/service.md index 8e4f263d5956..92acca247d44 100644 --- a/website/integrations/template/service.md +++ b/website/integrations/template/service.md @@ -23,21 +23,21 @@ This documentation lists only the settings that you need to change from their de ## authentik configuration -To support the integration of *Service* with authentik, you need to create an application/provider pair in authentik. +To support the integration of _Service_ with authentik, you need to create an application/provider pair in authentik. -*Any specific info about this integration can go here.* +_Any specific info about this integration can go here._ **Create an application and provider in authentik** In the authentik Admin Interface, navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create.)** - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. - - *If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example.* + - _If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example._ - **Choose a Provider type** - - *If there is a specific provider type required, state that here.* + - _If there is a specific provider type required, state that here._ - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - - *If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example.* -- **Configure Bindings** *(optional):* you can create a [binding](https://docs.goauthentik.io/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user’s **My applications** page. + - _If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example._ +- **Configure Bindings** _(optional):_ you can create a [binding](https://docs.goauthentik.io/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user’s **My applications** page. ## Service configuration From 15e97b76a7c935a122a45328b2d5e96b294e6c7f Mon Sep 17 00:00:00 2001 From: Dominic R Date: Wed, 5 Mar 2025 12:46:22 -0500 Subject: [PATCH 12/17] wip Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index a28e70228778..9760bdf455f0 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -125,7 +125,7 @@ return False For displaying multiline code blocks, especially when variables need to be defined, use the **`IntegrationsMultilineCodeblock`** React component: ```jsx -import IntegrationsMultilineCodeblock from "@site/src/components/Integrations/IntegrationsCodeblock"; +import IntegrationsMultilineCodeblock from "@site/src/components/MultilineCodeblock" {` From 3788e7cdcc28c4ac45bfbc72df9c1def4ba9443c Mon Sep 17 00:00:00 2001 From: Dominic R Date: Wed, 5 Mar 2025 12:53:05 -0500 Subject: [PATCH 13/17] wip Signed-off-by: Dominic R --- website/integrations/template/service.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/website/integrations/template/service.md b/website/integrations/template/service.md index 92acca247d44..13af35334f9c 100644 --- a/website/integrations/template/service.md +++ b/website/integrations/template/service.md @@ -27,9 +27,10 @@ To support the integration of _Service_ with authentik, you need to create an ap _Any specific info about this integration can go here._ -**Create an application and provider in authentik** +### Create an application and provider in authentik -In the authentik Admin Interface, navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create.)** +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create**.) - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. - _If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example._ @@ -37,7 +38,9 @@ In the authentik Admin Interface, navigate to **Applications** > **Applicatio - _If there is a specific provider type required, state that here._ - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - _If there are any specific settings required, list them here. Refer to the [ownCloud integration documentation](https://github.com/goauthentik/authentik/blob/main/website/integrations/services/owncloud/index.md) for a complex requirements example._ -- **Configure Bindings** _(optional):_ you can create a [binding](https://docs.goauthentik.io/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user’s **My applications** page. +- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. + +3. Click **Submit** to save the new application and provider. ## Service configuration From b534f09605f89b0ad45634664f576c005de7a3c6 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 13 Mar 2025 18:42:12 +0000 Subject: [PATCH 14/17] wip lint --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 9760bdf455f0..6773e7c42627 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -125,7 +125,7 @@ return False For displaying multiline code blocks, especially when variables need to be defined, use the **`IntegrationsMultilineCodeblock`** React component: ```jsx -import IntegrationsMultilineCodeblock from "@site/src/components/MultilineCodeblock" +import IntegrationsMultilineCodeblock from "@site/src/components/MultilineCodeblock"; {` From 132282a497b8bd8a38ef0a51a1332a3e080520ea Mon Sep 17 00:00:00 2001 From: Dominic R Date: Fri, 14 Mar 2025 17:52:19 -0400 Subject: [PATCH 15/17] Update website/docs/developer-docs/docs/style-guide.mdx Signed-off-by: Dominic R --- website/docs/developer-docs/docs/style-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 6773e7c42627..5940277d8df3 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -4,7 +4,7 @@ title: Style Guide 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. -If you notice any inconsistencies, feel free to open an [Issue](https://github.com/goauthentik/authentik/issues) or submit a [Pull Request](https://github.com/goauthentik/authentik/pulls) to address them. +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](./writing-documentation.md) guidelines. If you notice any inconsistencies, feel free to open an [Issue](https://github.com/goauthentik/authentik/issues) or submit a [Pull Request](https://github.com/goauthentik/authentik/pulls) to address them. - [General Style Guidelines](#general-style-guidelines) - [Terminology](#terminology) From 5ed4ddb98709cc8412f012aa3a848225d0a6089a Mon Sep 17 00:00:00 2001 From: Dominic R Date: Wed, 19 Mar 2025 18:30:30 -0400 Subject: [PATCH 16/17] tana --- .../docs/developer-docs/docs/style-guide.mdx | 85 ++++++++++++------- 1 file changed, 53 insertions(+), 32 deletions(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index 5940277d8df3..b64d2f62859b 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -21,11 +21,25 @@ We appreciate all contributions to our documentation — whether it's fixing a t ## General style guidelines -- **Logical Order:** 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. -- **Headings:** 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. -- **Cross-References:** 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. -- **Relative Paths:** Use relative paths when linking to documentation files. This will ensure links are automatically updated if file paths change in the future. -- **Markdown File Type:** The standard file type for documentation is `.md`. Use `.mdx` only if React components, such as interactive elements, are required. +### Logical order + +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. + +### Headings + +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. + +### Cross-references + +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. + +### Relative paths + +Use relative paths when linking to documentation files. This will ensure links are automatically updated if file paths change in the future. + +### Markdown file type + +The standard file type for documentation is `.md`. Use `.mdx` only if React components, such as interactive elements, are required. ## Terminology @@ -42,14 +56,21 @@ We appreciate all contributions to our documentation — whether it's fixing a t ## Writing style -- **Tone:** 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"). -- **Language:** The documentation uses **American English** spelling conventions (e.g., "customize" instead of "customise"). -- **Voice:** Use **active voice** and present tense for clear, direct communication. - - **DON'T:** "The Applications page will be loaded." - - **DO:** "The Applications page displays." -- **User-friendly phrasing:** Avoid phrasing that blames the user. Be subjective and polite when providing instructions. - - **DON'T:** "Never modify the default file." - - **DO:** "We recommend that you do not modify the default file, as doing so may result in unexpected issues." +### Tone + +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"). + +### Language + +The documentation uses **American English** spelling conventions (e.g., "customize" instead of "customise"). + +### Voice + +Use **active voice** and present tense for clear, direct communication. - **DON'T:** "The Applications page will be loaded." - **DO:** "The Applications page displays." + +### User-friendly phrasing + +Avoid phrasing that blames the user. Be subjective and polite when providing instructions. - **DON'T:** "Never modify the default file." - **DO:** "We recommend that you do not modify the default file, as doing so may result in unexpected issues." ## Word choices @@ -120,9 +141,11 @@ return False ## Component-Based Formatting +This section covers the usage of React components within our documentation. Files that use component-based formatting must use the `.mdx` extension. + ### Multiline Code Blocks -For displaying multiline code blocks, especially when variables need to be defined, use the **`IntegrationsMultilineCodeblock`** React component: +For displaying multiline code blocks, especially when variables need to be defined, use the **`IntegrationsMultilineCodeblock`** React component. Insert the following lines wherever you want the code block to appear: ```jsx import IntegrationsMultilineCodeblock from "@site/src/components/MultilineCodeblock"; @@ -138,7 +161,7 @@ This is especially useful for configuration files like JSON, YAML, or `.env` fil ### Tabs for Multiple Configurations -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. +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. Insert the following lines wherever you want the code block to appear: ```jsx import Tabs from "@theme/Tabs"; @@ -158,34 +181,32 @@ import TabItem from "@theme/TabItem"; Tabs improve readability when presenting different configurations or setup options. -## React Component Imports - -When importing React components (e.g.: Tabs), imports must be placed at the top of the file. - ## Error Message Formatting and Troubleshooting When documenting error messages: -- Display the expected error message format. -- Explain possible causes. -- Offer solutions. +- Display the error message +- Explain possible causes +- Offer solutions Example: -```sh -Error: Authentication failed. Invalid credentials. -``` +- **Error message:** + + ```sh + Error: Authentication failed. Invalid credentials. + ``` -**Possible causes:** +- **Possible causes:** -- Incorrect username or password. -- Account is locked due to too many failed login attempts. + - Incorrect username or password + - Account is locked due to too many failed login attempts -**Solution:** +- **Solution:** -- Verify your username and password. -- Reset your password if necessary. -- Contact an administrator if your account is locked. + - Verify your username and password + - Reset your password if necessary + - Contact an administrator if your account is locked ## Accessibility Best Practices From 2b0d22903bbc30390baa9715ef19b7c08e527eda Mon Sep 17 00:00:00 2001 From: Dominic R Date: Wed, 19 Mar 2025 18:55:05 -0400 Subject: [PATCH 17/17] fix --- website/docs/developer-docs/docs/style-guide.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/developer-docs/docs/style-guide.mdx b/website/docs/developer-docs/docs/style-guide.mdx index b64d2f62859b..3da740780282 100644 --- a/website/docs/developer-docs/docs/style-guide.mdx +++ b/website/docs/developer-docs/docs/style-guide.mdx @@ -14,7 +14,6 @@ We appreciate all contributions to our documentation — whether it's fixing a t - [Component-Based Formatting](#component-based-formatting) - [Error Message Formatting and Troubleshooting](#error-message-formatting-and-troubleshooting) - [Accessibility Best Practices](#accessibility-best-practices) -- [React Component Imports](#react-component-imports) - [Notes and Warnings](#notes-and-warnings) ---