Skip to main content

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.

The technical documentation (https://docs.goauthentik.io/docs/) and our integration guides (https://integrations.goauthentik.io/) are built, formatted, and tested using npm. The commands to build the content locally are defined in the Makefile in the root of the repository. Each command is prefixed with docs- or integrations- and corresponds to an NPM script within the website directory.

Guidelines​

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, 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.

  • After submitting a PR, you can view the Netlify Deploy Preview for the PR on GitHub, to check that your content rendered correctly, links work, etc. This is especially useful when using Docusaurus-specific features in your content.

  • Please refer to our Style Guide 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 templates 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 they keep the documentation structure and headings consistent.

tip

If you encounter build check fails, or issues you with your local build, you might need to run make docs-install in order to get the latest build tools and dependencies; we do occasionally update our build tools.

Setting up a docs development environment​

Prerequisites​

Install the required dependencies on macOS using Homebrew:

brew install node@24

Clone and fork the authentik repository​

git clone https://github.com/goauthentik/authentik

The documentation, integration guides, API docs, and the code are in the same GitHub repo, so if you have cloned and forked the repo, you already have the docs and integration guides.

Set up your local build tools​

Run the following command to install or update the build tools for both the technical docs and integration guides.

make docs-install

Installs or updates the build dependencies such as Docusaurus, Prettier, and ESLint. You should run this command when you are first setting up your writing environment, and also if you encounter build check fails either when you build locally or when you push your PR to the authentik repository. Running this command will grab any new dependencies that we might have added to our build tool package.

Writing or modifying technical docs​

In addition to following the Style Guide please review the following guidelines about our technical documentation (https://docs.goauthentik.io/docs/):

  • For new entries, make sure to add any new pages to the /docs/sidebar.mjs file. Otherwise, the new page will not appear in the table of contents to the left.

  • Always be sure to run the make docs 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. In general, check on the health of your build before pushing to the authentik repo, and also check on the build status of your PR after you create it.

For our technical documentation (https://docs.goauthentik.io/docs/), the following commands are used:

Build locally​

make docs

This command is a combination of make docs-lint-fix and make docs-build. It is important to run this command before committing changes because linter errors will prevent the build checks from passing.

Live editing​

make docs-watch

Starts a local development server for the documentation site and opens a preview in your browser. This command will automatically rebuild your local documentation site in real time, as you write or make changes to the Markdown files in the website/docs directory.

Writing or modifying integration guides​

In addition to following the Style Guide please review the following guidelines about our integration guides (https://integrations.goauthentik.io/).

  • For new integration documentation, please use the Integrations template in our Github repo at /website/integrations/template/service.md.

  • 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.

  • Make sure to create a directory for your service in a fitting category within /website/integrations/.

Sidebars and categories

You no longer need to modify the integrations sidebar file manually. This is now automatically generated from the categories in /website/integrations/categories.mjs.

When authoring integration guides, the following commands are used:

Build locally​

make integrations

This command is a combination of make docs-lint-fix and make integrations-build. This command should always be run on your local branch before committing your changes to a pull request to the authentik repo. It is important to run this command before committing changes because linter errors will prevent the build checks from passing.

Live editing​

make integrations-watch

Starts a local development server for the integrations site and opens a preview in your browser. This command will automatically rebuild your local integrations site in real time, as you write or make changes to the Markdown files in the website/integrations directory.

Page routing and URLs​

Every documentation page you see on our website starts as a simple Markdown file in our repository. When you create or edit these files, our build system automatically transforms them into web pages with predictable URLs.

Converting file paths to URLs​

Let's take a look at the file path of the Style Guide page:

/website/docs/developer-docs/docs/style-guide.mdx

Compared to the URL path of this page, there are a few differences:

  • The website/docs prefix is dropped.
  • File extensions are removed.
  • A trailing slash is added.

This results in the following URL path:

https://docs.goauthentik.io/developer-docs/docs/style-guide/

The final published URL is made possible with a combination of Docusaurus's routing system and Netlify's redirects.

The sidebar files define the navigation structure of the documentation pages.

Redirects​

Sometimes we need to move pages or change URLs. Instead of breaking bookmarks and links, we can define a redirect to automatically send readers from old URLs to new ones.

All our redirects are defined within three files:

A _redirects file contains a list of rules that define how to handle requests, each of which has the following format:

  1. The source URL path (i.e the old URL to match against).
  2. The destination URL path (i.e. the new URL to redirect to).
  3. The HTTP status code to use when redirecting, followed by an exclamation mark (!).

For example, if we moved our applications page:

website/docs/static/_redirects
# Source URL Path  | Destination URL Path           | Status Code
/core/applications   /add-secure-apps/applications/   302!

Anyone visiting the old URL will automatically land on the new page using a combination of Netlify and Docusaurus.

Initial page loads (server-side)​

When a reader first visits a documentation page or refreshes their browser:

  1. Their browser requests the URL from our server (Netlify).
  2. Netlify checks if that exact page exists.
  3. If not, it checks our _redirects file for a matching rule.
  4. The server sends back the correct page, or a 404 if no matching rule exists.

When a reader clicks a link to another documentation page:

  1. Docusaurus intercepts the click (no server request needed).
  2. The URL in the browser's address bar changes.
  3. Docusaurus router fetches the new page content without a full reload.

If Docusaurus's router attempts to render a page that does not exist, the _redirects file will be used to determine if a redirect rule should be applied, without a server request or a full reload.

Whether the reader is viewing a page for the first time or navigating between pages, this arrangement allows us to have a single source of truth for all URLs, ensuring that each page remains consistently accessible across authentik versions and throughout our three Docusaurus deployments (Topics, Integrations, and API).

Updating a page's URL​

Every URL is a promise

When someone bookmarks a page or shares a link, they expect it to keep working.

Before changing any URL, ask yourself:

  • Is this move absolutely necessary?
  • Could better organization be achieved without moving files?
  • Will this help or confuse readers migrating between authentik versions?

Remember, Cool URIs don't change!

Moving a documentation page to a new location requires updating a sidebar.mjs and _redirects file.

  1. Take note of the page's current URL path in the browser's address bar.
  2. Move the Markdown file to the new location.
  3. Add a new redirect rule to the _redirects file in the respective documentation directory.
  4. Update the sidebar.mjs file in the respective documentation directory.