Merge remote-tracking branch 'origin/main' into 4973-nuxt-migration

Author: n-lark

.claude/CLAUDE.md

@@ -1,25 +1,45 @@
 # FlowFuse Website — Codebase Guide
 
-## Stack
+## Architecture (Nuxt-first, 11ty being phased out)
 
-- **SSG**: Eleventy (11ty) v3, source in `src/`, output to `_site/`
-- **CSS**: Tailwind v3 via PostCSS → `_site/css/style.css`
-- **Templates**: Nunjucks (`.njk`) + Markdown
+The site is migrating from Eleventy (11ty) to Nuxt 3. Nuxt is the primary framework going forward; 11ty is being phased out section by section using a strangler-fig pattern.
+
+- **Primary framework**: Nuxt 3 (`nuxt/`) with `@nuxt/content` v3 for content-driven pages
+- **Legacy SSG**: Eleventy (11ty) v3, source in `src/`, output to `_site/` — being phased out
+- **Strategy**: Nuxt is the front door. In dev, Nuxt proxies un-migrated routes to 11ty (port 8080). In production, `nuxt generate` produces the final output.
+- **CSS**: Tailwind v3 via PostCSS → `_site/css/style.css` (shared between both)
+- **Templates (legacy)**: Nunjucks (`.njk`) + Markdown (11ty only)
 - **Search**: Algolia (`scripts/index-algolia.js`)
-- **Hosting**: Netlify; publish dir = `_site`
-- **Nuxt migration**: parallel Nuxt 3 project lives in `nuxt/` (see [nuxt/CLAUDE.md](nuxt/CLAUDE.md))
+- **Hosting**: Netlify; final output from `nuxt generate`
+
+### Migration status
+
+| Section | Status |
+|---------|--------|
+| `/handbook/**` | **Migrated** — served by Nuxt (`nuxt/content/handbook/`) |
+| All other routes | Still on 11ty, proxied through Nuxt in dev |
+
+### Production build order
+
+```
+clean:nuxt → build:js:nuxt → prod:postcss-nuxt → prod:eleventy-nuxt → prod:nuxt
+```
+
+11ty outputs to `nuxt/public/` so Nuxt can serve 11ty-generated assets. `nuxt/public/` is gitignored (fully build-generated).
 
 ## Dev commands
 
 ```bash
 npm start              # all watchers in parallel (11ty + nuxt + postcss + docs + blueprints)
 npm run dev            # eleventy + postcss + nuxt only
-npm run dev:eleventy   # 11ty only, port 8080
-npm run dev:nuxt       # Nuxt only, port 3000/3001
+npm run dev:eleventy   # 11ty only, port 8080 (legacy; most work doesn't need this)
+npm run dev:nuxt       # Nuxt only, port 3000 — use this for handbook and migrated pages
 npm run docs           # sync docs from external source once
 npm run build          # production build
 ```
 
+> When working on the handbook or other migrated sections, `npm run dev:nuxt` is sufficient. `npm start` is only needed when also touching 11ty-served pages.
+
 ## Directory layout
 
 ```
@@ -104,19 +124,26 @@ Each year has a `src/changelog/YYYY/YYYY.json` that tags the collection.
 
 ### Handbook pages
 
-**Source:** `src/handbook/{department}/{slug}.md`  
+**Source:** `nuxt/content/handbook/{department}/{slug}.md` ← edit here  
 **URL:** `/handbook/{department}/{slug}/`  
-**Layout:** `layouts/documentation.njk` (shared with docs)
+**Rendered by:** Nuxt — `nuxt/pages/handbook/[...slug].vue` + `HandbookLeftNav` component
 
 ```yaml
 ---
