Service offering

Documentation as Code

Documentation that lives in GitHub, evolves with your code, and never falls out of sync. We build production-grade Nextra documentation sites — MDX-first, full-text search, custom component libraries, and GitHub Actions pipelines that deploy on every merge. CNBS runs its own documentation on this exact stack, so everything we deliver comes from production experience.

Nextra (Next.js)MDX ContentPagefind Full-Text SearchCustom Component LibraryGitHub Actions CI/CDStatic ExportPR Preview EnvironmentsOpenAPI → MDX GenerationS3 / CloudFront Hosting

How Documentation as Code Works

Documentation as Code treats every page, diagram, and reference as a version-controlled artefact — authored in MDX (Markdown + JSX), reviewed via pull request, and deployed automatically on merge. Nextra provides the framework: it maps a directory of MDX files to a navigable, searchable documentation site with zero configuration for the common case. CNBS builds on top of this foundation with custom components, automated content pipelines, and a CI/CD model that makes contributing to docs feel identical to contributing to code.

Documentation as Code pipeline — from source systems to live site, automated on every merge

Live Documentation Site (Nextra)

Nextra docs theme — sidebar, TOC, breadcrumbsPagefind full-text searchCustom MDX components (callouts, diagrams, code blocks)Static export — S3 / CloudFront / Vercel

↑ GitHub Actions: build → pagefind index → deploy → cache invalidation ↑

GitHub Repository — Content & Pipeline

MDX content files (pages, guides, reference)_meta.js navigation configGitHub Actions workflows (build · deploy · preview)PR preview environments (per-branch deploy)Auto-generated content (OpenAPI → MDX scripts)

↕ content sourcing — OpenAPI specs · README files · architecture records

Source Systems

OpenAPI / AsyncAPI specificationsGitHub READMEs and ADRsArchitecture diagrams (drawio · Mermaid · Excalidraw)Runbooks and operational procedures

Docs drift because they live outside the development workflow. Putting them in the same repository as the code, reviewed by the same people in the same PRs, is the only durable fix. Nextra’s zero-config approach makes this low-friction: authors write MDX, navigation is declared in a _meta.js file, and the site builds itself.

Nextra-Only: Why We Don’t Offer Docusaurus

We exclusively deliver Nextra for documentation-as-code engagements. Nextra is built on Next.js and React — the same stack used across modern frontend development. Your team can contribute to the documentation site using the same toolchain they use for their applications. We run this exact site on Nextra, which means every component, pipeline pattern, and hosting configuration we deliver is proven in production.

Nextra Docs Theme

For Technical Documentation & Reference Sites

The Nextra docs theme provides a structured, sidebar-driven layout suited to technical documentation, API references, runbooks, and architecture guides. Navigation is controlled entirely by _meta.js files — no frontmatter configuration required per page. Full-text search is delivered by Pagefind, indexed at build time, with no external search service dependency.

Sidebar navigation driven by _meta.js hierarchy
Table of contents auto-generated from headings
Pagefind full-text search — no Algolia dependency
Dark / light mode, responsive layout
Code blocks with syntax highlighting and copy button

Custom Component Layer

MDX Components Matching Your Design System

Standard Nextra is extended with a custom MDX component library that matches your brand and documentation patterns. Callouts, badges, architecture diagrams, flow visualisations, API endpoint cards, and step-by-step guides are delivered as reusable JSX components — authors use them in MDX without touching React or CSS. Components are type-safe and documented.

Callout / alert components (info, warning, tip, danger)
Architecture diagram primitives (layers, flows, chips)
Step-by-step numbered procedure components
API endpoint reference cards
Badge and tag components for status / version labelling

Core Capabilities

Framework

Nextra — MDX-First, Zero Configuration for Authors

