mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
d8ea041c56
## 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]>
84 lines
2.9 KiB
Markdown
84 lines
2.9 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 frontmatter (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 configuration 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`
|