website: Bump prettier from 3.3.3 to 3.4.1 in /website (#12205)
* website: Bump prettier from 3.3.3 to 3.4.1 in /website Bumps [prettier](https://github.com/prettier/prettier) from 3.3.3 to 3.4.1. - [Release notes](https://github.com/prettier/prettier/releases) - [Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md) - [Commits](https://github.com/prettier/prettier/compare/3.3.3...3.4.1) --- updated-dependencies: - dependency-name: prettier dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> * update formatting Signed-off-by: Jens Langhammer <jens@goauthentik.io> * sigh Signed-off-by: Jens Langhammer <jens@goauthentik.io> * disable flaky test Signed-off-by: Jens Langhammer <jens@goauthentik.io> --------- Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: Jens Langhammer <jens@goauthentik.io> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jens Langhammer <jens@goauthentik.io>
This commit is contained in:
dependabot[bot]
@ -10,47 +10,47 @@ If you find any documentation that doesn't match these guidelines, feel free to
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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. :-)
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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."
|
||||
- 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").
|
||||
- Our documentation uses American English ("z" not "s").
|
||||
|
||||
- Use the present tense and active voice in almost all cases:
|
||||
- Use the present tense and active voice in almost all cases:
|
||||
|
||||
- DON'T: "The Applications page will be loaded."
|
||||
- DON'T: "The Applications page will be loaded."
|
||||
|
||||
- DO: "The Applications page displays."
|
||||
- DO: "The Applications page displays."
|
||||
|
||||
- Phrasing should never blame the user, and should be subjective:
|
||||
- Phrasing should never blame the user, and should be subjective:
|
||||
|
||||
- DON'T: "Never modify the default file."
|
||||
- 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."
|
||||
- DO: "We recommend that you do not modify the default file, because this can result in unexpected issues."
|
||||
|
||||
## Formatting
|
||||
|
||||
@ -58,37 +58,37 @@ Formatting in documentation is important; it improves comprehension and readabil
|
||||
|
||||
### 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 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.
|
||||
- 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:
|
||||
- Use `code` format when referring to:
|
||||
|
||||
- commands
|
||||
- file paths
|
||||
- file names
|
||||
- directory names
|
||||
- code snippets (single line or a block of code)
|
||||
- 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.
|
||||
- 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.
|
||||
- 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:
|
||||
- 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
|
||||
- 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".
|
||||
- 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".
|
||||
- Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance".
|
||||
|
||||
### Examples
|
||||
|
||||
@ -134,16 +134,16 @@ 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.
|
||||
- **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."
|
||||
- DON'T: "You may use an Expression policy to enforce MFA adherence."
|
||||
|
||||
- DO: "You can 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.""
|
||||
- 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.)
|
||||
- **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.)
|
||||
|
||||
@ -6,13 +6,13 @@ In technical documentation, there are document "types" (similar to how there are
|
||||
|
||||
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".
|
||||
- [**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.
|
||||
- [**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.
|
||||
- [**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.
|
||||
- [**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
|
||||
|
||||
|
||||
@ -6,23 +6,23 @@ Writing documentation for authentik is a great way for both new and experienced
|
||||
|
||||
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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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)
|
||||
- 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.
|
||||
|
||||
@ -32,15 +32,15 @@ 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`
|
||||
- **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`
|
||||
- **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`
|
||||
- **Live editing**: `make website-watch`
|
||||
|
||||
For real-time viewing of changes, as you make them.
|
||||
|
||||
@ -54,8 +54,8 @@ In addition to following the [Style Guide](./style-guide.mdx) please review the
|
||||
|
||||
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.
|
||||
- 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.
|
||||
- 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.
|
||||
- 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