Architecture Overview

This repository implements a documentation website for a bare-metal Kubernetes platform using a modern, server-side rendered (SSR) architecture. The core stack combines Astro 6 for content generation, Tailwind CSS v4 for styling, and Cloudflare Workers for deployment, ensuring high performance and global availability. The project enforces strict code quality and content hygiene through automated CI/CD pipelines that monitor file sizes, prose standards, and site generation integrity.

High-Level Stack

For typography, the site uses the Inter font, which is self-hosted at build time via the Astro Fonts API to avoid external dependencies [src: astro.config.mjs:L14-L21][src: README.md:L21-L22]. The build process is optimized for performance, utilizing esbuild for JavaScript minification and enabling CSS minification [src: astro.config.mjs:L25-L28].

Deployment Target

The build output is structured into two main directories:

• dist/server/: Contains the worker entry point and a generated wrangler.json configuration file [src: README.md:L33-L34].
• dist/client/: Contains static assets such as images, CSS, and fonts [src: README.md:L35].

Deployment is executed via the command wrangler deploy --config dist/server/wrangler.json, which reads the generated configuration to push the site to Cloudflare [src: package.json:L13][src: README.md:L36].

Additional Cloudflare integrations include:

• Email Workers: Used for the contact form, bound via the [[send_email]] binding in wrangler.toml [src: wrangler.toml:L16-L17][src: README.md:L23].
• Turnstile: Used for CAPTCHA verification on the contact form, with the secret key managed as a Cloudflare secret [src: wrangler.toml:L14-L15][src: README.md:L24].

CI/CD Pipelines

The repository uses GitHub Actions to maintain code quality and manage site generation through two primary workflows.

Code Quality and Prose Hygiene

The ceiling.yml workflow runs on every push and pull request to the main and dev branches [src: .github/workflows/ceiling.yml:L5-L8]. It performs two key checks:

1. File Size Ceiling: Enforces a 1000-line limit on files using a custom Python script [src: .github/workflows/ceiling.yml:L14-L15].
2. Prose Hygiene: Ensures documentation adheres to style guidelines by checking for prohibited dashes, emojis, and AI-generated speech patterns [src: .github/workflows/ceiling.yml:L16-L17].

Wiki Site Build and Deploy

The wiki-pages.yml workflow handles the build and deployment of the LLM-generated wiki site to GitHub Pages [src: .github/workflows/wiki-pages.yml:L2-L3]. This workflow is triggered by pushes to the main branch affecting specific documentation paths (docs/wiki/**, wiki-site/**) or via manual dispatch [src: .github/workflows/wiki-pages.yml:L9-L14].

The pipeline consists of two jobs:

1. Build: Sets up Node.js 22, installs dependencies, and builds the site using the WIKI_SITE environment variable to derive the public URL [src: .github/workflows/wiki-pages.yml:L33-L43]. It uploads the dist directory as an artifact [src: .github/workflows/wiki-pages.yml:L44-L46].
2. Deploy: Deploys the artifact to GitHub Pages using the deploy-pages action [src: .github/workflows/wiki-pages.yml:L48-L58].

The workflow includes safeguards to prevent deployment on private repositories by checking the repository name suffix [src: .github/workflows/wiki-pages.yml:L23-L27].