docs: introduce versioned docs and migrate to fuma (#11166)

## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
2026-11-04 05:12:16 +00:00 · 2026-01-29 08:38:36 -08:00
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,45 @@
+import ThemedImage from "@/components/docusaurus/themed-image";
+import AuthType from "./_auth-type.mdx";
+import RedirectURIs from "./_redirect-uris.mdx";
+import GenerateKey from "./_generate-key.mdx";
+import ReviewConfig from "./_review-config.mdx";
+
+export default function CreateApp(props) {
+  return (
+    <div>
+      <h3>
+        Create the {props.appName ? props.appName + " app" : "application"}
+      </h3>
+      <p>
+        Go to the detail page of your project and click the "+"-button in the
+        application-section. This will lead you to the the creation wizard.
+      </p>
+      <img
+        alt="Add application"
+        src="/docs/img/guides/console/addapplication.png"
+        width="120px"
+      />
+      <p>
+        Create the app by setting a name and select the application type "Web"
+      </p>
+      <img
+        alt={"create " + props.appType + " preview"}
+        src={"/img/guides/application/create-" + props.appType + "-app.png"}
+      />
+      <h3>Select the authentication method</h3>
+      <p>
+        The authentication method defines the communication flow during a login
+      </p>
+      <AuthType components={props.components}  appType={props.appType} authType={props.authType} />
+      <h3>Redirect URIs</h3>
+      <RedirectURIs components={props.components}
+        appType={props.appType}
+        redirectURI={props.redirectURI}
+        postLogoutURI={props.postLogoutURI}
+      />
+      <h3>Review your configuration</h3>
+      <ReviewConfig components={props.components}  appType={props.appType} authType={props.authType} />
+      <GenerateKey components={props.components}  appType={props.appType} authType={props.authType} />
+    </div>
+  );
+}
@@ -0,0 +1,183 @@
+import ThemedImage from "@/components/docusaurus/themed-image";
+
+export default function AuthType(props) {
+  return <div>{defaultAuthTypes(props.appType, props.authType)}</div>;
+}
+
+export function defaultAuthTypes(appType, authType) {
+  let rows;
+  switch (appType) {
+    case "web":
+      rows = web(authType);
+      break;
+    case "user-agent":
+      rows = userAgent(authType);
+      break;
+    case "api":
+      rows = api(authType);
+      break;
+    case "native":
+      rows = native();
+      break;
+    default:
+      return null;
+  }
+  return (
+    <table>
+      <tbody>{rows.map((fn) => fn())}</tbody>
+    </table>
+  );
+}
+
+export const web = (typ) => {
+  switch (typ) {
+    case "pkce":
+      return [pkce];
+    case "code":
+      return [code];
+    case "jwt":
+      return [jwt];
+    case "post":
+      return [post];
+  }
+  return [pkce, code, jwt, post];
+};
+
+export const userAgent = (typ) => {
+  switch (typ) {
+    case "pkce":
+      return [pkce];
+    case "implicit":
+      return [implicit];
+  }
+  return [pkce, implicit];
+};
+
+export const api = (typ) => {
+  switch (typ) {
+    case "jwt":
+      return [jwt];
+    case "basic":
+      return [basic];
+  }
+  return [jwt, basic];
+};
+
+export const native = () => {
+  return [
+    () => (
+      <tr key="native">
+        <td>
+          Native only supports code authentication type, that's why you don't
+          have to select any
+        </td>
+      </tr>
+    ),
+  ];
+};
+
+export const pkce = () => (
+  <tr key="pkce">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/pkce-logo-dark.png"
+        alt="pkce preview"
+      />
+    </td>
+    <td>
+      <h4>PKCE</h4>
+      <p>Recommended because it's the most secure.</p>
+    </td>
+  </tr>
+);
+
+export const code = () => (
+  <tr key="code">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/code-logo-dark.png"
+        alt="code preview"
+      />
+    </td>
+    <td>
+      <h4>Code</h4>
+      <p>Use if your application needs client id and client secret</p>
+    </td>
+  </tr>
+);
+
+export const jwt = () => (
+  <tr key="jwt">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/jwt-logo-dark.png"
+        alt="jwt preview"
+      />
+    </td>
+    <td>
+      <h4>(Private Key) JWT</h4>
+      <p>
+        Key file to authorize your application. You can create keys after
+        created the application see{" "}
+        <a href="#create-key-for-private-key-jwt">below</a>
+      </p>
+    </td>
+  </tr>
+);
+
+export const post = () => (
+  <tr key="post">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/post-logo-dark.png"
+        alt="post preview"
+      />
+    </td>
+    <td>
+      <h4>Post</h4>
+      <p>
+        Only use if you have no other possibilities. Client id and client secret
+        in request body
+      </p>
+    </td>
+  </tr>
+);
+
+export const implicit = () => (
+  <tr key="implicit">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/implicit-logo-dark.png"
+        alt="Implicit preview"
+      />
+    </td>
+    <td>
+      <h4>Implicit</h4>
+      <p>
+        Only use if you have no other possibilities. The flow is objective to be
+        removed.
+      </p>
+    </td>
+  </tr>
+);
+
+export const basic = () => (
+  <tr key="basic">
+    <td>
+      <img
+        width="300px"
+        src="/docs/img/guides/application/basic-logo-dark.png"
+        alt="Basic preview"
+      />
+    </td>
+    <td>
+      <h4>Basic</h4>
+      <p>The application sends username and password</p>
+    </td>
+  </tr>
+);
@@ -0,0 +1,19 @@
+import ThemedImage from "@/components/docusaurus/themed-image";
+
+export default function GenerateKey(props) {
+  return props.appType == "api" || props.authType == "jwt" ? (
+    <div>
+     <h3>Create key for private key JWT</h3>
+      <p>
+        After you successfully created your application with authentication type
+        JWT your can create keys in the Configuration section and Keys Card of
+        the app details like following image shows:
+      </p>
+      <img
+        width="400px"
+        alt="Generate key"
+        src="/docs/img/guides/application/generate-key.png"
+      />
+    </div>
+  ) : null;
+}
@@ -0,0 +1,51 @@
+import ThemedImage from "@/components/docusaurus/themed-image";
+import Admonition from "@/components/docusaurus/admonition";
+
+export default function RedirectURIs(props) {
+  return ["web", "native", "user-agent"].includes(props.appType) ? (
+    <div>
+      <p>
+        During the login flow the application defines where a user is redirected
+        to after login or logout.
+        <br />
+        ZITADEL verifies if the URL the user gets redirected to is valid by
+        checking if one of the redirect URIs match.
+      </p>
+      <ul>
+        <li>
+          <b>Redirect URIs</b> are verified during the login process.
+        </li>
+        {props.redirectURI ? (
+          <ul>
+            <li>
+              The default redirect uri of your app is{" "}
+              <code>{props.redirectURI}</code>
+            </li>
+          </ul>
+        ) : null}
+        <li>
+          <b>Post Logout URIs</b> are verified during the logout process.
+        </li>
+        {props.postLogoutURI ? (
+          <ul>
+            <li>
+              The default post logout uri of your app is{" "}
+              <code>{props.postLogoutURI}</code>
+            </li>
+          </ul>
+        ) : null}
+      </ul>
+      <Admonition type="note">
+        <p>
+          The default redirect uri of your app is{" "}
+          <code>{props.redirectURI}</code>
+        </p>
+      </Admonition>
+      <img
+        width="600px"
+        alt="Redirect URIs configuration"
+        src={"/img/guides/application/redirect-uris.png"}
+      />
+    </div>
+  ) : null;
+}
@@ -0,0 +1,41 @@
+import ThemedImage from "@/components/docusaurus/themed-image";
+
+export default function ReviewConfig(props) {
+  let clientObjects = [];
+  if (clientID(props.appType, props.authType)) {
+    clientObjects.push("id");
+  }
+  if (clientSecret(props.appType, props.authType)) {
+    clientObjects.push("secret");
+  }
+  return clientObjects.length > 0 ? (
+    <div>
+      <p>
+        The last page of the stepper shows a summary of what will be created.
+        After you have reviewed the configuration you can create the
+        application.
+      </p>
+      <h3>Client information</h3>
+      <p>
+        Please make sure to safe the <b>client {clientObjects.join(" and ")}</b>{" "}
+        for later use in the application.
+      </p>
+      <img
+        alt="client infos"
+        src={`/docs/img/guides/application/client-${clientObjects.join("-")}.png`}
+        width="700px"
+      />
+    </div>
+  ) : null;
+}
+
+export function clientID(appType, authType) {
+  return (
+    ["pkce", "code", "jwt", "post", "implicit", "basic"].includes(authType) ||
+    appType === "native"
+  );
+}
+
+export function clientSecret(appType, authType) {
+  return ["code", "post", "basic"].includes(authType);
+}