-navTitle: "Title shown in sidebar nav"
-navGroup: "Optional group heading"
+title: "Page title (shown in browser tab and sidebar nav)"
+navigation:            # optional — only needed on top-level section index.md files
+  group: "Company"     # groups this section under a heading in the left nav
 ---
 ```
 
+**Fields:**
+- `title` — required; used as the page title and sidebar nav label
+- `navigation.group` — only set on top-level section `index.md` files to group sections in the left nav (e.g. "Company", "Engineering & Design Practices", "Internal Operations", "Sales department")
+
+**Nav grouping:** `nuxt/composables/useHandbookNav.ts` reads all pages via `queryCollection('handbook').all()` and builds the sidebar tree. The `navigation.group` on each section's `index.md` controls which sidebar group the section appears under.
+
 Department folders: `company/`, `design/`, `engineering/`, `marketing/`, `operations/`, `peopleops/`, `sales/`  
-Collection config: `src/handbook/handbook.json`
+Collection config: `nuxt/content.config.ts` (defines the `handbook` collection)
 
 ---
 

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "eleventy",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev:eleventy"],
+      "port": 8080
+    }
+  ]
+}

.eleventy.js

@@ -221,6 +221,7 @@ module.exports = function(eleventyConfig) {
     eleventyConfig.addLayoutAlias('page', 'layouts/page.njk');
     eleventyConfig.addLayoutAlias('nohero', 'layouts/nohero.njk');
     eleventyConfig.addLayoutAlias('solution', 'layouts/solution.njk');
+    eleventyConfig.addLayoutAlias('use-case', 'layouts/use-case.njk');
     eleventyConfig.addLayoutAlias('catalog', 'layouts/catalog.njk');
     eleventyConfig.addLayoutAlias('redirect', 'layouts/redirect.njk');
 
@@ -531,12 +532,13 @@ module.exports = function(eleventyConfig) {
         return new URL(url, site.baseURL).href;
     })
 
+
     eleventyConfig.addFilter("handbookBreadcrumbs", (url) => {
         let parts = url.split("/").filter(e => e !== '');
         if (parts[parts.length-1] === "index") {
             parts.pop();
         }
-        
+
         let path = "";
         return "/"+parts.map(p => {
             let url = `${path}/${p}`;
@@ -546,24 +548,16 @@ module.exports = function(eleventyConfig) {
     });
 
     eleventyConfig.addFilter("rewriteHandbookLinks", (str, page) => {
-        // If page.inputPath looks like: ./src/handbook/abc/def.md
-        // then the url of the page will be `/handbook/abc/def/`
-        // links of the form `./` or `[^/]` must be prepended with `../`
-        // to ensure it links to the right place
-
         const isIndexPage = /(README.md|index.md)$/i.test(page.inputPath)
 
         const matcher = /((href|src)="([^"]*))"/g
         let match
         while ((match = matcher.exec(str)) !== null) {
             let url = match[3]
             if (/^(http|#|mailto:)/.test(url)) {
-                // Do not rewrite absolute urls, in-page anchors or emails
                 continue
             }
-            // */abc.md#anchor => */abc/#anchor
             url = url.replace(/.md(#.*)?$/, '$1')
-            // */README#anchor => */#anchor
             url = url.replace(/README(#.*)?$/, '$1')
             if (url[0] !== '/' && !isIndexPage) {
                 url = '../'+url
@@ -922,7 +916,7 @@ module.exports = function(eleventyConfig) {
     // Inject tier badges into docs pages: parent feature after H1, subfeatures after their headings
     eleventyConfig.addTransform("docsFeatureBadges", function(content) {
         if (!this.page.outputPath || !this.page.outputPath.endsWith(".html")) return content;
-        if (!this.page.url || !/^(\/docs\/|\/node-red\/|\/handbook\/)/.test(this.page.url)) return content;
+        if (!this.page.url || !/^(\/docs\/|\/node-red\/)/.test(this.page.url)) return content;
 
         const parentFeature = findFeatureByDocsLink(this.page.url);
         const subfeatures = findSubfeaturesForDocsPage(this.page.url);
@@ -1109,7 +1103,6 @@ module.exports = function(eleventyConfig) {
     eleventyConfig.addCollection('nav', function(collection) {
         let nav = {}
 
-        createNav('handbook')
         createNav('docs')
 
         function createNav(tag) {
@@ -1140,7 +1133,7 @@ module.exports = function(eleventyConfig) {
                 // recursively parse the folder hierarchy and created our collection object
                 // pass nav = {} as the first accumulator - build up hierarchy map of TOC
                 hierarchy.reduce((accumulator, currentValue, i) => {
-                    // create a nested object detailing the full handbook hierarchy
+                    // create a nested object detailing the full docs hierarchy
                     if (!accumulator[currentValue]) {
                         accumulator[currentValue] = {
                             'name': currentValue,
@@ -1191,7 +1184,6 @@ module.exports = function(eleventyConfig) {
                 }
             }
 
-            // not req'd to have handbook in Website build, so this may be empty
             if (nav[tag]) {
                 for (child of nav[tag].children) {
                     if (child.group) {
@@ -1205,7 +1197,7 @@ module.exports = function(eleventyConfig) {
                         }
                         groups[group].children.push(child)
                     } else {
-                        // capture & flag top-level handbook docs, that haven't had a group assigned
+                        // capture & flag top-level docs that haven't had a group assigned
                         groups['Other'].children.push(child)
                     }
                 }

.github/workflows/build.yml

@@ -13,11 +13,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out website repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           path: 'website'
       - name: Check out FlowFuse/flowfuse repository (to access the docs)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           repository: 'FlowFuse/flowfuse'
           ref: main
@@ -30,7 +30,7 @@ jobs:
           private-key: ${{ secrets.GH_BOT_APP_KEY }}
           owner: ${{ github.repository_owner }}
       - name: Check out FlowFuse/blueprint-library repository (to access the blueprints)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           repository: 'FlowFuse/blueprint-library'
           ref: main

.github/workflows/calibreapp-image-actions.yml

@@ -16,7 +16,7 @@ jobs:
     if: github.repository == 'FlowFuse/website' && github.event.pull_request.head.repo.full_name == github.repository
     steps:
       - name: Checkout Branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Compress Images
         id: calibre
         uses: calibreapp/image-actions@9d037c06280028c110ff61c433ad4dc7d33c3c43 # 1.5.0
@@ -25,3 +25,4 @@ jobs:
           # For non-Pull Requests, run in compressOnly mode and we'll PR after.
           compressOnly: ${{ github.event_name != 'pull_request' }}
           pngQuality: '100'
+          ignorePaths: 'nuxt/**'

.github/workflows/handbook-changes-notify.yaml

@@ -17,7 +17,7 @@ jobs:
       handbook_has_been_updated: ${{ steps.changed-files.outputs.handbook_changed }}
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
       - name: Find changed files
@@ -35,7 +35,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         fetch-depth: 0
     - name: Generate URLs

.github/workflows/test.yml

@@ -18,19 +18,19 @@ jobs:
             flowfuse
             blueprint-library
       - name: Check out website repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           path: 'website'
           token: ${{ steps.generate_token.outputs.token }}
       - name: Check out FlowFuse/flowfuse repository (to access the docs)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           repository: 'FlowFuse/flowfuse'
           ref: main
           path: 'flowfuse'
           token: ${{ steps.generate_token.outputs.token }}
       - name: Check out FlowFuse/blueprint-library repository (to access the blueprints)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           repository: 'FlowFuse/blueprint-library'
           ref: main
@@ -51,3 +51,7 @@ jobs:
       - name: Build the forge
         run: npm run build:nuxt:skip-images
         working-directory: 'website'
+      - name: Check links
+        uses: untitaker/hyperlink@fb5bb9c5011a3d143a54b4b30aedc30ec5bc0f89 # 0.2.0
+        with:
+          args: website/nuxt/dist/ --check-anchors --sources website/src

README.md

@@ -67,6 +67,12 @@ This starts three watchers concurrently:
 
 **Note**: the first time running this, 11ty may take a little while to process all images in the `/docs` and `/handbook` folders.
 
+**Note**: if you have previously run `npm run build:nuxt`, clean the generated directories before starting dev or you will get a `spawn EBADF` error:
+
+```bash
+npm run clean:nuxt
+```
+
 ### Legacy-only mode
 
 To run just the legacy 11ty stack (equivalent to the old `npm start`):

netlify.toml

@@ -1,8 +1,8 @@
 [[headers]]
   for = "/*"
   [headers.values]
-    X-Frame-Options = "DENY"
-    Content-Security-Policy = "frame-ancestors 'none';"
+    X-Frame-Options = "SAMEORIGIN"
+    Content-Security-Policy = "frame-ancestors 'self';"
 
 [[redirects]]
 from = "http://flowforge.com/*"
@@ -66,7 +66,15 @@ autoLaunch = false
 
 [build]
 command = "npm run build:nuxt"
-publish = "nuxt/.output/public"
+publish = "nuxt/dist"
+
+[functions]
+directory = "nuxt/.netlify/functions-internal"
+
+[[redirects]]
+from = "/*"
+to = "/.netlify/functions/server"
+status = 200
 
 [context.deploy-preview]
 command = "npm run build:nuxt"

nuxt/.env.example

@@ -0,0 +1,5 @@
+# Nuxt Studio — GitHub OAuth
+# Create at: GitHub → Settings → Developer settings → OAuth Apps
+# Callback URL: https://your-domain.com/_studio/auth/github/callback
+STUDIO_GITHUB_CLIENT_ID=
+STUDIO_GITHUB_CLIENT_SECRET=