Nextra maps a directory of MDX files to a navigable documentation site with sidebar, table of contents, and full-text search configured at the framework level — not per-page. Authors write standard Markdown with optional JSX component usage. Adding a page is as simple as dropping an MDX file in the right directory and adding one entry to _meta.js. No build configuration, no plugin wiring, no template copying per page.

Nextra 4 · Next.js 16 · MDX 3 · nextra-theme-docs · _meta.js navigation · React 19 · Tailwind CSS · Pagefind · static export

Workflow

GitHub-Native — PR Reviews for Documentation Changes

Documentation changes go through the same PR workflow as code changes — diff review, comments, approvals, and merge. This is not just a process decision: it means documentation quality is enforced the same way code quality is. Broken links, missing navigation entries, and structural errors are caught in review, not discovered by users. A GitHub Actions workflow builds a preview deployment for every PR so reviewers can check the rendered result before approving.

GitHub PR workflow · branch protection rules · PR preview deployment · GitHub Actions · review-required policy · automated link checking · build validation on PR

Automation

Auto-Generated Content — OpenAPI, READMEs, Diagrams

Manually maintaining API reference pages is a losing battle — they fall behind the moment the spec changes. We build content generation scripts that pull OpenAPI or AsyncAPI specifications from your repositories and render them as structured MDX pages on every build. README files and Architecture Decision Records can be pulled from source repositories and embedded into the docs site automatically, keeping reference content in sync with its source of truth.

OpenAPI → MDX generation · AsyncAPI rendering · GitHub API content pull · Mermaid diagram rendering · ADR embedding · remark / rehype plugins · build-time generation scripts

Hosting

Static Export — S3 / CloudFront on Your Infrastructure

Nextra’s static export produces plain HTML, CSS, and JS — no Node server required at runtime, no external service dependency, no vendor lock-in. The output is synced to a private S3 bucket served through CloudFront with HTTPS, custom domain, and cache invalidation on every deploy. Hosting costs are a fraction of a managed documentation service. You own the infrastructure and the content — nothing runs on a third-party platform you don’t control.

Next.js static export · AWS S3 + CloudFront · ACM TLS certificate · custom domain · CloudFront cache invalidation · GitHub Actions deploy pipeline · Terraform-provisioned infrastructure

What We Deliver

Nextra Site Setup & Theme Configuration

Nextra project initialised with Next.js App Router, nextra-theme-docs, Tailwind CSS, and static export configured. Theme customised to your brand — colours, logo, fonts, and footer. Navigation structure designed and implemented via _meta.js hierarchy. Pagefind full-text search integrated and validated. Dark/light mode, responsive layout, and SEO metadata configured.

Content Architecture & Navigation Design

Information architecture designed for your documentation scope — directory structure, page hierarchy, and navigation groupings that match how your users look for information. _meta.js files configured for all sections. URL structure agreed and stabilised before content migration to avoid link rot. Page templates created for common content types: guides, reference pages, runbooks, and ADRs.

Custom MDX Component Library

A set of reusable JSX components registered in mdx-components.js — usable in MDX without any import statement. Callouts (info, warning, tip, danger), badges, architecture diagram primitives (layered diagrams, flow sequences), step-by-step numbered procedures, API endpoint cards, and code blocks with language labels. All components are type-safe, styled to your design system, and documented with usage examples.

GitHub Actions CI/CD Pipeline

Production deploy pipeline: on merge to main — install, build, pagefind index, sync to S3, invalidate CloudFront cache. PR preview pipeline: on PR open/update — build and deploy to a branch-specific S3 prefix, post the preview URL as a PR comment. Link checker and build validation run on every PR. Pipeline includes approval gate for production deploys if required.

Auto-Generated Content Integration

Build-time scripts that pull OpenAPI or AsyncAPI specifications from your source repositories and render them as structured MDX API reference pages — automatically updated on every deploy. README and ADR pull scripts for embedding repository-level documentation into the site. Mermaid diagram rendering configured for architecture diagrams authored in source files.

