--- description: Documentation Pages Location globs: *.mdx alwaysApply: false --- # Documentation Pages Location Rules for placing and organizing documentation pages in the repository. name: docs_location description: Standards for placing documentation pages in the correct directory structure filters: # Match any .mdx files - type: file_extension pattern: "\\.mdx$" # Match files that look like documentation pages - type: content pattern: "^---\\s*\\ntitle:.*\\ndescription:.*\\n---" # Match file creation events - type: event pattern: "file_create" actions: - type: reject conditions: - pattern: "^(?!packages/varlock-website/src/content/docs/.*\\.mdx$)" message: "Documentation pages (.mdx) must be placed in the packages/varlock-website/src/content/docs directory" - type: suggest message: | When creating documentation pages: 1. Always place documentation files under `packages/varlock-website/src/content/docs/`: ``` packages/varlock-website/src/content/docs/ ├── getting-started/ ├── guides/ # how-to guides (nested by topic in the sidebar) ├── integrations/ # frameworks, languages, platforms ├── plugins/ # secret backends ├── reference/ # CLI + schema language └── env-spec/ ``` 2. Top-level sections become sidebar **tabs** (Astro docs pattern), configured in `packages/varlock-website/src/sidebar.ts` and rendered by `TabbedSidebar.astro`: - **Getting Started** - Onboarding (keep short) - **Guides** - How-to guides, nested into Core / Encryption and delivery / AI and agents / Ops and migration - **Reference** - CLI, schema language, and `@env-spec` - **Ecosystem** - Integrations and Plugins (nested catalogs) Within a tab, nest subgroups so no level has more than ~8–10 siblings. 3. File naming: - Use kebab-case for filenames - Always use `.mdx` - Prefer a parent overview page plus children when a topic has independent H2 sections (CLI command groups, per-sandbox-tool, local vs remote MCP, etc.) 4. Never place documentation files: - In the project root - Outside `packages/varlock-website/src/content/docs/` - Under `guides/` for Docker (use `integrations/docker`) 5. Update the sidebar in `packages/varlock-website/src/sidebar.ts`: - Every page must have a corresponding sidebar entry - Add the page under the correct nested subgroup (do not append to a flat 15+ item list) - Aim for ≤8–10 siblings at any nesting level - Example (page under Guides > Core): ```ts { label: 'Guides', items: [ { label: 'Core', collapsed: true, items: [ { label: 'Schema', slug: 'guides/schema' }, { label: 'New Feature', slug: 'guides/new-feature' }, ], }, ], } ``` Top-level labels must stay one of: Getting Started, Guides, Reference, Ecosystem (they render as the tab switcher). Do not add a fifth top-level group without updating `TabbedSidebar.astro` icons. 6. If the page is a plugin or integration, also update homepage tiles in `packages/varlock-website/src/lib/works-with-tiles.ts` when it should appear on the homepage. examples: - input: | # Bad: Documentation file in wrong location docs/my-guide.mdx my-guide.mdx src/content/my-guide.mdx # Good: Documentation file in correct location packages/varlock-website/src/content/docs/guides/my-guide.mdx output: "Correctly placed documentation file" - input: | # Bad: Flat dump into Guides with 20 siblings # Added guides/new-ai-thing.mdx at the end of the Guides items array # Good: Nested under the right subgroup # Added under Guides > AI and agents in sidebar.ts output: "Documentation file nested in the correct sidebar subgroup" metadata: priority: high version: 2.0