Deployment

npm Scripts

Script	Purpose
npm run dev	Development server with hot reload
npm run build	Production build (minified CSS)
npm run clean	Remove dist/ directory

GitHub Pages

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - run: npm ci
      - run: npm run build

      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: "./dist"

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: $
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Path Prefix

For project sites (username.github.io/repo-name), set path prefix in eleventy.config.js:

return {
  pathPrefix: process.env.GITHUB_ACTIONS ? "/repo-name/" : "/",
};

Custom Domain

1. Add a CNAME file to src/ with your domain
2. Add passthrough copy: eleventyConfig.addPassthroughCopy("src/CNAME")
3. Configure DNS to point to GitHub Pages

Build Verification

Before deploying, verify locally:

# Clean build
npm run clean && npm run build

# Serve the dist folder
npx serve dist

Maintenance

Guidance for keeping your site up to date.

Updating Dependencies

Check for outdated packages:

npm outdated

Update to latest compatible versions:

npm update

For major version upgrades, update package.json manually and test thoroughly. Pay special attention to:

• Eleventy — Check the release blog for breaking changes
• Tailwind CSS — Review the upgrade guide for migration steps
• Stimulus — Generally backwards compatible; check release notes

Content Updates

Content lives in src/. Common tasks:

Task	Where
Edit page content	src/*.njk or src/**/*.md
Update site metadata	src/_data/site.json
Change navigation	src/_data/sections.json
Modify layouts	src/_includes/layouts/
Update partials	src/_includes/partials/
Adjust styling	src/assets/css/main.css

Adding Pages

1. Create a new .njk or .md file in src/
2. Add frontmatter with layout, title, and description
3. Add to sections.json if it should appear in navigation
4. Update prev/next links on adjacent pages if using chapter navigation

Adding Controllers

1. Create src/assets/js/controllers/your_controller.js
2. Register in application.js:

   import YourController from "./controllers/your_controller.js";
   application.register("your", YourController);

3. Use in templates: data-controller="your"

Troubleshooting

Issue	Solution
CSS not updating	Run npm run clean and rebuild
Search not finding content	Rebuild to regenerate Pagefind index
Build fails	Check for Nunjucks syntax errors in templates
Controller not working	Verify registration in application.js
Styles missing in production	Ensure classes are in @source paths in main.css