Skip to content

Docs as Code

Publish module documentation through GitHub Pages with custom domains using DNS-as-Code and Zensical.

Guides

  • GitHub Pages Setup — set up a GitHub Pages site for an OpsDev.nz module with a custom domain

Overview

OpsDev.nz modules publish their documentation through GitHub Pages using a consistent workflow:

  1. Zensical builds the docs site from docs/ in each module
  2. GitHub Actions deploys the site on merge to main
  3. OctoDNS manages the DNS records for custom domains
  4. Metaname is the DNS provider for opsdev.nz and opstest.nz

This approach keeps documentation close to the code, deploys automatically on merge, and uses the same DNS-as-Code workflow as production infrastructure.

Custom domains

Each module gets its own subdomain under opsdev.nz:

Module Domain
op-opsdevnz op.opsdev.nz
octodns-metaname octodns-metaname.opsdev.nz

The DNS records are managed in the OpsDev.nz monorepo's OctoDNS zone files, not in the individual module repositories.