How alphagov/govuk-design-system works
Project type and purpose
This is a static-site generator for the GOV.UK Design System website. It consumes Markdown and Nunjucks templates (in src/), applies a pipeline of Metalsmith plugins and other Node.js modules (in lib/), bundles CSS (Sass) and JavaScript (Rollup), and outputs a fully static site (in build/). It includes a local dev server (Browsersync), automated tests (Jest + Puppeteer), linting (ESLint, Stylelint, HTMLValidate), and CI/CD (GitHub Actions → Netlify).
File structure
• Top-level build orchestrators in tasks/ (build.js, serve.js, start.js) invoke the pipeline.
• lib/ holds custom processing modules and Metalsmith plugins (render-markdown, lunr-index, fingerprinting, highlight, nunjucks integration, sitemap generation).
• src/ contains the content:
– Nunjucks pages & layouts (src/**/*.njk, views/)
– Markdown (src/**/*.md)
– Static assets: images/, styles (Sass under stylesheets/, plus govuk-frontend via NPM), and JavaScript components (src/javascripts/, bundled via Rollup).
• config/ and rollup.config.js define ports, paths, plugin options.
• __tests__ and lib/**/__tests__ contain unit and integration tests.
• .github/workflows drives CI.
Key README insights
• Node.js + NPM scripts for dev (npm start), build (npm run build), lint (npm run lint).
• CI runs tests, lints, builds on each push, and deploys via Netlify as per netlify.toml.
• Dependencies include govuk-frontend, Metalsmith ecosystem, Nunjucks, Rollup, Browsersync.
Diagramming the architecture
a. Main components:
– Developer environment (local Git repo, Node.js + NPM, nvm)
– Build orchestrator (tasks/start.js → tasks/build.js → tasks/serve.js)
– Processing pipeline:
• Read content (src/*.md + src/**/*.njk)
• Metalsmith core with plugins: render-markdown, metalsmith-lunr-index, fingerprint assets, generate-sitemap
• Nunjucks renderer (views/layouts + views/partials)
• Sass compiler (stylesheets → CSS via PostCSS/autoprefixer)
• Rollup bundler (src/javascripts → bundle.js)
– Output folder (build/) containing static HTML, CSS, JS, images, sitemap.xml
– Dev server (Browsersync) or production host (Netlify/CND)
– External services: GitHub (repo + Actions), NPM registry (govuk-frontend), Netlify
b. Relationships & data flows:
• Developer commits → GitHub → GitHub Actions
• CI: checkout → npm install → run lint/tests → run build → on success, Netlify deploy
• Locally, npm start runs build pipeline, watches files, serves via Browsersync
• End users request HTML/CSS/JS from Netlify CDN
c. Architectural patterns & principles:
• Plugin pipeline (Metalsmith) for content transformations
• Separation of concerns: content (src/), view templates (views/), processing logic (lib/), configuration (config/), orchestration (tasks/)
• Modular bundling: Rollup for JS, Sass modules for styles, Nunjucks for templates
• CI/CD automation with GitHub Actions & Netlify
d. Key technologies/frameworks:
• Node.js, NPM
• Metalsmith + custom plugins (in lib/)
• Nunjucks templating (views/)
• Sass + PostCSS/autoprefixer (stylesheets/)
• Rollup (rollup.config.js) bundling JS components
• Browsersync (config/browsersync.js)
• Jest + Puppeteer for testing
• GitHub Actions for CI
• Netlify (netlify.toml) for deployment