Astro Content Collections for Multi-Tenant Help Docs: Rendering Tenant-Specific Documentation Without CMS Sprawl

A developer built a multi-tenant documentation system for CitizenApp using Astro Content Collections, replacing a headless CMS with static Markdown files versioned in Git. The system generates tenant-specific help docs at build time by filtering content based on feature gates and tier requirements, eliminating the need for CMS API calls or separate documentation sites. The approach enforces schema validation through Astro's Content Collections and handles routing boilerplate, producing fast, cacheable HTML files that are auditable through the repository.

I've watched teams burn money on Contentful, Strapi, and Sanity licenses just to manage help documentation that differs slightly between billing tiers. A startup pays $500/month for a headless CMS when they could ship the same thing as static files versioned in Git. Here's the hard truth: most SaaS help docs don't need a CMS . They need Git, a build pipeline, and metadata. If you're using Astro already and you should be for marketing sites , Content Collections gives you a native, zero-overhead way to generate tenant-specific documentation at build time. I built this for CitizenApp. We have 9 AI features split across three tiers. Each tenant sees only the docs for features they've paid for. Instead of querying a CMS API on every request or maintaining separate documentation sites, we define docs as Markdown, tag them with feature gates, and Astro handles the rest during the static build. When you use a headless CMS for documentation: Static generation eliminates all of this. Your docs compile at build time. They're just HTML files. They're fast, cacheable, and auditable because they're in your repo. I prefer Astro's Content Collections over rolling my own because it enforces schema validation and handles the routing boilerplate. Without it, you're writing custom glob patterns and Zod schemas. With it, it's declarative. First, define your content schema with feature-level metadata: js // src/content/config.ts import { defineCollection, z } from 'astro:content'; const docsCollection = defineCollection { type: 'content', schema: z.object { title: z.string , description: z.string , // Tier requirement: 'free', 'pro', 'enterprise' minTier: z.enum 'free', 'pro', 'enterprise' .default 'free' , // Feature flags—a doc can require multiple features requiredFeatures: z.array z.string .default , // Category for navigation category: z.enum 'getting-started', 'ai-features', 'billing', 'api' , // Publication status draft: z.boolean .default false , lastUpdated: z.date .optional , } , } ; export const collections = { docs: docsCollection, }; Now, structure your content directory with tenant-aware naming: src/content/docs/ ├── getting-started/ │ ├── setup.md minTier: free │ └── authentication.md minTier: free ├── ai-features/ │ ├── text-summarization.md minTier: free, requiredFeatures: summarization │ ├── sentiment-analysis.md minTier: pro, requiredFeatures: sentiment │ └── custom-models.md minTier: enterprise, requiredFeatures: custom-models ├── billing/ │ ├── plans.md minTier: free │ └── enterprise-sso.md minTier: enterprise └── api/ └── reference.md minTier: pro Here's a concrete doc file: --- title: "Sentiment Analysis API" description: "Analyze emotion and intent in user input" minTier: "pro" requiredFeatures: "sentiment-analysis", "api-access" category: "ai-features" lastUpdated: 2025-01-15 --- Sentiment Analysis Our sentiment engine classifies text into positive, negative, neutral, and mixed. Endpoint POST /api/v1/sentiment Authorization: Bearer YOUR API KEY Response json { "score": 0.87, "label": "positive", "confidence": 0.94 } typescript The magic happens in your Astro pages. You filter collections by tenant tier and features: js // src/pages/docs/ tenant / ...slug .astro import { getCollection } from 'astro:content'; import type { GetStaticPaths } from 'astro'; // Your tenant configuration from database, config file, etc. const TENANTS = { acme free: { tier: 'free', features: 'summarization' }, acme pro: { tier: 'pro', features: 'summarization', 'sentiment-analysis', 'api-access' }, globex enterprise: { tier: 'enterprise', features: 'summarization', 'sentiment-analysis', 'custom-models', 'api-access', 'sso' }, }; export const getStaticPaths: GetStaticPaths = async = { const allDocs = await getCollection 'docs' ; const paths = ; // Generate a static page for every doc + tenant combination for const tenantId, config of Object.entries TENANTS { const visibleDocs = allDocs.filter doc = { // Check tier access const tierHierarchy = { free: 0, pro: 1, enterprise: 2 }; if tierHierarchy config.tier < tierHierarchy doc.data.minTier { return false; } // Check feature access if doc.data.requiredFeatures.length 0 { const hasAllFeatures = doc.data.requiredFeatures.every feature = config.features.includes feature ; if hasAllFeatures return false; } // Exclude drafts if doc.data.draft return false; return true; } ; // Create routes for const doc of visibleDocs { paths.push { params: { tenant: tenantId, slug: doc.slug }, props: { doc, tenantId, config }, } ; } } return paths; }; interface Props { doc: any; tenantId: string; config: any; } const { doc, tenantId, config } = Astro.props; const { Content } = await doc.render ; --- <html <head <title {doc.data.title}</title </head <body <nav <p Tenant: {tenantId} | Tier: {config.tier}</p </nav <article <h1 {doc.data.title}</h1 <Content / </article </body </html This generates N docs × M tenants static HTML files at build time. Deploy to Cloudflare Pages or Vercel. Each tenant gets their own URL namespace /docs/acme pro/ai-features/sentiment-analysis , and the HTML is precomputed. You've got a new AI feature? Add a Markdown file, set minTier: pro , and commit. GitHub Actions builds and deploys in seconds. No CMS UI to configure, no API calls during rendering, no cache invalidation headers to debug. .github/workflows/docs.yml name: Deploy Docs on: push: branches: main paths: "src/content/docs/ " jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 - run: npm install && npm run build - uses: cloudflare/pages-action@v1 with: apiToken: ${{ secrets.CLOUDFLARE API TOKEN }} Here's what burned me: if you're generating /docs/acme pro/ and /docs/globex enterprise/ separately, search engines see duplicate content. The same help doc appears at multiple URLs. Solution: Add a robots meta tag to tenant-specific builds: js // In your page component const isProductionTenant = tenantId === 'public'; // or check env const robotsContent = isProductionTenant ? 'index, follow' : 'noindex, follow'; --- <meta name="robots" content={robotsContent} / Or use canonical tags and serve the "public" docs at /docs/ with all features visible, then tenant-specific sites as internal-only. The second gotcha: versioning . If you have API docs that change between versions, your content schema needs a version field. Build tenant-specific and version-specific paths. This scales quickly—think it through before you ship. If your docs change hourly unlikely or require real-time user input comments, feedback forms , add a separate lightweight service. But for static help content? This is unbeatable. Ship less infrastructure. Version your docs in Git. Let Astro compile.