website: latest migration to new structure (#11522)

* first pass * dependency shenanigans * move blueprints * few broken links * change config the throw errors * internal file edits * fighting links * remove sidebarDev * fix subdomain Signed-off-by: Jens Langhammer <jens@goauthentik.io> * fix relative URL Signed-off-by: Jens Langhammer <jens@goauthentik.io> * fix mismatched package versions Signed-off-by: Jens Langhammer <jens@goauthentik.io> * fix api reference build Signed-off-by: Jens Langhammer <jens@goauthentik.io> * test tweak * links hell * more links hell * links hell2 * yep last of the links * last broken link fixed * re-add cves Signed-off-by: Jens Langhammer <jens@goauthentik.io> * add devdocs redirects * add dir * tweak netlify.toml * move latest 2 CVES into dir * fix links to moved cves * typoed title fix * fix link * remove banner * remove committed api docs Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * integrations: remove version dropdown Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * Update Makefile Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * change doc links in web as well Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * fix some more docs paths Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * fix more docs paths Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * ci: require ci-web.build for merging Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> * Revert "ci: require ci-web.build for merging" This reverts commit b99a4842a9. * remove sluf for Application * put slug back in * minor fix to trigger deploy --------- Signed-off-by: Jens Langhammer <jens@goauthentik.io> Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> Co-authored-by: Tana M Berry <tana@goauthentik.com> Co-authored-by: Jens Langhammer <jens@goauthentik.io> Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
2024-10-08 14:07:19 -05:00
parent 9200a598ec
commit 9a89a5f94b
336 changed files with 2624 additions and 871 deletions
--- a/website/docs/developer-docs/docs/style-guide.mdx
+++ b/website/docs/developer-docs/docs/style-guide.mdx
@ -0,0 +1,149 @@
+---
+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.
+
+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 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
+
+-   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.
+
+-   You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions.
+
+## Terminology
+
+### authentik names
+
+-   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. :-)
+
+-   Our company name is Authentik Security, Inc. but in non-legal documentation you can shorten it to Authentik Security.
+
+### Industry terms, technology, and other tools
+
+-   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.
+
+-   Try to avoid using abbreviations if possible.
+
+-   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.
+
+## Writing style
+
+-   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."
+
+-   Our documentation uses American English ("z" not "s").
+
+-   Use the present tense and active voice in almost all cases:
+
+    -   DON'T: "The Applications page will be loaded."
+
+    -   DO: "The Applications page displays."
+
+-   Phrasing should never blame the user, and should be subjective:
+
+    -   DON'T: "Never modify the default file."
+
+    -   DO: "We recommend that you do not modify the default file, because this can result in unexpected issues."
+
+## Formatting
+
+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.
+
+### Fonts and font styling
+
+-   When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use **bold** text.
+
+-   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.
+
+-   Use `code` format when referring to:
+
+    -   commands
+    -   file paths
+    -   file names
+    -   directory names
+    -   code snippets (single line or a block of code)
+
+-   For variables or placeholders use _italic_ font for the variable, and use place-holder names that makes it obvious that the user needs to replace it.
+
+    Example: <kbd>https://<em>company-domain</em>/source/oauth/callback/<em>source-slug</em></kbd>
+
+    When using variables in code snippets, make sure to specify if the value is something the user needs to define, is system-defined or generated.
+
+-   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.
+
+### Titles and headers
+
+-   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:
+
+    -   Configure your provider
+    -   Configure the Google Workspace provider
+
+-   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".
+
+-   Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance".
+
+### Examples
+
+When you want to show an example (say, a code snippet), use a new line, bold text, and a semi-colon, like this:
+
+    **Example**:
+    This expression policy uses an expression based on the user's name.
+    ```
+    if request.context["pending_user"].username == "marie":
+      return True
+    return False
+    ```
+
+### Notes and warnings
+
+Use the following convention for a note:
+
+```
+:::info
+Write your note here.
+:::
+```
+
+:::info
+Write your note here.
+:::
+
+For a warning, use this:
+
+```
+:::warning
+Write your note here.
+:::
+```
+
+:::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.)
--- a/website/docs/developer-docs/docs/templates/combo.md
+++ b/website/docs/developer-docs/docs/templates/combo.md
@ -0,0 +1,55 @@
+---
+title: "Combination topic"
+---
+
+:::info
+**How to use this template**: start with the markdown version of the template, either by copying the [`combo.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
+
+```
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/combo.tmpl.md
+```
+
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
+:::
+
+For a combo topic, the title is typically the name of the feature ("Branding" or "Remote Access Control").
+
+In this first section, right after the title but with no header, write one or two sentences about the task. Keep it brief, just an overview.
+
+## About feature XYZ
+
+In this section, go into a deeper explanation of the feature, provide typical use cases, etc.
+
+### More info about the feature, a sub-category of info
+
+Use this section if there are several big topics or categories of info that the reader needs to know about the feature or task. Add as many of these sections as needed.
+
+## Prerequisites (optional section)
+
+In this section, inform the reader of anything they need to do, or have configured or installed, before they start following the procedural instructions below.
+
+## Overview of steps/workflow (optional section)
+
+If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familairize themselves with the 50,000 meter view before they dive into the detailed steps.
+
+## First several group steps
+
+If the task involves a lot of steps, try to group them into similar steps and have a Head3 or Head4 title for each group.
+
+In this section, help the reader get oriented... where do they need to be (i.e. in the GUI, on a CLI, etc).
+
+Have a separate paragraph for each step.
+
+_Start instructions with the desired goal_, followed by the instructions. For example, in this sentence: "To define a new port number, navigate to the Admin interface, and then to the **Settings** tab." we first read the goal (to define a new port) and then we see the instructions.
+
+## Next step of grouped steps (if a second group is needed)
+
+Continue with the steps...
+
+Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words.
+
+Provide as many code snippets and examples as needed.
+
+## Verify the steps
+
+Use a heading such as "Verify your installation" or "Verify successful configuration". Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.
--- a/website/docs/developer-docs/docs/templates/combo.tmpl.md
+++ b/website/docs/developer-docs/docs/templates/combo.tmpl.md
@ -0,0 +1,43 @@
+---
+title: "Markdown template: combo"
+---
+
+add brief description of the feature/functionality
+
+## About feature XYZ
+
+In this section, go into a deeper explanation of the feature, provide typical use cases, etc.
+
+:::info
+if needed, use this syntax to add a note (info) or warning (warning).
+:::
+
+### More info about the feature, a sub-category of info
+
+Use this section if there are several big topics or categories of info that the reader needs to know about the feature or task. Add as many of these sections as needed.
+
+## Prerequisites
+
+bullet list of pre-reqs
+
+## Overview of steps/workflow (Optional, only if there are a lot of steps)
+
+describe the 50,000 meter view before they dive into the detailed steps, using a bullet list of the main steps, or even a diagram of the workflow.
+
+## first several group steps
+
+1. first step
+
+2. second step
+
+3. third step
+
+if you need a tabbed section to represent diff processes or code snippets for diff install environments, use an MDX tabbed component.
+
+## next step of grouped steps, if needed
+
+Continue with the steps...
+
+## verify the steps
+
+add verification steps
--- a/website/docs/developer-docs/docs/templates/conceptual.md
+++ b/website/docs/developer-docs/docs/templates/conceptual.md
@ -0,0 +1,35 @@
+---
+title: "Conceptual topic"
+---
+
+:::info
+**How to use this template**: start with the markdown version of the template, either by copying the [`conceptual.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
+
+```
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/conceptual.tmpl.md
+```
+
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
+:::
+
+Use a title that focuses on the feature, component, or technology you are writing about... for example, "About authentik polices" or "Understanding outposts". For conceptual docs, the verb in the title should indicate a concept, such as "About" or "Overview" or "Understanding", followed by the noun (the component or object you are writing about).
+
+In this first section, immediately after the title, write one or two sentences about the feature, component, or technology. The following sections can help break up the content.
+
+## Common use cases (optional section)
+
+In this optional section, provide some example use cases for the feature. Who would use it, WHY? If you mention HOW to use the feature, be sure to link off to the related procedural doc. Also share situations where users might NOT want to use the feature; for example, if the feature is intended for a specific environment.
+
+## Overview of feature/component
+
+Dive deeper into explaining the concepts behind the feature/component.
+
+Write about the feature/functionalilty from the user's perspective. What is this feature used for, why should they use it, are there situations where they should **_not_** use it?
+
+> Pro Tip: If you were writing the related procedural topic, and you found that you had a lot to say about the topic, this is exactly where that info would go (not crowded up at the top of the procedural topic!).
+
+Cover anything the user needs to know about the feature. If there are Reference docs or a related procedural doc for this feature or component, be sure to link to them from this page.
+
+## Important considerations
+
+List anything that might be critical for user to know, such as situations where this feature might not be ideal, or pre-configs that need to be set, etc.
--- a/website/docs/developer-docs/docs/templates/conceptual.tmpl.md
+++ b/website/docs/developer-docs/docs/templates/conceptual.tmpl.md
@ -0,0 +1,21 @@
+---
+title: "Markdown template: conceptual"
+---
+
+Write a few sentences introducing the feature/component/technology.
+
+:::info
+if needed, use this syntax to add a note (info) or warning (warning)
+:::
+
+## Common use cases
+
+Provide a few use cases, with examples/scenarios when possible.
+
+## About feature x
+
+Provide more conceptual details.
+
+##Important considerations
+
+List anything users should know before implementing the feature/technology.
--- a/website/docs/developer-docs/docs/templates/index.md
+++ b/website/docs/developer-docs/docs/templates/index.md
@ -0,0 +1,23 @@
+---
+title: "Templates"
+---
+
+In technical documentation, there are document "types" (similar to how there are data types). We have templates for the different types, to make it super-easy for whomever wants to contribute some documentation!
+
+The most common types are:
+
+-   [**Combo**](./combo.md): For most topics (unless they are very large and complex), we can combine the procedural and conceptual information into a single document. A handy guideline to follow is: "If the actual 1., 2., 3. steps are buried at the bottom, and a reader has to scroll multiple times to find them, then the combo approach is _not_ the right one".
+
+-   [**Procedural**](./procedural.md): these are How To docs, the HOW information, with step-by-step instructions for accomplishing a task. This is what most people are looking for when they open the docs... and best practice is to separate the procedural docs from long, lengthy conceptual or reference docs.
+
+-   [**Conceptual**](./conceptual.md): these docs provide the WHY information, and explain when to use a feature (or when not to!), and general concepts behind the feature or functionality.
+
+-   [**Reference**](./reference.md): this is typically tables or lists of reference information, such as configuration values, or functions, or most commmonly APIs.
+
+### Add a new integration
+
+To add documentation for a new integration (with support level Community or Vendor), please use the integration templates [`service.md`](https://github.com/goauthentik/authentik/blob/main/website/integrations/template/service.md) from our GitHub repo. You can download the template using the following command:
+
+```shell
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/integrations/template/service.md
+```
--- a/website/docs/developer-docs/docs/templates/procedural.md
+++ b/website/docs/developer-docs/docs/templates/procedural.md
@ -0,0 +1,47 @@
+---
+title: "Procedural topic"
+---
+
+:::info
+**How to use this template**: start with the markdown version of the template, either by copying the [`procedural.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
+
+```
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/procedural.tmpl.md
+```
+
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
+:::
+
+For a procedural topic, use a title that focuses on the task you are writing about. For example, "Add a new Group" or "Edit user profiles". For procedural docs, there should be a verb in the title, and usually the noun (the component or object you are working on). For the title (and all headings) use the infinitive form of the verb (i.e. "add") not the gerund form (i.e. "adding").
+
+In this first section, right after the title, write one or two sentences about the task. Keep it brief; if it goes on too long, then create a separate conceptual topic, in a separate `.md` file. We don't want readers to have to scroll through paragraphs of conceptual info before they get to Step 1.
+
+## Prerequisites (optional section)
+
+In this section, inform the reader of anything they need to do, or have configured or installed, before they start following the procedural instructions below.
+
+## Overview of steps/workflow (optional section)
+
+If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familairize themselves with the 50,000 meter view before they dive into the detailed steps.
+
+## First several group steps
+
+If the task involves a lot of steps, try to group them into similar steps and have a Head3 or Head4 title for each group.
+
+In this section, help the reader get oriented... where do they need to be (i.e. in the GUI, on a CLI, etc).
+
+Have a separate paragraph for each step.
+
+Start instructions with the desired goal, followed by the instructions. For example, in this sentence we first read the goal (to define a new port) and then we see the instructions: "To define a new port number, navigate to the Admin interface, and then to the **Settings** tab."
+
+## Next step of grouped steps (if a second group is needed)
+
+Continue with the steps...
+
+Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words.
+
+Provide as many code snippets and examples as needed.
+
+## Verify the steps
+
+Use a heading such as "Verify your installation" or "Verify successful configuration". Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.
--- a/website/docs/developer-docs/docs/templates/procedural.tmpl.md
+++ b/website/docs/developer-docs/docs/templates/procedural.tmpl.md
@ -0,0 +1,35 @@
+---
+title: "Markdown template: procedural"
+---
+
+add brief description of the feature/functionality
+
+:::info
+if needed, use this syntax to add a note (info) or warning (warning)
+:::
+
+## Prerequisites
+
+bullet list of pre-reqs
+
+## Overview of steps/workflow
+
+describe the 50,000 meter view before they dive into the detailed steps, using a bullet list of the main steps, or even a diagram of the workflow.
+
+## first several group steps
+
+1. first step
+
+2. second step
+
+3. third step
+
+if you need a tabbed section to represent diff processes or code snippets for diff install environments, use an MDX tabbed component.
+
+## next step of grouped steps, if needed
+
+Continue with the steps...
+
+## verify the steps
+
+add verification steps
--- a/website/docs/developer-docs/docs/templates/reference.md
+++ b/website/docs/developer-docs/docs/templates/reference.md
@ -0,0 +1,39 @@
+---
+title: "Reference topic"
+---
+
+:::info
+**How to use this template**: start with the markdown version of the template, either by copying the [`reference.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
+
+```
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/reference.tmpl.md
+```
+
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
+:::
+
+Create a title that specifies the component you are documenting. For example, "Group attributes".
+
+Provide a sentence or two about the topic.
+
+Reference documentation provides details, values, syntax, etc., about specific programming elements.
+
+The most common type of reference documentation is for REST APIs; the request syntax, a successful response, any parameters such as query, header, or request body parameters, and possible http status codes.
+
+Other types of reference content include lists of functions, parameters, object properties, event actions, and attributes.
+
+## Head 2
+
+Use a title that is descriptive, such as "User object attributes" or "Expression policy functions".
+
+Use tables, bullet lists, Head3s... whatever you need to clearly present the values.
+
+Be sure to use a sentence after every heading, to explain what the section is about, how the values are used, etc.
+
+### Head 3 (optional, if needed)
+
+Add a sentence explaining the following grouping.
+
+### Head 3 (optional, if needed)
+
+Add a sentence explaining the following grouping.
--- a/website/docs/developer-docs/docs/templates/reference.tmpl.md
+++ b/website/docs/developer-docs/docs/templates/reference.tmpl.md
@ -0,0 +1,19 @@
+---
+title: "Markdown template: reference"
+---
+
+Write a few sentences introducing the feature/component/technology, and state that this page contains refeerence materials.
+
+:::info
+if needed, use this syntax to add a note (info) or warning (warning)
+:::
+
+## Head 2
+
+After a brief description of this section, list the reference values.
+
+Consider using a table if that is cleaner looking.
+
+### Head 3 (optional, if needed)
+
+After a brief description of this section, list the reference values.
--- a/website/docs/developer-docs/docs/writing-documentation.md
+++ b/website/docs/developer-docs/docs/writing-documentation.md
@ -0,0 +1,61 @@
+---
+title: Writing documentation
+---
+
+Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic.
+
+Adhering to the following guidelines will help us get your PRs merged much easier and faster, with fewer edits needed.
+
+-   Ideally, when you are making contributions to the documentation, you should fork and clone our repo, then [build it locally](#set-up-your-local-build), so that you can test the docs and run the required linting and spell checkers before pushing your PR. While you can do much of the writing and editing within the GitHub UI, you cannot run the required linters from the GitHub UI.
+
+-   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.
+
+-   Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow our style guidelines, they make it a lot easier for you (no blank page frights!), and keeps the documentation structure and headings consistent.
+
+-   To test how the documentation renders you can build locally and then use the Netlify Deploy Preview, especially when using Docusaurus-specific features. You can also run the `make website-watch` command on your local build, to see the rendered pages as you make changes.
+
+-   Be sure to run the `make website` command on your local branch, before pushing the PR to the authentik repo. This command does important linting, and the build check in our repo will fail if the linting has not been done.
+
+-   For new entries, make sure to add any new pages to the appropriate `sidebar.js` file. Otherwise, the new page will not appear in the table of contents to the left.
+
+## Set up your local build
+
+Requirements:
+
+-   Node.js 20 (or greater, we use Node.js 22)
+
+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 `make website` command (which runs `prettier` and other 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:
+
+-   **Installation**: `make website-install`
+
+    This command is required before running any of the following commands, and after upgrading any dependencies.
+
+-   **Formatting**: `make website`, `make website-lint-fix`, or `npm run prettier`
+
+    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 a formatting command before committing changes.
+:::
+
+## Documentation for Integrations
+
+In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.
+
+For new integration documentation, please use the Integrations template in our [Github repo](https://github.com/goauthentik/authentik) at `/website/integrations/template/service.md`.
+
+-   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 sections in an order that makes it easiest for the user to configure.