mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-03 21:02:15 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## 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]>
This commit is contained in:
Florian Forster
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
+5
-58
@@ -129,7 +129,7 @@ The code consists of the following parts:
|
||||
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) | [Contribute to API](#contribute-to-api) |
|
||||
| Management Console | Frontend the user interacts with after log in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) | [Contribute to Frontend](#contribute-to-frontend) |
|
||||
| Login | Modern authentication UI built with Next.js | [Next.js](https://nextjs.org), [React](https://reactjs.org), [TypeScript](https://www.typescriptlang.org) | [./apps/login](./apps/login) | [Contribute to Frontend](#contribute-to-frontend) |
|
||||
| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./docs](./docs) | [Contribute to Frontend](#contribute-to-frontend) |
|
||||
| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) |
|
||||
| translations | Internationalization files for default languages | YAML | [./console](./console) and [./internal](./internal) | [Contribute Translations](#contribute-translations) |
|
||||
|
||||
Please follow the guides to validate and test the code before you contribute.
|
||||
@@ -582,62 +582,9 @@ pnpm nx run @zitadel/client:build # Build after changes
|
||||
|
||||
### Contribute to Docs
|
||||
|
||||
Project documentation is made with Docusaurus and is located under [./docs](./docs). The documentation uses **pnpm** and **Nx** for development and build processes.
|
||||
Project documentation is located under [./apps/docs](./apps/docs).
|
||||
Please refer to the [Docs README](./apps/docs/README.md) for detailed instructions on how to contribute to the documentation.
|
||||
|
||||
To start developing, make sure you followed the [quick start](#quick-start) steps.
|
||||
|
||||
#### Local Development
|
||||
|
||||
```bash
|
||||
# Start development server (recommended)
|
||||
pnpm nx run @zitadel/docs:dev
|
||||
|
||||
# Or start production server
|
||||
pnpm nx run @zitadel/docs:prod
|
||||
```
|
||||
|
||||
The Docs build process automatically:
|
||||
|
||||
1. Downloads required protoc plugins
|
||||
2. Generates gRPC documentation from proto files
|
||||
3. Generates API documentation from OpenAPI specs
|
||||
4. Copies configuration files
|
||||
5. Builds the Docusaurus site
|
||||
|
||||
#### Local testing
|
||||
|
||||
The documentation server will be available at http://localhost:3000 with live reload for fast development feedback.
|
||||
|
||||
#### Style guide
|
||||
|
||||
- **Code with variables**: Make sure that code snippets can be used by setting environment variables, instead of manually replacing a placeholder.
|
||||
- **Embedded files**: When embedding mdx files, make sure the template ist prefixed by "\_" (lowdash). The content will be rendered inside the parent page, but is not accessible individually (eg, by search).
|
||||
- **Don't repeat yourself**: When using the same content in multiple places, save and manage the content as separate file and make use of embedded files to import it into other docs pages.
|
||||
- **Embedded code**: You can embed code snippets from a repository. See the [plugin](https://github.com/saucelabs/docusaurus-theme-github-codeblock#usage) for usage.
|
||||
|
||||
Following the [Google style guide](https://developers.google.com/style) is highly recommended. Its clear and concise guidelines ensure consistency and effective communication within the wider developer community.
|
||||
|
||||
The style guide covers a lot of material, so their [highlights](https://developers.google.com/style/highlights) page provides an overview of its most important points. Some of the points stated in the highlights that we care about most are given below:
|
||||
|
||||
- Be conversational and friendly without being frivolous.
|
||||
- Use sentence case for document titles and section headings.
|
||||
- Use active voice: make clear who's performing the action.
|
||||
- Use descriptive link text.
|
||||
|
||||
#### Docs pull request
|
||||
|
||||
When making a pull request use `docs(<scope>): <short summary>` as title for the semantic release.
|
||||
Scope can be left empty (omit the brackets) or refer to the top navigation sections.
|
||||
|
||||
#### Pass Quality Checks
|
||||
|
||||
Verify the Docs build correctly.
|
||||
|
||||
```bash
|
||||
pnpm nx run @zitadel/docs:build
|
||||
```
|
||||
|
||||
Fix the quality checks, add new checks that cover your changes and mark your pull request as ready for review when the pipeline checks pass.
|
||||
|
||||
## Contribute Translations
|
||||
|
||||
@@ -657,7 +604,7 @@ You also have to add some changes to the following files:
|
||||
- [Register Local File](./console/src/app/app.module.ts) - Import and register the Angular locale, register `i18n-iso-countries` locale
|
||||
- [Exclude from Angular prebundle](./console/angular.json) - Add `i18n-iso-countries/langs/<locale>.json` to `prebundle.exclude`
|
||||
- [Add Supported Language](./console/src/app/utils/language.ts)
|
||||
- [Customized Text Docs](./docs/docs/guides/manage/customize/texts.md)
|
||||
- [Customized Text Docs](./apps/docs/docs/guides/manage/customize/texts.md)
|
||||
- [Add language option](./internal/api/ui/login/static/templates/external_not_found_option.html)
|
||||
|
||||
### Login v2 (Next.js)
|
||||
@@ -737,7 +684,7 @@ The category shows which part of Zitadel is affected.
|
||||
- **category: backend**: The backend includes the APIs, event store, command and query side. This is developed in golang.
|
||||
- **category: ci**: ci is all about continuous integration and pipelines.
|
||||
- **category: design**: All about the ux/ui of Zitadel
|
||||
- **category: docs**: Adjustments or new documentations, this can be found in the docs folder.
|
||||
- **category: docs**: Adjustments or new documentations, this can be found in the apps/docs folder.
|
||||
- **category: frontend**: The frontend concerns on the one hand the Zitadel Management Console (Angular) and on the other hand the Login (gohtml)
|
||||
- **category: infra**: Infrastructure does include many different parts. E.g Terraform-provider, docker, metrics, etc.
|
||||
- **category: translation**: Everything concerning translations or new languages
|
||||
|
||||
Reference in New Issue
Block a user