Pug + SCSS pipeline

The contributor pipeline uses Node >=22.12, Pug 3.0.4, Sass 1.105.1, Chokidar 5.0.0, concurrently 10.0.6, Vite 8.3.4, and Terser 5.51.2. Built files ship alongside source so template users can skip the toolchain.

npm ci
npm run dev
npm run check

Development processes

Process	Watches	Output
Pug	.pug/.html under src/pug/	Root HTML
Sass	src/scss/	css/theme.css, css/app.css
Vite	Browser assets	Dev server at localhost:3000

Pug watches a real directory, debounces save bursts, serializes builds, and writes only changed HTML. A compilation error preserves the previous good page; a later correction rebuilds it. If one development process exits, its siblings stop.

Page sources

• src/pug/layouts/: _default.pug for dashboards, _auth.pug for auth, _error.pug for status/error pages.
• src/pug/pages/: one entry per page, with metadata and layout selection.
• src/pug/partials/: head, navigation, headers, sidebar, and script stack.
• src/pug/partials/content/: raw HTML and optional .scripts.html, .styles.html, or .post.html sidecars.

extends ../layouts/_default

block variables
  - var pageMeta = { title: 'My page', description: 'A short description.' }
  - var activePage = 'my-page.html'

block content
  include ../partials/content/my-page.html

Create the matching content fragment, add sidebar/mobile navigation in _nav-data.pug, and add any palette command separately in js/main-vanilla.js. Add page-specific libraries using block vendor_scripts before the shared browser scripts. Use block extra_head for page styles and block extra_scripts for inline page logic. Pug blocks replace defaults; restate the page variables you need.

SCSS sources

theme.scss builds the legacy theme; app.scss builds the overlay from the app/ partials. Overlay rules are scoped to body.app. Reuse --m-* design tokens and preserve @use order: later partials intentionally override earlier mobile/layout rules.

Edit source partials and rebuild; root HTML and the two generated CSS files are overwritten by the pipeline. Commit sources and outputs together. There is no Vite production bundle or runtime Node requirement.

Calendar vendor build

npm run build:vendor reads the installed FullCalendar package, minifies its global core/classic-theme scripts with Terser, and copies CSS plus the upstream license. It preserves license banners and writes only changed assets.

When upgrading FullCalendar, update the versioned paths in src/pug/pages/calendar.pug and docs, rebuild, and retire the previous vendor directory after cached old pages have expired. See build and testing for validation.