mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-19 22:14:25 +00:00
Wim Van LaerandGitHub
699ed17918
# Which Problems Are Solved naming inconsistencies: Configuration <-> Settings # How the Problems Are Solved # Additional Changes # Additional Context - Closes #11282
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# @zitadel/docs
|
|
|
|
Documentation for Zitadel, built with [Fumadocs](https://fumadocs.dev) and [Next.js](https://nextjs.org).
|
|
|
|
## Getting Started
|
|
|
|
Ensure you have followed the [root quick start](../../CONTRIBUTING.md#quick-start) to set up dependencies.
|
|
|
|
### Local Development
|
|
|
|
Start the development server:
|
|
|
|
```bash
|
|
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 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
|
|
|
|
## 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.
|
|
|
|
### 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.
|
|
|
|
Refer to the [Google Developer Style Guide](https://developers.google.com/style) 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:
|
|
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
|
|
|
|
Use `docs(<scope>): <short summary>` for PR titles.
|
|
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`
|