|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This repository contains the documentation for Siderolabs products, particularly Omni - a Kubernetes management platform and Talos - a Linux operating system for Kubernetes. The documentation is built using Mintlify and configured via `docs.json`. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +### Documentation Structure |
| 12 | +- **Single documentation site**: All docs are organized under the `omni/`, `talos/`, and `kubernetes` directories. |
| 13 | +- **Mintlify-based**: Uses Mintlify documentation platform with configuration in `docs.json` |
| 14 | +- **MDX format**: All documentation files use `.mdx` extension for enhanced markdown with React components |
| 15 | +- **Hierarchical organization**: Content is organized into logical groups (Overview, Getting Started, Infrastructure, etc.) |
| 16 | + |
| 17 | +### Key Directories |
| 18 | +- `omni/overview/` - High-level product information |
| 19 | +- `omni/getting-started/` - User onboarding guides |
| 20 | +- `omni/infrastructure-and-extensions/` - Infrastructure setup and extensions |
| 21 | +- `omni/omni-cluster-setup/` - Cluster configuration guides |
| 22 | +- `omni/cluster-management/` - Ongoing cluster operations |
| 23 | +- `omni/security-and-authentication/` - Security and auth configuration |
| 24 | +- `omni/reference/` - Reference documentation |
| 25 | +- `images/` - Static assets and screenshots |
| 26 | + |
| 27 | +### Navigation Configuration |
| 28 | +The site navigation is entirely defined in `docs.json` with a tab-based structure. All pages must be explicitly listed in the navigation configuration to appear in the documentation site. |
| 29 | + |
| 30 | +## Content Standards |
| 31 | + |
| 32 | +### File Naming |
| 33 | +- Use kebab-case for file and directory names |
| 34 | +- All documentation files use `.mdx` extension |
| 35 | +- Image files are organized in `images/` subdirectories within relevant sections |
| 36 | + |
| 37 | +### Documentation Structure |
| 38 | +- Each `.mdx` file begins with YAML frontmatter containing at minimum a `title` field |
| 39 | +- Content focuses on Omni platform usage, Kubernetes cluster management, and Talos Linux integration |
| 40 | +- Includes step-by-step guides with screenshots stored in adjacent `images/` directories |
| 41 | + |
| 42 | +## Development Workflow |
| 43 | + |
| 44 | +### Local Development with Docker |
| 45 | +To preview the documentation locally without installing Mintlify, use the provided Makefile: |
| 46 | + |
| 47 | +```bash |
| 48 | +# Build container and start preview server |
| 49 | +make preview |
| 50 | + |
| 51 | +# View available commands |
| 52 | +make help |
| 53 | +``` |
| 54 | + |
| 55 | +Alternatively, use Docker commands directly: |
| 56 | +```bash |
| 57 | +# Build the Docker image |
| 58 | +docker build -t mintlify-docs . |
| 59 | + |
| 60 | +# Run the development server (mounts current directory) |
| 61 | +docker run -p 3000:3000 -v $(pwd):/docs mintlify-docs |
| 62 | +``` |
| 63 | + |
| 64 | +Access the site at http://localhost:3000 |
| 65 | + |
| 66 | +### Generating docs.json |
| 67 | +The `docs.json` file is automatically generated from multiple YAML config files using a containerized generator: |
| 68 | + |
| 69 | +```bash |
| 70 | +# Generate and validate docs.json using container (recommended) |
| 71 | +make docs.json |
| 72 | + |
| 73 | +# Check for MDX files not included in configuration |
| 74 | +make check-missing |
| 75 | + |
| 76 | +# Build the docs-gen container locally (if needed) |
| 77 | +make build-docs-gen |
| 78 | + |
| 79 | +# Alternative: Use local Go build for development |
| 80 | +make docs.json-local |
| 81 | +make check-missing-local |
| 82 | +make generate-deps # Install Go dependencies |
| 83 | +``` |
| 84 | + |
| 85 | +The generator supports **multi-file configuration** - it merges multiple YAML files where: |
| 86 | +- **Base configuration**: First file provides site metadata (colors, branding, etc.) |
| 87 | +- **Navigation tabs**: All `navigation.tabs` from all files are combined in order |
| 88 | +- **Icon support**: Tabs can specify icons with the `icon` field |
| 89 | + |
| 90 | +**Schema validation is enabled by default** and validates against the Mintlify schema. Use `make check-missing` to find any documentation files that aren't included in the navigation. |
| 91 | + |
| 92 | +### Making Changes |
| 93 | +1. Edit `.mdx` files directly for content updates |
| 94 | +2. Update YAML config files: |
| 95 | + - `common.yaml` for site metadata (colors, branding, global navigation) |
| 96 | + - `omni.yaml` for Omni-specific navigation tabs |
| 97 | + - Additional YAML files for other product tabs |
| 98 | +3. Run `make docs.json` to regenerate the configuration |
| 99 | +4. Add images to appropriate `images/` subdirectories |
| 100 | +5. Use Docker setup above to preview changes locally |
| 101 | + |
| 102 | +### Multi-File Configuration |
| 103 | +The generator merges YAML files in the order specified: |
| 104 | +```bash |
| 105 | +# Using container (recommended) |
| 106 | +docker run --rm -v $(PWD):/workspace -w /workspace ghcr.io/siderolabs/docs-gen:latest common.yaml omni.yaml additional-tabs.yaml |
| 107 | + |
| 108 | +# Using local Go build |
| 109 | +cd docs-gen && go run main.go ../common.yaml ../omni.yaml ../additional-tabs.yaml |
| 110 | +``` |
| 111 | + |
| 112 | +Example tab with icon: |
| 113 | +```yaml |
| 114 | +navigation: |
| 115 | + tabs: |
| 116 | + - tab: "Product Name" |
| 117 | + icon: "/images/product.svg" # or FontAwesome icon name |
| 118 | + groups: |
| 119 | + - group: "Getting Started" |
| 120 | + folder: "product/getting-started" |
| 121 | +``` |
| 122 | +
|
| 123 | +### Manual Page Configuration |
| 124 | +The generator supports two approaches for page organization: |
| 125 | +
|
| 126 | +**Option 1: Automatic folder scanning (current default)** |
| 127 | +```yaml |
| 128 | +navigation: |
| 129 | + tabs: |
| 130 | + - tab: "Docs" |
| 131 | + groups: |
| 132 | + - group: "Getting Started" |
| 133 | + folder: "docs/getting-started" |
| 134 | + order: # Optional custom ordering |
| 135 | + - "intro.mdx" |
| 136 | + - "setup.mdx" |
| 137 | +``` |
| 138 | +
|
| 139 | +**Option 2: Manual page definition (NEW)** |
| 140 | +```yaml |
| 141 | +navigation: |
| 142 | + tabs: |
| 143 | + - tab: "Docs" |
| 144 | + groups: |
| 145 | + - group: "Security and Authentication" |
| 146 | + folder: "omni/security-and-authentication" # Optional base path |
| 147 | + pages: |
| 148 | + - "authentication-and-authorization" |
| 149 | + - "how-to-manage-acls" |
| 150 | + - "omni-kms-disk-encryption" |
| 151 | + - group: "Rotate Siderolink Join Token" |
| 152 | + pages: |
| 153 | + - "rotate-siderolink-join-token/rotate-siderolink-join-token" |
| 154 | + - group: "Using SAML With Omni" |
| 155 | + pages: |
| 156 | + - "using-saml-with-omni/auto-assign-roles-to-saml-users" |
| 157 | + - "using-saml-with-omni/configure-saml-and-acls" |
| 158 | + - "using-saml-with-omni/how-to-configure-entraid-for-omni" |
| 159 | + - "using-saml-with-omni/overview" |
| 160 | +``` |
| 161 | +
|
| 162 | +**Key features of manual page configuration:** |
| 163 | +- **Mixed content**: Can combine individual pages and subgroups |
| 164 | +- **Nested subgroups**: Subgroups can contain other subgroups |
| 165 | +- **Base path**: Optional `folder` field prepends to all page paths |
| 166 | +- **Flexible structure**: Full control over navigation hierarchy |
| 167 | +- **Backward compatible**: Falls back to folder scanning if no `pages` defined |
| 168 | + |
| 169 | +### Content Guidelines |
| 170 | +- Focus on practical, actionable guidance for Omni users |
| 171 | +- Include screenshots for UI-based procedures |
| 172 | +- Maintain consistency with existing documentation structure and tone |
| 173 | +- All content relates to Kubernetes management, infrastructure setup, or security configuration |
| 174 | + |
| 175 | +## Important Notes |
| 176 | + |
| 177 | +- **Containerized generator**: The `docs.json` file is generated using a containerized tool (`ghcr.io/siderolabs/docs-gen`) |
| 178 | +- **Multi-file configuration**: Generated from multiple YAML files - edit the YAML files, not the JSON directly |
| 179 | +- **Automatic page discovery**: The generator automatically discovers all `.mdx` files in configured folders |
| 180 | +- **CI/CD integration**: The container is built and published automatically via GitHub Actions |
| 181 | +- **Mintlify hosting**: The site is hosted and built by Mintlify using the `docs.json` configuration |
| 182 | +- **Static assets**: All images are committed to the repository in `images/` directories |
| 183 | + |
| 184 | +## Generator Configuration |
| 185 | + |
| 186 | +### Code Structure |
| 187 | +- **`docs-gen/`**: Contains the Go generator code |
| 188 | + - `main.go`: Main generator logic |
| 189 | + - `go.mod`, `go.sum`: Go module files |
| 190 | +- **YAML config files**: In root directory (e.g., `common.yaml`, `omni.yaml`) |
| 191 | + |
| 192 | +### Configuration Files |
| 193 | +The YAML config files control: |
| 194 | +- **Site metadata**: name, colors, logos, banners |
| 195 | +- **Schema validation**: URL for Mintlify JSON schema validation |
| 196 | +- **Navigation structure**: tabs, groups, and folder mappings |
| 197 | +- **Page ordering**: optional custom ordering within groups |
| 198 | +- **Global navigation**: footer links, external anchors |
| 199 | +- **Redirects**: URL redirects for moved or renamed pages |
| 200 | + |
| 201 | +Each navigation group maps to a folder, and all `.mdx` files in that folder are automatically included. Subdirectories become nested groups. |
| 202 | + |
| 203 | +### Schema Validation |
| 204 | +The generator validates the output against the Mintlify schema by default. To skip validation (not recommended), use: |
| 205 | +```bash |
| 206 | +go run main.go --skip-validation common.yaml > docs.json |
| 207 | +``` |
| 208 | + |
| 209 | +### Redirects |
| 210 | +Add redirects to handle moved or renamed pages: |
| 211 | +```yaml |
| 212 | +redirects: |
| 213 | + - source: "/old-path" |
| 214 | + destination: "/new-path" |
| 215 | + - source: "/legacy-docs/*" |
| 216 | + destination: "/docs/$1" |
| 217 | +``` |
| 218 | + |
| 219 | +Redirects support wildcards (`*`) and parameter substitution (`$1`, `$2`, etc.) as described in the [Mintlify redirects documentation](https://mintlify.com/docs/settings/broken-links#redirects). |
0 commit comments