mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
SilvanandGitHub
4bc899d052
## Problem statement - `<Tabs>` were not rendered in docs - Missing steps in README for local dev ## How it was solved - Enhance the README to better describe local development setup and clean up formatting. - Standardize the use of tabs across various components for consistency. ## Additional info To not cause merge conflicts with https://github.com/zitadel/zitadel/pull/11729 changes in `/self-hosting/manage/configure/configure.mdx` were skipped
118 lines
4.7 KiB
Markdown
118 lines
4.7 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
|
||
|
||
Ensure all dependencies are installed:
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
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 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 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.
|
||
|
||
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
|
||
```
|