mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-20 22:44:25 +00:00
96f9bbc044
### **Restructure Docs Navigation & Consolidate Core Concepts**
**Summary**
This PR refactors the documentation navigation to follow a clearer
**User Journey** and consolidates fragmented pages to reduce redundancy.
**Key Changes**
* **Sidebar:**
* Replaced the legacy resource-based structure with user-journey-focused
categories.
**Proposed Structure:**
```
Get Started
├─ Overview
│ └─ Guides Overview (Brief intro to docs, persona-aligned: "Get auth working in minutes for your B2B app.")
├─ Quickstart Guide
│ └─ Quickstart (Step-by-step: Sign up, spin up instance, connect app, log in – mirrors brand's 4-step guide.)
├─ Authenticate Users
│ ├─ Login with ZITADEL (OIDC)
│ ├─ Get ID / Access Token
│ └─ Logout
├─ Examples & SDKs
│ ├─ SPA / Frontend
│ ├─ Web Applications
│ ├─ APIs / Backend Services
│ ├─ Hybrid / Full-Stack
│ └─ Sample Applications (Include community-contributed examples for openness.)
├─ Key Concepts
│ ├─ Instances, Orgs, Projects, Apps
│ ├─ Policies (Intro)
│ └─ Users & Roles
└─ Use Cases
├─ B2B Integration (Tailored to multi-tenant enterprise needs.)
├─ B2C Login
├─ Multi-Tenant / SaaS
├─ Branded Login & White-Label
└─ Machine-to-Machine (M2M)
Configure Identity & Policies
├─ Identity Providers
│ ├─ External IDPs (e.g., Google, Azure)
│ └─ Custom Providers
├─ Policies
│ ├─ Password Policies
│ ├─ Lockout Policies
│ └─ Privacy Policies
├─ Roles & Permissions
│ ├─ RBAC Setup
│ └─ Custom Roles
└─ Compliance & Security
├─ Audits & Logs
└─ Certifications (Highlight trust through openness.)
Integrate & Authenticate
├─ OIDC & OAuth Flows
├─ API Access
│ ├─ gRPC APIs
│ └─ REST APIs
├─ SDKs
│ ├─ Go
│ ├─ JavaScript/TypeScript
│ ├─ Python
│ └─ Others (Link to community SDKs.)
└─ External Integrations
├─ SAML
├─ LDAP
└─ Webhooks
Test & Debug
├─ Testing Tools
│ ├─ Console Testing
│ └─ API Playground
├─ Common Issues
│ ├─ Token Errors
│ └─ Integration Failures
└─ Debugging Guides
├─ Logs & Monitoring
└─ Error Codes Reference
Deploy & Operate
├─ Deployment Options
│ ├─ Cloud (ZITADEL Cloud)
│ ├─ Self-Hosted (Linux, MacOS)
│ ├─ Docker Compose
│ └─ Kubernetes
├─ Configuration
│ ├─ Environment Variables
│ └─ Advanced Settings
├─ Scaling & Performance
│ ├─ High Availability
│ └─ Backup & Restore
└─ Monitoring & Maintenance
├─ Metrics
└─ Upgrades
Architecture & Concepts
├─ System Architecture
│ ├─ Core Components
│ └─ Data Flow Diagrams (Expressive visuals per brand.)
├─ Principles
│ ├─ Multi-Tenancy
│ └─ Open Standards (OIDC, SAML)
└─ Advanced Topics
├─ Customization
└─ Extensibility (Open-source contributions.)
Product, Releases & Support
├─ Product Features
│ ├─ Roadmap (Public, for transparency.)
│ └─ Pricing & Tiers
├─ Releases
│ ├─ Changelog
│ └─ Upgrade Guides
└─ Support Resources
├─ Community (Discord, GitHub – for community-led growth.)
├─ FAQ
├─ Contact Support
└─ Contribute (Encourage feedback/shaping the product.)
```
**Content Consolidation:**
* Merged separate "Concept" and "Console Guide" files into single,
comprehensive **Overview** pages for core resources:
* `Organizations`, `Projects`, `Applications`, `Users`, `Console`, and
`Actions`.
```
concepts/structure/organizations + guides/manage/console/organizations -> guides/manage/console/organizations-overview
concepts/structure/projects + guides/manage/console/projects -> guides/manage/console/projects-overview
concepts/structure/applications + guides/manage/console/applications -> guides/manage/console/applications-overview
concepts/structure/users + guides/manage/console/users -> guides/manage/console/users-overview
guides/manage/console/actions + apis/actions/introduction -> guides/manage/console/actions-overview
concepts/features/console + guides/manage/console/overview -> guides/manage/console/console-overview
```
**Redirects (`vercel.json`):**
* Added permanent redirects for all the 6 legacy files mentioned above
**No files were deleted**
---------
Co-authored-by: Florian Forster <[email protected]>
ZITADEL-Docs
This website is built using Docusaurus 2, a modern static website generator.
The documentation is part of the ZITADEL monorepo and uses pnpm and Nx for development and build processes.
Quick Start
Run the following commands from the repositories root directory to install all dependencies needed. Using Corepack makes sure you have the pnpm version installed that is declared in .
corepack enable
pnpm install
Start a docs server
# Start development server with live-reloading
pnpm nx run @zitadel/docs:dev
# Or serve a production build
pnpm nx run @zitadel/docs:prod
The site will be available at http://localhost:3100
Add new Sites to existing Topics
To add a new site to the already existing structure simply save the md file into the corresponding folder and append the sites id int the file sidebars.js.
If you are introducing new APIs (gRPC), you need to add a new entry to docusaurus.config.js under the plugins section.
Build Process
The documentation build process automatically:
- Downloads required protoc plugins - Ensures
protoc-gen-connect-openapiis available - Generates gRPC documentation - Creates API docs from proto files
- Generates API documentation - Creates OpenAPI specification docs
- Copies configuration files - Includes configuration examples
- Builds the Docusaurus site - Generates the final static site