Astro Content Collections: Building a Fast Documentation Site

Why documentation teams are moving to Astro content collections

Documentation teams move to Astro content collections because they get the simplicity of Markdown files with the safety of a typed database. Writers keep working in plain text, while developers get compile-time checks, fast static output and full control over layout.

A content collection is a named group of entries, such as docs pages, changelog items or API references, that share one schema and are loaded through one API. In Astro, you define collections in a single configuration file, and every page, sidebar and search index reads from them.

For Saudi software companies, fintechs and government suppliers, a docs site is often the first thing a technical buyer checks. A fast, bilingual, well-organised developer portal signals maturity long before a sales call.

How Astro content collections work under the hood

Astro content collections work in three layers: a loader fetches raw entries, a schema validates and types them, and query functions return them to your pages at build time. Understanding those three layers is enough to design a documentation site that scales to thousands of pages.

Layer 1: loaders decide where content comes from

A loader is a function that tells Astro how to find entries. The built-in glob loader reads every Markdown or MDX file that matches a pattern inside a base folder, such as src/content/docs. The file loader reads a single JSON or YAML file, which suits glossaries, FAQ lists or a table of supported countries. Community and custom loaders can pull from Contentful, Sanity, Notion or your own REST endpoint.

Layer 2: schemas turn frontmatter into a contract

Each collection can declare a schema written with Zod, a TypeScript validation library bundled with Astro. For docs, a sensible schema requires a title of at most 70 characters, a description between 50 and 160 characters, a sidebar order number, an optional version tag, a last-reviewed date and an owner field. If a writer forgets the description or types the date wrongly, the build stops and names the file.

Schemas can also reference other collections. A docs page can point to an authors collection or a products collection, and Astro checks that the referenced entry exists. That single feature removes most “orphan page” problems we see in docs audits.

Layer 3: query functions feed pages and navigation

Pages call getCollection to fetch every entry in a collection, optionally with a filter, or getEntry to fetch one entry by its ID. A render function converts the Markdown body into HTML plus a list of headings, which you can use for the “On this page” table of contents. Because all of this runs at build time, the reader receives finished HTML with no database call.

Where Starlight fits

Starlight is Astro’s official documentation theme, built on top of Astro content collections. It gives you a sidebar, full-text search powered by Pagefind, dark mode, versioned-looking navigation, accessible components and built-in internationalisation, including right-to-left layout for Arabic. For most teams, Starlight is the fastest route; a custom build makes sense only when the design must match a strong brand system or the docs sit inside a larger marketing site.

Our process: building a docs site step by step

We build documentation sites in eight steps, from content audit to performance budget. A 60–150 page bilingual docs site usually takes four to eight weeks with this process, most of it spent on content, not code.

1. Audit existing content. Export every current page into a spreadsheet with URL, title, owner, last update and monthly visits. Mark each one keep, merge, rewrite or delete. Most docs sites we audit can drop 20–35% of pages.
2. Design the information architecture. Group pages into four or five top-level sections, for example Getting started, Guides, API reference, Integrations and Changelog. Limit sidebar depth to three levels.
3. Define collections and schemas. Usually one docs collection, one changelog collection and one small data collection for shared items such as error codes or supported regions.
4. Set up the folder structure. Use locale folders, such as docs/en and docs/ar, with identical file names so each Arabic page maps to its English twin.
5. Migrate content. Convert HTML or wiki pages to Markdown with a script, then fix what the schema rejects. The build error list becomes your migration checklist.
6. Add search and navigation. Pagefind indexes the built HTML, so search works offline and costs nothing to host. Generate the sidebar from the order field rather than a hand-edited list.
7. Wire SEO and structured data. Unique titles and descriptions come straight from the schema. Add canonical URLs, an XML sitemap, hreflang pairs and TechArticle or FAQPage markup where it fits.
8. Set a performance budget and CI checks. Fail the pull request if a page exceeds, for example, 100 KB of JavaScript or if a link checker finds broken internal links.

Making the site bilingual: Arabic and English

Bilingual docs need more than translated files. Set the dir attribute to rtl on the Arabic layout, use CSS logical properties (margin-inline-start rather than margin-left) so spacing mirrors automatically, and keep code samples left-to-right inside Arabic pages. The W3C guidance on internationalization covers bidirectional text in detail.

Each page pair should output reciprocal hreflang tags for ar-SA and en, plus an x-default. Our free hreflang generator produces the tag set for a page pair so you can compare it with what your layout outputs. Arabic headings also run shorter or longer than English, so test the sidebar with real Arabic titles, not placeholder text.

Performance: why static docs stay fast

