mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
8ad1d28086
<!-- Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Do not remove any of the sections. --> # Which Problems Are Solved The `/apis/introduction` page did not give developers clear guidance on which API version to use. v1 and v2 were presented as equal choices, the v2 resource list was incomplete, the API path prefix block was misleading, and several links used inconsistent relative paths. - No clear recommendation to use v2 for new integrations - v1 APIs not labelled as legacy - "APIs v2" section only listed 3 of 15 available v2 services - Path prefix block only listed 5 of 15 v2 gRPC service paths, with no distinction between REST and gRPC/Connect access patterns - `/ui/` path listed as a single entry — the Management Console (`/ui/console/`) and hosted Login UI (`/ui/login/`) were not distinguished - Relative links (`../guides/...`, `./assets/assets`) inconsistent with the rest of the page - Auth disclaimer paragraph was confusing; "Custom" section heading was unclear # How the Problems Are Solved - **v2-first framing**: Added a clear directive — "Use the v2 APIs for all new integrations" — and renamed the old section to "Legacy v1 APIs" - **Complete v2 resource list**: All 15 v2 services now listed with one-line descriptions (User, Session, Org, Instance, Project, Application, IDP, Group, Settings, Feature, Authorization, Action, WebKey, OIDC, SAML) - **Full path prefix list**: All 15 v2 gRPC service paths listed; split into `# REST (HTTP/JSON transcoding): /v2/` and `# gRPC + Connect protocol (binary or JSON via connectRPC):` - **`/ui/` paths clarified**: Split into `/ui/console/` (Management Console) and `/ui/login/` (Hosted Login UI) with inline comments - **Fixed relative links**: `../guides/...` → `/guides/...`; `./assets/assets` → `/apis/assets/assets` - **Section copy improvements**: Auth disclaimer removed; "Custom" renamed to "Session-based and custom login" with clear bullet list; v1 API card descriptions updated with v2 pointers; Assets card, System card title fix - **Client libraries section**: Replaced noisy "API definitions" section with cleaner "Client libraries & schemas" # Additional Context All changes are in `apps/docs/content/apis/introduction.mdx`, `apps/docs/content/apis/v2.mdx`, and `apps/docs/content/apis/migration_v1_to_v2.mdx`. Co-authored-by: Copilot <[email protected]>
@zitadel/docs
Documentation for Zitadel, built with Fumadocs and Next.js.
Getting Started
Ensure you have followed the root quick start to set up dependencies.
Local Development
Start the development server:
pnpm nx run @zitadel/docs:dev
The site will be available at http://localhost:3000.
Scripts
Key scripts for documentation workflows:
| Script | Description |
|---|---|
dev |
Starts the development server. |
build |
Builds the production application. |
fetch:remote-content |
Fetches remote tags and referenced content. |
generate |
Runs all generation steps (fetch:remote-content, generate:proto-docs, generate:api-reference, generate:index-pages). |
check:links |
Validates content integrity (broken links, missing frontmatter, schema errors). |
check-types |
Validates typescript types. |
test |
Runs all validation steps (check-types, check:links). |
lint |
checks for code style and syntax errors (ESLint). |
clean |
Cleans the build output and generated files. |
Validation
- Code Quality: Run
pnpm lintto check for syntax and style issues in JS/TS/MDX files. - Content Integrity: Run
pnpm check:linksto validate content structure, including:- Broken internal links
- Missing required front-matter (e.g.,
title) - Image references
Contributing
Build Process
The docs build process automatically handling the following steps via generate:
- Downloads required protoc plugins.
- Generates gRPC documentation from proto files.
- Generates API documentation from OpenAPI specs.
- Generates index files for directory structures.
Style Guide
- Variables: Use environment variables in code snippets where possible.
- Embedded Content: Use
_filename.mdxfor content embedded in other pages (not indexed individually). - Code Embedding: Use the
fileproperty 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 for general guidelines.
Adding Content
All documentation content is located in the content directory. Note that the system strictly accepts only .mdx files.
To add a new page:
- Create a
.mdxfile in the appropriate subdirectory ofcontent. - Register the new page in the sidebar settings at
lib/sidebar-data.tsto make it accessible in the navigation.
Pull Requests
Use docs(<scope>): <short summary> for PR titles.
Pass quality checks before submitting:
pnpm nx run @zitadel/docs:build
pnpm nx run @zitadel/docs:check:links
You can also run specific steps individually:
pnpm fetch:remote-contentpnpm generate:api-reference