Static Hosting on Your Infrastructure

Terraform-provisioned S3 bucket and CloudFront distribution with ACM TLS certificate, custom domain, and security headers (HSTS, CSP, X-Frame-Options). Route 53 DNS configuration. CloudFront cache invalidation integrated into the deploy pipeline. Hosting configuration is yours — no subscription to a documentation platform, no usage-based pricing, no data leaving your AWS account.

How Customers Benefit

Accurate

Documentation That Can’t Drift from the Code

When docs live in the same repository as the code they describe, drift is structurally prevented — not managed by policy. A PR that changes an API must update the documentation in the same diff. Auto-generated pages pull directly from the OpenAPI spec — they update the moment the spec does.

Reviewed

Every Change Goes Through PR Review

Documentation quality is enforced the same way code quality is — branch protection, required reviewers, and PR preview deployments. Broken navigation, missing pages, and incorrect content are caught before merge, not discovered by users. The review process builds shared ownership of the documentation across the team.

Fast

Static Site — Sub-Second Page Loads, Offline Search

Nextra’s static export produces pre-rendered HTML for every page — no server rendering, no API round-trips, no hydration wait. Pagefind search is fully client-side and index-based, with no external search service and no latency beyond the initial index load. CloudFront caches every asset at the edge globally.

Owned

Your Infrastructure, Your Content, No Vendor Lock-In

The site is a Next.js application and a set of MDX files in a GitHub repository — nothing proprietary, nothing hosted on a third-party documentation platform. Your team can maintain, extend, and migrate it independently. Hosting runs on your own S3 and CloudFront with Terraform-managed infrastructure you control entirely.

Automated

Deploy on Merge, Preview on Every PR

Production deployments happen automatically on merge to main — build, index, sync, invalidate. PR preview environments deploy to a branch-specific URL and post a comment with the link. Contributors see the rendered result of their changes before requesting review, reducing the back-and-forth of “did that render correctly?”

Proven

Built by a Team That Runs This Stack in Production

CNBS runs its own website and documentation on Nextra with the exact same stack — static export, S3/CloudFront hosting, GitHub Actions pipeline, Pagefind search. Every component and pattern we deliver has been validated in a live production environment, not assembled from documentation and tutorials.

How We Work

Content Audit & Architecture Design

We review your existing documentation — wikis, Confluence spaces, README files, architecture records, runbooks — and design an information architecture that maps to Nextra’s directory-based navigation model. URL structure, section hierarchy, and content types agreed before any code is written.

Nextra Setup & Component Library

Nextra project initialised with your branding, theme configuration, and static export settings. Custom MDX component library built and registered. Pagefind search integrated and validated. Page templates created for each content type — authors have a clear starting point for every page they write.

GitHub Actions Pipeline & Hosting

Production and PR preview pipelines configured. Terraform provisions S3 bucket, CloudFront distribution, ACM certificate, and Route 53 DNS. First production deploy validated end-to-end — build, index, sync, cache invalidation, custom domain resolution. Branch protection rules and PR preview deployment configured.

Auto-Generated Content & Content Migration

OpenAPI/AsyncAPI generation scripts built and integrated into the build pipeline. README and ADR pull scripts configured for repositories in scope. Existing documentation migrated from source systems into MDX — reformatted, restructured, and cross-linked according to the agreed information architecture.

Handover & Team Enablement

Contribution guide written — how to add a page, how to use each component, how the pipeline works, how to run the site locally. Live walkthrough with your team covering the authoring workflow, PR review process, and how to extend the component library. CNBS available for ongoing feature additions and platform maintenance under a retained arrangement.

Ready to fix documentation for good?

Let’s build your documentation system — in your repo, on your infrastructure, maintained like code.

Tell us about your current documentation landscape, your team’s toolchain, and what content needs to live there — we’ll design and deliver a Nextra site that your team actually wants to contribute to.

Get in touch →