docs-location

Documentation Pages Location

Rules for placing and organizing documentation pages in the repository.

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):

       {
         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"