This repository contains the source of the FlowFuse website.
It is hosted on Netlify, which watches the main branch directly and deploys on every commit to it.
Netlify's own build resolves everything it needs at build time — product documentation from main of
FlowFuse/flowfuse, and blueprints from
FlowFuse/blueprint-library (see npm run blueprints /
nuxt/lib/blueprints-sync.mjs) — so nothing needs to be pre-fetched and committed to a separate branch first.
A commit to flowfuse/flowfuse or blueprint-library doesn't push anything to this repo, so it wouldn't otherwise
trigger a Netlify rebuild on its own. The Build Site action covers that gap: it's
dispatched by flowfuse/flowfuse's Publish Documentation workflow after a docs PR merges, and also runs on a
schedule to pick up blueprint-library changes — either way it just calls a Netlify build hook to rebuild main.
This repository is an npm workspace. The whole site is one Nuxt 4 application in nuxt/:
| Directory | Purpose |
|---|---|
nuxt/pages, nuxt/components |
Routes and the components they render |
nuxt/content |
Markdown and YAML content, read through @nuxt/content |
nuxt/public |
Everything served as a file: images, downloads, favicons |
nuxt/data |
JSON and YAML that components import directly (the nav, the team, site config) |
nuxt/assets |
Stylesheets, the two icon sets (icons/ for <UIcon>, nav-icons/ for <NavIcon>), the cookie-consent source |
nuxt/lib, nuxt/server/lib |
Plain-JS helpers with node --test unit tests |
scripts/ |
Build-time syncs for the two external content sources, and the Algolia indexer |
| (root) | The workspace: npm scripts, Tailwind and PostCSS config, Netlify config |
The site was previously generated by Eleventy and was migrated to Nuxt
page group by page group, using the Strangler Fig pattern.
That migration is complete and Eleventy is gone; a .njk file or a src/ path in a comment
is a reference to what a page used to be.
gitandgitbash(download)nodejs(download)- IMPORTANT: Select the [x] checkbox to install developer tools when asked
choco- Installed as part of the Node JS installer
- Needed for installing
jq
jq(download)- From a administrator terminal, run
choco install jq
- From a administrator terminal, run
Clone the repository, then install all dependencies (workspace packages are included automatically):
npm installnpm run devThe site is then on http://localhost:3000. That one command starts everything:
| Process | Description |
|---|---|
| Nuxt dev server | The site, on port 3000 |
| PostCSS watcher | Compiles Tailwind CSS into nuxt/public/css |
| Docs watcher | Re-syncs a product-docs page as it changes (see below) |
| Blueprints watcher | Re-syncs the Blueprint Library when the sibling checkout changes |
npm run dev:nuxt runs the Nuxt server on its own, without the watchers.
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:
npm run clean:nuxtThe documentation for FlowFuse is maintained in the core FlowFuse repo. To run a local version of the documentation, clone that repository alongside this one:
/<parent_directory>
/website
/flowfuse
npm run dev will retrieve the documentation from that folder and inject it into the site automatically. The docs will be available at http://localhost:3000/docs.
Nothing needs configuring for that to happen. Every build resolves the docs in this order, and logs which one it used:
| Order | Source | Used when |
|---|---|---|
| 1 | FLOWFUSE_DOCS_LOCAL=/path/to/flowfuse |
The env var is set. A path that does not exist is an error, not a fallback. |
| 2 | A sibling checkout: ../flowfuse, ../flowforge or ../dev-env/packages/flowfuse |
One of those has a docs/ directory. This is what CI relies on. |
| 3 | A clone of FLOWFUSE_DOCS_REF (default main) |
Nothing above applied. This is what Netlify production deploys use. |
npm run docs runs that resolution on its own, without a full build, writing nuxt/content/docs and nuxt/public/docs. Both are generated, and neither is committed on main.
npm run dev also watches the resolved docs and re-syncs each file as it changes, so an edit appears without restarting. npm run dev:nuxt on its own does not include that watcher; run npm run dev:docs beside it if you want one.
Blueprints are maintained in the (private) FlowFuse/blueprint-library repo. To work with them locally, clone that repository alongside this one, the same way as flowfuse above:
/<parent_directory>
/website
/blueprint-library
Every build resolves blueprints in this order, and logs which one it used:
| Order | Source | Used when |
|---|---|---|
| 1 | FLOWFUSE_BLUEPRINTS_LOCAL=/path/to/blueprint-library |
The env var is set. A path that does not exist is an error, not a fallback. |
| 2 | A sibling checkout: ../blueprint-library |
It exists. This is what local development relies on. |
| 3 | A clone, authenticated with a minted GitHub App installation token (GH_BOT_APP_ID/GH_BOT_APP_KEY) |
Nothing above applied, and those env vars are set. This is what Netlify production deploys use — blueprint-library is private, so this can't clone anonymously the way docs does. |
| 4 | Skipped | Nothing above applied. Matches the previous behaviour for contributors without access to the private repo. |
npm run blueprints runs that resolution on its own, writing nuxt/content/blueprints and nuxt/public/blueprints, both gitignored. npm run dev re-runs it whenever the resolved source changes (scripts/watch_blueprints.js), but only when it found a source to watch in the first place — no sibling checkout means no watching.
/llms.txt (and /llms-full.txt) are generated by the nuxt-llms module, configured in nuxt/nuxt.config.ts under the llms key. Sections are built from @nuxt/content collections (docs, blog, changelog, ebooks, whitepapers) plus a small hardcoded list of standalone Nuxt routes (pricing, integrations, etc.) that aren't backed by a collection.
The handbook collection is deliberately excluded: it's internal company documentation, not product content, so it has no contentCollection section here.
See the Blog section of the Marketing Handbook for instructions on writing and publishing blog posts.
When the website is built it will include the documentation
from the main branch of the FlowFuse/flowfuse
repository.
To make a documentation update and make it live on the website:
- PR the documentation update to the
mainbranch of FlowFuse/flowfuse - Get the PR reviewed and merged in the normal manner.
That repository's Publish Documentation workflow builds this site against the PR's docs before it can merge, then
triggers a website rebuild once it lands. A rebuild can also be started by hand with 'Run workflow' on
this page.
This setup was inspired by: