diff --git a/apps/docs/README.md b/apps/docs/README.md index 6a5750f08..deeb7592b 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -8,6 +8,12 @@ Ensure you have followed the [root quick start](../../CONTRIBUTING.md#quick-star ### Local Development +Ensure all dependencies are installed: + +```bash +pnpm install +``` + Start the development server: ```bash @@ -34,28 +40,61 @@ Key scripts for documentation workflows: ### Validation -* **Code Quality**: Run `pnpm lint` to check for syntax and style issues in JS/TS/MDX files. -* **Content Integrity**: Run `pnpm check:links` to validate content structure, including: - * Broken internal links - * Missing required front-matter (e.g., `title`) - * Image references +* **Code Quality**: Run `pnpm nx run @zitadel/docs:lint` to check for syntax and style issues in JS/TS/MDX files. +* **Content Integrity**: Run `pnpm nx run @zitadel/docs:check-links` to validate content structure, including: + * Broken internal links + * Missing required front-matter (e.g., `title`) + * Image references + +### Troubleshooting + +#### Issue: Nx configuration not found or "nx" command not found + +If you see errors like: + +```bash + NX Cannot find configuration for task @zitadel/zitadel:@zitadel/docs:generate + +Pass --verbose to see the stacktrace. +``` + +or + +``` +pnpm nx run @zitadel/docs:dev + ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL  Command "nx" not found + +Did you mean "pnpm nx"? +``` + +**Root cause**: Your dependency cache or `node_modules` is out of sync. + +**Solution**: Run these commands from the repository root in order: + +1. **Clear node_modules**: `rm -rf node_modules` — removes the installed dependency folder +2. **Clear pnpm cache**: `pnpm cache delete` — clears pnpm's internal package cache +3. **Reinstall dependencies**: `pnpm install` — reinstalls all dependencies fresh +4. **Test the setup**: `pnpm nx run @zitadel/docs:generate` — verifies everything works + +This resolves 99% of setup-related issues. ## Contributing ### Build Process -The docs build process automatically handling the following steps via `generate`: -1. Downloads required protoc plugins. -2. Generates gRPC documentation from proto files. -3. Generates API documentation from OpenAPI specs. -4. Generates index files for directory structures. +The docs build process automatically handles the following steps via `generate`: + +1. Downloads required protoc plugins. +2. Generates gRPC documentation from proto files. +3. Generates API documentation from OpenAPI specs. +4. Generates index files for directory structures. ### Style Guide -- **Variables**: Use environment variables in code snippets where possible. -- **Embedded Content**: Use `_filename.mdx` for content embedded in other pages (not indexed individually). -- **Code Embedding**: Use the `file` property in code blocks to embed code from the repo. -- **Voice**: Use active voice and sentence case for titles. +* **Variables**: Use environment variables in code snippets where possible. +* **Embedded Content**: Use `_filename.mdx` for content embedded in other pages (not indexed individually). +* **Code Embedding**: Use the `file` property in code blocks to embed code from the repo. +* **Voice**: Use active voice and sentence case for titles. Refer to the [Google Developer Style Guide](https://developers.google.com/style) for general guidelines. @@ -64,9 +103,9 @@ Refer to the [Google Developer Style Guide](https://developers.google.com/style) All documentation content is located in the `content` directory. Note that the system strictly accepts **only `.mdx` files**. To add a new page: -1. Create a `.mdx` file in the appropriate subdirectory of [`content`](./content). -2. Register the new page in the sidebar settings at [`lib/sidebar-data.ts`](./lib/sidebar-data.ts) to make it accessible in the navigation. +1. Create a `.mdx` file in the appropriate subdirectory of [`content`](./content). +2. Register the new page in the sidebar settings at [`lib/sidebar-data.ts`](./lib/sidebar-data.ts) to make it accessible in the navigation. ### Pull Requests @@ -75,9 +114,4 @@ Pass quality checks before submitting: ```bash pnpm nx run @zitadel/docs:build -pnpm nx run @zitadel/docs:check:links ``` - -You can also run specific steps individually: -* `pnpm fetch:remote-content` -* `pnpm generate:api-reference` diff --git a/apps/docs/content/apis/openidoauth/endpoints.mdx b/apps/docs/content/apis/openidoauth/endpoints.mdx index 31f46e1b2..eb63092d0 100644 --- a/apps/docs/content/apis/openidoauth/endpoints.mdx +++ b/apps/docs/content/apis/openidoauth/endpoints.mdx @@ -63,13 +63,8 @@ Depending on your authorization method you will have to provide additional param no additional parameters required @@ -77,7 +72,7 @@ no additional parameters required no additional parameters required - + | Parameter | Description | | --------------------- | ----------------------------------------------------- | @@ -192,13 +187,8 @@ Depending on your authorization method you will have to provide additional param @@ -215,7 +205,7 @@ Send your `client_id` and `client_secret` as parameters in the body: | client_secret | client_secret of the application | - + Send your `client_id` and `code_verifier` for us to recompute the `code_challenge` of the authorization request. @@ -292,13 +282,8 @@ Depending on your authorization method you will have to provide additional param @@ -315,7 +300,7 @@ Send your `client_id` and `client_secret` as parameters in the body: | client_secret | client_secret of the application | - + Send your `client_id` as parameter in the body. No authentication is required. @@ -402,13 +387,8 @@ Depending on your authorization method you will have to provide additional param @@ -426,7 +406,7 @@ Send your `client_id` and `client_secret` as parameters in the body: | client_secret | client_secret of the application | - + Send your `client_id` as parameter in the body. No authentication is required. @@ -477,12 +457,9 @@ this endpoint will check if the token is not revoked (by client or logout). Depending on your authorization method you will have to provide additional parameters or headers: @@ -585,14 +562,9 @@ the corresponding `access_token` will be revoked as well. Depending on your authorization method you will have to provide additional parameters or headers: @@ -609,7 +581,7 @@ Send your `client_id` and `client_secret` as parameters in the body: | client_secret | client_secret of the application | - + Send your `client_id` as parameters in the body: diff --git a/apps/docs/content/guides/integrate/actions/testing-request-signature.mdx b/apps/docs/content/guides/integrate/actions/testing-request-signature.mdx index b93dd48d4..adc5a2a0d 100644 --- a/apps/docs/content/guides/integrate/actions/testing-request-signature.mdx +++ b/apps/docs/content/guides/integrate/actions/testing-request-signature.mdx @@ -132,7 +132,7 @@ You will need to implement a listener that can receive HTTP requests. For this example, we will use a simple Go HTTP server that will print the received request to standard output. As mentioned before, this validation can and should be applied to any target implementation. - + diff --git a/apps/docs/content/guides/integrate/login/hosted-login.mdx b/apps/docs/content/guides/integrate/login/hosted-login.mdx index cd41b659b..bb0a96de2 100644 --- a/apps/docs/content/guides/integrate/login/hosted-login.mdx +++ b/apps/docs/content/guides/integrate/login/hosted-login.mdx @@ -168,8 +168,12 @@ You can also activate the v2 login for your apps, so users are redirected to `/u **Customizing the new login:** The easiest way to actually customizing it is to fork the https://github.com/zitadel/zitadel repo and use the [Deploy with Vercel button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) to run your login code on Vercel. - - + + Zitadel Cloud provides the V2 login at the fixed path `/ui/v2/login`. @@ -181,7 +185,7 @@ You can also activate the v2 login for your apps, so users are redirected to `/u 2. Enable the [loginV2 feature](/reference/api/feature/zitadel.feature.v2.FeatureService.SetInstanceFeatures) on the instance. Leave the base URI empty to use the default. If you enable this feature, the login will be used for every application configured in your Zitadel instance. (Example: https://your-zitadel-instance.zitadel.cloud/ui/v2/login) - + The simplest way to deploy the new login for yourself is by using the [Deploy with Vercel button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) to deploy the login directly to your Vercel. diff --git a/apps/docs/content/guides/integrate/login/oidc/_authmethods.mdx b/apps/docs/content/guides/integrate/login/oidc/_authmethods.mdx index 57372f832..344ec90a9 100644 --- a/apps/docs/content/guides/integrate/login/oidc/_authmethods.mdx +++ b/apps/docs/content/guides/integrate/login/oidc/_authmethods.mdx @@ -10,20 +10,16 @@ export default function AuthMethods(props) {
- + - + - + @@ -31,26 +27,23 @@ export default function AuthMethods(props) { ) : props.selected == "native" ? ( - + ) : props.selected == "spa" ? ( - + - + diff --git a/apps/docs/content/guides/integrate/login/oidc/login-users.mdx b/apps/docs/content/guides/integrate/login/oidc/login-users.mdx index 326f509ab..a4582097e 100644 --- a/apps/docs/content/guides/integrate/login/oidc/login-users.mdx +++ b/apps/docs/content/guides/integrate/login/oidc/login-users.mdx @@ -53,14 +53,10 @@ This will start a wizard asking you for an application name and a type. - + #### Authentication method @@ -73,7 +69,7 @@ Please change the authentication method here as well, if you did so in the wizar - + #### Authentication method @@ -82,7 +78,7 @@ When selecting Native the authentication method always needs to be PKCE. - + #### Authentication method diff --git a/apps/docs/content/guides/manage/console/_create-user.mdx b/apps/docs/content/guides/manage/console/_create-user.mdx index f6675cef6..6b7545255 100644 --- a/apps/docs/content/guides/manage/console/_create-user.mdx +++ b/apps/docs/content/guides/manage/console/_create-user.mdx @@ -5,8 +5,8 @@ If you started with Zitadel before version 3, you might have the "Human User [de In this case please enable the Feature Flag "Use V2 Api in Management Console for User creation" in the Default Settings. - - + + Invite Human When creating a new user you have different options. @@ -21,7 +21,7 @@ In this case please enable the Feature Flag "Use V2 Api in Management Console fo - **Set an initial password for the user**: The user will receive an email and be able to setup an authentication method (e.g Password, Passkey, External SSO) - + Add Human After a user is created, by default, an initialization mail with a code is sent to the registered email. This code then has to be verified on first login. @@ -29,7 +29,7 @@ In this case please enable the Feature Flag "Use V2 Api in Management Console fo If no password is set initially, the initialization mail prompting the user to set his password is sent. - + - + + First [add a new SMS Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddSMSProviderHTTP) to create a new HTTP provider that can be used to send SMS messages: @@ -74,7 +74,7 @@ A provider with HTTP type will send the messages and the data to a pre-defined w See full API reference for [SMS Providers](/reference/api/admin) for more details. - + First [add a new Email Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddEmailProviderHTTP) to create a new HTTP provider that can be used to send Email messages: diff --git a/apps/docs/content/legal/service-description/support-services.mdx b/apps/docs/content/legal/service-description/support-services.mdx index 2020cc344..b2442f8f2 100644 --- a/apps/docs/content/legal/service-description/support-services.mdx +++ b/apps/docs/content/legal/service-description/support-services.mdx @@ -169,11 +169,11 @@ Topics of the onboarding term may include - Migration - Security Best Practices & Go-Live Checkup - - + +
  • Instance Settings
    • -
  • Walk-though all features
    • +
  • Walk-through all features
  • Users / Manuals
  • Authentication & Management APIs
  • Validation of tokens
    • @@ -189,7 +189,7 @@ Topics of the onboarding term may include
  • Functional testing of the ZITADEL instance
 - +
  • Performance testing
  • Setting up or maintaining backup storage