Static docs stay fast because the browser receives pre-built HTML and CSS with little or no JavaScript to parse. On a mid-range Android phone on a 4G connection, that difference is often one to three seconds of load time compared with a client-rendered docs app.

Targets worth setting

Aim well inside Google’s Core Web Vitals thresholds: Largest Contentful Paint at or under 2.5 seconds, Interaction to Next Paint at or under 200 milliseconds and Cumulative Layout Shift at or under 0.1. The web.dev guide to LCP explains what counts as the largest element. In our builds, docs pages built with Astro content collections typically land between 0.8 and 1.6 seconds LCP on mobile field data, with CLS close to zero.

Where speed still gets lost

• Web fonts: loading four weights of an Arabic font and four of a Latin font can add 400 KB. Subset fonts and load two weights each.
• Syntax highlighting in the browser: highlight code at build time with Shiki (built into Astro) rather than a client library.
• Unoptimised screenshots: use Astro’s image component to output AVIF or WebP with fixed dimensions, which also prevents layout shift.
• Chat widgets and analytics: load them after user interaction or on idle. A single support widget can outweigh the entire docs page.

Key benefits of Astro content collections for documentation

The main benefits of Astro content collections are fewer content bugs, faster pages and lower running costs. Each one is measurable within the first quarter after launch.

• Build-time validation: missing titles, invalid dates and broken references fail the build, so they never reach production.
• Type safety in templates: editors in VS Code autocomplete frontmatter fields, and a renamed field shows errors everywhere it is used.
• Near-zero JavaScript: pages are HTML first, which suits readers on mobile data plans and older laptops.
• Git-based workflow: docs changes go through pull requests and review, just like code, with full history.
• Low hosting costs: static hosting for a docs site commonly costs SAR 0–150 a month, compared with SAR 400–1,500 for a managed CMS plan.

“The best docs sites fail loudly at build time so they never fail quietly in front of a customer.”
— Best Web Developer engineering team

Use cases in Saudi Arabia: who needs a fast docs site

In Saudi Arabia, fast documentation sites matter most for fintechs, SaaS vendors, logistics platforms and suppliers integrating with government systems. Each group has technical readers who judge the product by the quality of its docs.

Fintech and payment APIs

Payment and open-banking providers need clear API references, sandbox guides and error-code tables. A data collection for error codes lets the same entries appear in the reference, the troubleshooting guide and the search index without copy-paste drift.

E-invoicing and ERP integrations

Software vendors connecting clients to ZATCA’s FATOORA e-invoicing platform publish step-by-step onboarding guides that change whenever requirements change. A lastReviewed field and version tag make it obvious which instructions are current. Link readers to the official ZATCA website for the rules themselves.

Astro vs Docusaurus vs Next.js vs hosted docs platforms

Astro wins on page weight and flexibility, Docusaurus on out-of-the-box versioning, Next.js on app-like features, and hosted platforms on speed of setup. The right choice depends on who writes the docs and how much control you need.

Choose Astro content collections when developers or technical writers own the docs, when speed and SEO matter, and when you want Arabic and English under one build. Choose a hosted platform when non-technical staff must publish daily without pull requests. Our web development service builds all of these, so the recommendation follows the brief rather than a favourite tool.

Vision 2030, AI search and the future of documentation

Vision 2030 is expanding the Saudi software, fintech and digital-government sectors, and every new platform needs documentation that developers and AI assistants can read. Docs built on structured collections are well placed for both.

• AI assistants as readers: developers increasingly ask chat assistants how to use an API. Clear headings, one topic per page and direct answers help assistants quote your docs accurately.
• Machine-readable exports: because entries are typed data, you can generate an llms.txt summary, a JSON search index or an OpenAPI cross-reference from the same collections.
• Arabic-first developer content: as more Saudi developers join the market, Arabic docs become a competitive advantage, not a translation afterthought.
• Accessibility as a requirement: tenders increasingly reference WCAG 2.2, and static HTML with semantic headings is the easiest base to make conformant.
• Structured data: TechArticle and FAQPage markup generated from schema fields keep rich results consistent. Our schema generator helps you draft the JSON-LD pattern before you template it.

Frequently Asked Questions about Astro documentation sites

Getting started with Astro content collections

Astro content collections give documentation teams a rare combination: writers keep plain Markdown, developers get typed and validated data, and readers get pages that load in about a second. Start with a content audit, a strict schema and Starlight, then add Arabic, search and structured data in that order.

For Saudi software and fintech teams, fast bilingual docs are now part of the product. Build them on a foundation that catches mistakes before customers do, and the site will keep up as your platform grows.