website: Docusaurus 3.8 (#15097)

website: Upgrade Docusaurus. Split API build.
This commit is contained in:
Teffen Ellis
2025-07-23 16:42:01 +02:00
committed by GitHub
parent 35de683959
commit e280159946
26 changed files with 756 additions and 2118 deletions
+91
View File
@@ -0,0 +1,91 @@
name: authentik-ci-api-docs
on:
push:
branches:
- main
- next
- version-*
pull_request:
branches:
- main
- version-*
jobs:
lint:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
command:
- prettier-check
steps:
- uses: actions/checkout@v4
- name: Install Dependencies
working-directory: website/
run: npm ci
- name: Lint
working-directory: website/
run: npm run ${{ matrix.command }}
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: website/package.json
cache: "npm"
cache-dependency-path: website/package-lock.json
- working-directory: website/
name: Install Dependencies
run: npm ci
- uses: actions/cache@v4
with:
path: |
${{ github.workspace }}/website/api/.docusaurus
${{ github.workspace }}/website/api/**/.cache
key: |
${{ runner.os }}-docusaurus-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
restore-keys: |
${{ runner.os }}-docusaurus-${{ hashFiles('**/package-lock.json') }}
- name: Build API Docs via Docusaurus
working-directory: website
env:
NODE_ENV: production
run: npm run build -w api
- uses: actions/upload-artifact@v4
with:
name: api-docs
path: website/api/build
retention-days: 7
deploy:
runs-on: ubuntu-latest
needs:
- lint
- build
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
with:
name: api-docs
path: website/api/build
- uses: actions/setup-node@v4
with:
node-version-file: website/package.json
cache: "npm"
cache-dependency-path: website/package-lock.json
- name: Deploy Netlify (Production)
working-directory: website/api
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
env:
NETLIFY_SITE_ID: authentik-api-docs.netlify.app
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
run: npx netlify deploy --no-build --prod
- name: Deploy Netlify (Preview)
if: github.event_name == 'pull_request' || github.ref != 'refs/heads/main'
working-directory: website/api
env:
NETLIFY_SITE_ID: authentik-api-docs.netlify.app
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
run: npx netlify deploy --no-build --alias=deploy-preview-${{ github.event.number }}
@@ -1,4 +1,4 @@
name: authentik-ci-website
name: authentik-ci-docs
on:
push:
@@ -18,17 +18,18 @@ jobs:
fail-fast: false
matrix:
command:
- lint:lockfile
- prettier-check
steps:
- uses: actions/checkout@v4
- working-directory: website/
- name: Install dependencies
working-directory: website/
run: npm ci
- name: Lint
working-directory: website/
run: npm run ${{ matrix.command }}
test:
build-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
@@ -37,19 +38,14 @@ jobs:
cache: "npm"
cache-dependency-path: website/package-lock.json
- working-directory: website/
name: Install Dependencies
run: npm ci
- name: test
- name: Build Documentation via Docusaurus
working-directory: website/
run: npm test
build:
run: npm run build
build-integrations:
runs-on: ubuntu-latest
name: ${{ matrix.job }}
strategy:
fail-fast: false
matrix:
job:
- build
- build:integrations
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
@@ -58,10 +54,11 @@ jobs:
cache: "npm"
cache-dependency-path: website/package-lock.json
- working-directory: website/
name: Install Dependencies
run: npm ci
- name: build
- name: Build Integrations via Docusaurus
working-directory: website/
run: npm run ${{ matrix.job }}
run: npm run build -w integrations
build-container:
if: ${{ github.repository != 'goauthentik/authentik-internal' }}
runs-on: ubuntu-latest
@@ -115,8 +112,8 @@ jobs:
if: always()
needs:
- lint
- test
- build
- build-docs
- build-integrations
- build-container
runs-on: ubuntu-latest
steps:
+2 -1
View File
@@ -10,7 +10,8 @@ coverage
dist
out
.docusaurus
website/docs/developer-docs/api/**/*
# TODO Replace after moving website to docs
website/api/reference
## Environment
*.env
+10 -34
View File
@@ -4,12 +4,7 @@
{
"label": "authentik/core: make",
"command": "uv",
"args": [
"run",
"make",
"lint-fix",
"lint"
],
"args": ["run", "make", "lint-fix", "lint"],
"presentation": {
"panel": "new"
},
@@ -18,11 +13,7 @@
{
"label": "authentik/core: run",
"command": "uv",
"args": [
"run",
"ak",
"server"
],
"args": ["run", "ak", "server"],
"group": "build",
"presentation": {
"panel": "dedicated",
@@ -32,17 +23,13 @@
{
"label": "authentik/web: make",
"command": "make",
"args": [
"web"
],
"args": ["web"],
"group": "build"
},
{
"label": "authentik/web: watch",
"command": "make",
"args": [
"web-watch"
],
"args": ["web-watch"],
"group": "build",
"presentation": {
"panel": "dedicated",
@@ -52,26 +39,19 @@
{
"label": "authentik: install",
"command": "make",
"args": [
"install",
"-j4"
],
"args": ["install", "-j4"],
"group": "build"
},
{
"label": "authentik/website: make",
"label": "authentik/docs: make",
"command": "make",
"args": [
"website"
],
"args": ["docs"],
"group": "build"
},
{
"label": "authentik/website: watch",
"label": "authentik/docs: watch",
"command": "make",
"args": [
"website-watch"
],
"args": ["docs-watch"],
"group": "build",
"presentation": {
"panel": "dedicated",
@@ -81,11 +61,7 @@
{
"label": "authentik/api: generate",
"command": "uv",
"args": [
"run",
"make",
"gen"
],
"args": ["run", "make", "gen"],
"group": "build"
}
]
+5 -1
View File
@@ -32,8 +32,12 @@ tests/wdio/ @goauthentik/frontend
locale/ @goauthentik/backend @goauthentik/frontend
web/xliff/ @goauthentik/backend @goauthentik/frontend
# Docs & Website
docs/ @goauthentik/docs
# TODO Remove after moving website to docs
website/ @goauthentik/docs
CODE_OF_CONDUCT.md @goauthentik/docs
# Security
SECURITY.md @goauthentik/security @goauthentik/docs
website/docs/security/ @goauthentik/security @goauthentik/docs
# TODO Remove after moving website to docs
website/security/ @goauthentik/security @goauthentik/docs
docs/security/ @goauthentik/security @goauthentik/docs
+1
View File
@@ -18,6 +18,7 @@ RUN --mount=type=bind,target=/work/web/package.json,src=./web/package.json \
COPY ./package.json /work
COPY ./web /work/web/
# TODO: Update this after moving website to docs
COPY ./website /work/website/
COPY ./gen-ts-api /work/web/node_modules/@goauthentik/api
+11 -1
View File
@@ -121,7 +121,7 @@ gen-diff: ## (Release) generate the changelog diff between the current schema a
sed -i 's/}/}/g' diff.md
npx prettier --write diff.md
gen-clean-ts: ## Remove generated API client for Typescript
gen-clean-ts: ## Remove generated API client for TypeScript
rm -rf ${PWD}/${GEN_API_TS}/
rm -rf ${PWD}/web/node_modules/@goauthentik/api/
@@ -251,6 +251,16 @@ integrations-build:
integrations-watch: ## Build and watch the Integrations documentation
npm run start --prefix website -w integrations
docs-api-build:
npm run build --prefix website -w api
docs-api-watch: ## Build and watch the API documentation
npm run build:api --prefix website -w api
npm run start --prefix website -w api
docs-api-clean: ## Clean generated API documentation
npm run build:api:clean --prefix website -w api
#########################
## Docker
#########################
+2 -2
View File
@@ -8,9 +8,9 @@
# make gen-dev-config
# ```
#
# You may edit the generated file to override the configuration below.
# You may edit the generated file to override the configuration below.
#
# When making modifying the default configuration file,
# When making modifying the default configuration file,
# ensure that the corresponding documentation is updated to match.
#
# @see {@link ../../website/docs/install-config/configuration/configuration.mdx Configuration documentation} for more information.
+3 -2
View File
@@ -23,8 +23,9 @@ export const DefaultIgnorePatterns = [
"**/out",
"**/dist",
"**/.wireit",
"website/build/**",
"website/.docusaurus/**",
// TODO: Replace after moving to `docs` directory.
"website/**/build/**",
"website/**/.docusaurus/**",
"**/node_modules",
"**/coverage",
"**/storybook-static",
+8
View File
@@ -144,7 +144,13 @@ skip = [
"**/web/out",
"./web/storybook-static",
"./web/custom-elements.json",
# TODO: Remove this after moving website to docs
"./website/build",
"./website/api/build",
"./website/integrations/build",
"./docs/build",
"./docs/api/build",
"./docs/integrations/build",
"./gen-ts-api",
"./gen-py-api",
"./gen-go-api",
@@ -200,7 +206,9 @@ omit = [
"*/migrations/*",
"*/management/commands/*",
"*/apps.py",
# TODO: Remove this after moving website to docs
"website/",
"docs/",
]
[tool.coverage.report]
+5 -2
View File
@@ -40,6 +40,8 @@ const pluginName = "mdx-plugin";
* @returns {Plugin}
*/
export function mdxPlugin({ root }) {
const prefix = "~docs";
// TODO: Replace with `resolvePackage` after NPM Workspaces support is added.
const docsPackageRoot = path.resolve(MonoRepoRoot, "website");
@@ -55,7 +57,8 @@ export function mdxPlugin({ root }) {
if (!args.path.startsWith("~")) return args;
return {
path: path.resolve(docsPackageRoot, args.path.slice(1)),
path: path.join(docsPackageRoot, "docs", args.path.slice(prefix.length)),
pluginName,
};
}
@@ -75,7 +78,7 @@ export function mdxPlugin({ root }) {
const publicPath = path.resolve(
"/",
path.relative(path.join(root, "website"), data.path),
path.relative(path.join(root, "website", "docs"), data.path),
);
const publicDirectory = path.dirname(publicPath);
@@ -4,7 +4,7 @@ import { useMDXModule } from "#elements/ak-mdx/MDXModuleContext";
import React from "react";
const DOCS_DOMAIN = "https://goauthentik.io";
const DOCS_DOMAIN = "https://docs.goauthentik.io";
/**
* A custom anchor element that applies special behavior for MDX content.
+3 -3
View File
@@ -2,10 +2,10 @@
This directory contains the source files for the [authentik technical documentation](https://docs.goauthentik.io/docs?utm_source=github) and the [authentik integration guides](https://integrations.goauthentik.io?utm_source=github).
Contributions are welcome! Please refer to our [contributor guidelines](https://docs.goauthentik.io/docs/developer-docs?utm_source=github) for details about contributing code or docs.
Contributions are welcome! Please refer to our [contributor guidelines](https://docs.goauthentik.io/developer-docs?utm_source=github) for details about contributing code or docs.
For instructions to set up your local environment for building docs locally, refer to our [Docs development environment](https://docs.goauthentik.io/docs/developer-docs/setup/website-dev-environment?utm_source=github) page.
For instructions to set up your local environment for building docs locally, refer to our [Docs development environment](https://docs.goauthentik.io/developer-docs/setup/website-dev-environment?utm_source=github) page.
For instructions for writing the docs and then testing in your local build, plus tips on writing, links to our Style Guide and templates, see the [Writing documentation guide](https://docs.goauthentik.io/docs/developer-docs/docs/writing-documentation?utm_source=github).
For instructions for writing the docs and then testing in your local build, plus tips on writing, links to our Style Guide and templates, see the [Writing documentation guide](https://docs.goauthentik.io/developer-docs/docs/writing-documentation?utm_source=github).
To ensure a smooth review process, we encourage you to build the documentation locally to preview and test your documentation contributions. Be sure to test locally before opening a pull request. Let us know if you have any questions or want help with any part of the process.
+1 -2
View File
@@ -11,12 +11,11 @@
base = "website"
package = "api"
command = "npm run build -w api"
publish = "api/build"
publish = "website/api/build"
[dev]
command = "npm start"
targetPort = 3000
publish = "api/build"
[context.production.environment]
NODE_ENV = "production"
+16 -16
View File
@@ -20,28 +20,28 @@
"#reference/sidebar": "./reference/sidebar.ts"
},
"dependencies": {
"@docusaurus/core": "3.7.0",
"@docusaurus/faster": "3.7.0",
"@docusaurus/module-type-aliases": "3.7.0",
"@docusaurus/plugin-client-redirects": "3.7.0",
"@docusaurus/plugin-content-docs": "3.7.0",
"@docusaurus/preset-classic": "3.7.0",
"@docusaurus/theme-common": "3.7.0",
"@docusaurus/tsconfig": "3.7.0",
"@docusaurus/types": "3.7.0",
"@goauthentik/docusaurus-config": "1.1.0",
"@docusaurus/core": "^3.8.1",
"@docusaurus/faster": "^3.8.1",
"@docusaurus/module-type-aliases": "^3.8.1",
"@docusaurus/plugin-client-redirects": "^3.8.1",
"@docusaurus/plugin-content-docs": "^3.8.1",
"@docusaurus/preset-classic": "^3.8.1",
"@docusaurus/theme-common": "^3.8.1",
"@docusaurus/tsconfig": "^3.8.1",
"@docusaurus/types": "^3.8.1",
"@goauthentik/docusaurus-config": "^2.1.1",
"@goauthentik/docusaurus-theme": "*",
"@goauthentik/tsconfig": "^1.0.4",
"@mdx-js/react": "^3.1.0",
"@types/postman-collection": "^3.5.11",
"@types/react": "^18.3.22",
"@types/react-dom": "^18.3.0",
"docusaurus-plugin-openapi-docs": "^4.4.0",
"docusaurus-theme-openapi-docs": "^4.4.0",
"@types/react": "^19.1.8",
"@types/react-dom": "^19.1.6",
"docusaurus-plugin-openapi-docs": "^4.5.1",
"docusaurus-theme-openapi-docs": "^4.5.1",
"npm-run-all": "^4.1.5",
"prism-react-renderer": "^2.4.1",
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react": "^19.1.0",
"react-dom": "^19.1.0",
"typescript": "^5.8.3"
},
"optionalDependencies": {
+1 -1
View File
@@ -6,7 +6,7 @@ Installing authentik is exactly the same process for both Enterprise version and
## 1. Install Enterprise
To get started working with Enterprise authentik, [upgrade](../install-config/upgrade.mdx) to the [2023.8.x](../releases) version or later.
To get started working with Enterprise authentik, [upgrade](../install-config/upgrade.mdx) to the [2023.8.x](../../releases/) version or later.
If this is a fresh install, refer to our [technical documentation](../install-config/index.mdx) for instructions to install and configure authentik.
@@ -113,7 +113,7 @@ docker compose pull
docker compose up -d
```
The `docker-compose.yml` file statically references the latest version available at the time of downloading the compose file. Each time you upgrade to a newer version of authentik, you download a new `docker-compose.yml` file, which points to the latest available version. For more information, refer to the **Upgrading** section in the [Release Notes](../../releases).
The `docker-compose.yml` file statically references the latest version available at the time of downloading the compose file. Each time you upgrade to a newer version of authentik, you download a new `docker-compose.yml` file, which points to the latest available version. For more information, refer to the **Upgrading** section in the [Release Notes](../../../releases/).
To start the initial setup, navigate to `http://<your server's IP or hostname>:9000/if/flow/initial-setup/`.
+1 -1
View File
@@ -10,7 +10,7 @@ Upgrading to the latest version of authentik, whether a new major release or a p
authentik does not support downgrading. Make sure to back up your database in case you need to revert an upgrade.
:::
**Preview the release notes**: Be sure to carefully read the [Release Notes](../releases/) for the specific version to which you plan to upgrade. The release might have special requirements or actions or contain breaking changes.
**Preview the release notes**: Be sure to carefully read the [Release Notes](../../releases/) for the specific version to which you plan to upgrade. The release might have special requirements or actions or contain breaking changes.
**Database backup**: Before upgrading, make a backup of your PostgreSQL database. You can create a backup by dumping your existing database. For detailed instructions, refer to the relevant guide for your deployment method ([Docker Compose](../troubleshooting/postgres/upgrade_docker.md) or [Kubernetes](../troubleshooting/postgres/upgrade_kubernetes.md)).
+12 -12
View File
@@ -4,7 +4,7 @@
"license": "MIT",
"private": true,
"scripts": {
"build": "run-s check-types build:docusaurus",
"build": "run-s build:docusaurus",
"build:docusaurus": "docusaurus build --out-dir ../build",
"check-types": "tsc -b .",
"clear": "docusaurus clear",
@@ -13,21 +13,21 @@
"start": "docusaurus start"
},
"dependencies": {
"@docusaurus/core": "3.7.0",
"@docusaurus/module-type-aliases": "3.7.0",
"@docusaurus/preset-classic": "3.7.0",
"@docusaurus/theme-mermaid": "3.7.0",
"@docusaurus/tsconfig": "3.7.0",
"@docusaurus/types": "3.7.0",
"@goauthentik/docusaurus-config": "1.1.0",
"@docusaurus/core": "^3.8.1",
"@docusaurus/module-type-aliases": "^3.8.1",
"@docusaurus/preset-classic": "^3.8.1",
"@docusaurus/theme-mermaid": "^3.8.1",
"@docusaurus/tsconfig": "^3.8.1",
"@docusaurus/types": "^3.8.1",
"@goauthentik/docusaurus-config": "^2.1.1",
"@goauthentik/docusaurus-theme": "*",
"@mdx-js/react": "^3.1.0",
"@types/react": "^18.3.22",
"@types/react-dom": "^18.3.0",
"@types/react": "^19.1.8",
"@types/react-dom": "^19.1.6",
"prism-react-renderer": "^2.3.0",
"react": "^18.3.1",
"react": "^19.1.0",
"react-before-after-slider-component": "^1.1.8",
"react-dom": "^18.3.1",
"react-dom": "^19.1.0",
"unist-util-visit": "^5.0.0"
},
"engines": {
+1 -1
View File
@@ -4,7 +4,7 @@
### ADDENDUM May 30, 2025
As of version 2025.4, the option to store sessions in cache has been removed; sessions are now exclusively stored in the database. See our [2025.4 release notes](../../releases/2025.4#sessions-are-now-stored-in-the-database) for more information.
As of version 2025.4, the option to store sessions in cache has been removed; sessions are now exclusively stored in the database. See our [2025.4 release notes](../../releases/2025/v2025.4.md#sessions-are-now-stored-in-the-database) for more information.
### Summary
+1 -1
View File
@@ -637,7 +637,7 @@ const items = [
items: [
{
type: "link",
href: "pathname:///api",
href: "https://api.goauthentik.io",
label: "API Overview",
className: "api-overview",
},
+2 -2
View File
@@ -22,8 +22,8 @@
"#theme/*": "./theme/*"
},
"dependencies": {
"@docusaurus/preset-classic": "3.7.0",
"@goauthentik/docusaurus-config": "1.1.0",
"@docusaurus/preset-classic": "^3.8.1",
"@goauthentik/docusaurus-config": "^2.1.1",
"@types/semver": "^7.7.0",
"clsx": "^2.1.1",
"fast-glob": "^3.3.3",
+1 -2
View File
@@ -11,12 +11,11 @@
base = "website"
package = "integrations"
command = "npm run build -w integrations"
publish = "integrations/build"
publish = "website/integrations/build"
[dev]
command = "npm start"
targetPort = 3000
publish = "integrations/build"
[context.production.environment]
NODE_ENV = "production"
+12 -12
View File
@@ -12,21 +12,21 @@
"start": "docusaurus start"
},
"dependencies": {
"@docusaurus/core": "3.7.0",
"@docusaurus/module-type-aliases": "3.7.0",
"@docusaurus/plugin-client-redirects": "3.7.0",
"@docusaurus/preset-classic": "3.7.0",
"@docusaurus/theme-mermaid": "3.7.0",
"@docusaurus/tsconfig": "3.7.0",
"@docusaurus/types": "3.7.0",
"@goauthentik/docusaurus-config": "1.1.0",
"@docusaurus/core": "^3.8.1",
"@docusaurus/module-type-aliases": "^3.8.1",
"@docusaurus/plugin-client-redirects": "^3.8.1",
"@docusaurus/preset-classic": "^3.8.1",
"@docusaurus/theme-mermaid": "^3.8.1",
"@docusaurus/tsconfig": "^3.8.1",
"@docusaurus/types": "^3.8.1",
"@goauthentik/docusaurus-config": "^2.1.1",
"@goauthentik/docusaurus-theme": "*",
"@mdx-js/react": "^3.0.0",
"@types/react": "^18.3.22",
"@types/react-dom": "^18.3.0",
"@types/react": "^19.1.8",
"@types/react-dom": "^19.1.6",
"prism-react-renderer": "^2.3.0",
"react": "^18.3.1",
"react-dom": "^18.3.1"
"react": "^19.1.0",
"react-dom": "^19.1.0"
},
"engines": {
"node": ">=24"
+549 -1999
View File
File diff suppressed because it is too large Load Diff
+1 -3
View File
@@ -4,10 +4,8 @@
"license": "MIT",
"private": true,
"scripts": {
"build": "run-s build:api build:docusaurus build:api:copy",
"build": "npm run build -w docs",
"build:api": "npm run build -w api",
"build:api:copy": "cp -r ./api/build ./build/api",
"build:docusaurus": "npm run build -w docs",
"build:integrations": "npm run build -w integrations",
"check-types": "tsc -b",
"docusaurus": "docusaurus",