mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
Florian ForsterandGitHub
2763e93a61
## What
Shorten the `title` frontmatter on 20 docs pages so that the rendered
`<title>` tag stays within the 70-character SEO limit.
The root layout appends ` | ZITADEL Docs` (15 chars) to every page
title, meaning the raw frontmatter `title` must be ≤ 55 characters. A
site scan flagged all 20 pages for the "Title too long" warning (titles
ranged from 71 to 92 characters in the final rendered tag).
## Why
Search engines may truncate or ignore `<title>` tags longer than 70
characters, hurting click-through rates and keyword relevance in search
results.
## How
Each title was rewritten to:
- Fit within 55 characters (leaving room for ` | ZITADEL Docs`)
- Front-load the primary search keyword (product name, protocol, or
feature)
- Include "ZITADEL" where users realistically search for `{feature}
ZITADEL`
- Avoid generic filler words ("Configure", "Set up", "Support for")
All 20 files already have a `sidebar_label` field that preserves the
original descriptive title for sidebar navigation — no navigation
changes result from this PR.
## Pages updated
| Page | Before (chars) | After (chars) |
|---|---|---|
| concepts/features/passkeys | 82 | 64 |
| guides/integrate/identity-providers/openldap | 72 | 58 |
| guides/solution-scenarios/b2b | 78 | 59 |
| guides/integrate/services/cloudflare-oidc | 86 | 54 |
| guides/integrate/login/hosted-login | 71 | 55 |
| guides/integrate/service-accounts/private-key-jwt | 76 | 56 |
| guides/integrate/service-accounts/client-credentials | 78 | 60 |
| guides/integrate/services/google-cloud | 92 | 57 |
| guides/solution-scenarios/saas | 88 | 65 |
| guides/migrate/sources/auth0 | 73 | 65 |
| guides/integrate/login-ui/oidc-standard | 81 | 55 |
| guides/integrate/login-ui/username-password | 73 | 59 |
| guides/integrate/login-ui/device-auth | 78 | 60 |
| guides/integrate/identity-providers/linkedin_oauth | 72 | 58 |
| guides/integrate/identity-providers/pingfederate-saml | 74 | 61 |
| guides/integrate/service-accounts/personal-access-token | 82 | 62 |
| legal/service-description/cloud-service-description | 76 | 61 |
| guides/integrate/login/login-users | 83 | 55 |
| guides/integrate/identity-providers/migrate | 74 | 65 |
| guides/manage/console/projects-overview | 71 | 62 |
All final `<title>` values are between 54 and 66 characters (well under
the 70-char limit).
@zitadel/docs
Documentation for Zitadel, built with Fumadocs and Next.js.
Getting Started
Ensure you have followed the root quick start to set up dependencies.
Local Development
Start the development server:
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 lintto check for syntax and style issues in JS/TS/MDX files. - Content Integrity: Run
pnpm check:linksto 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:
- Downloads required protoc plugins.
- Generates gRPC documentation from proto files.
- Generates API documentation from OpenAPI specs.
- Generates index files for directory structures.
Style Guide
- Variables: Use environment variables in code snippets where possible.
- Embedded Content: Use
_filename.mdxfor content embedded in other pages (not indexed individually). - Code Embedding: Use the
fileproperty 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 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:
- Create a
.mdxfile in the appropriate subdirectory ofcontent. - Register the new page in the sidebar settings at
lib/sidebar-data.tsto make it accessible in the navigation.
Pull Requests
Use docs(<scope>): <short summary> for PR titles.
Pass quality checks before submitting:
pnpm nx run @zitadel/docs:build
pnpm nx run @zitadel/docs:check:links
You can also run specific steps individually:
pnpm fetch:remote-contentpnpm generate:api-reference