Repository navigation
README out of date with build instructions #5432
Description
Description
PR #5177 changed how the website incorporates docs from the flowfuse/flowfuse repo. There are some outstanding problems:
.claude/CLAUDE.md was updated with information about the new process - but README.md was not updated and contains out of date information.
Specifically, the fact it now clones the ff repo by default rather than use a local copy of the docs without manual intervention. This has broken the FF repo build that verifies doc changes.
It has also added docs to CLAUDE.md about an npm task called dev:nuxt. This task doesn't exist.
It has also removed the ability to watch the docs for changes and trigger automatic rebuild - was previously the npm run dev:docs task. When working on product docs, I now have to manually restart the website build every time and wait for it to complete.
I also find I'm routinely hitting nuxt/nuxt#35253 due to the version of nuxt we are using.
In addition to knowing about the FLOWFUSE_DOCS_LOCAL env var, I also have to set TMPDIR=/tmp to workaround that nuxt issue.
Epic/Story
No response
Have you provided an initial effort estimate for this issue?
I have provided an initial effort estimate
Activity
dimitrieh commentedon Aug 3, 2026
Created two PR's to speed this up/take some work out of the hands of engineers ideally (should be merged in order):
Checking CI as we speak
dimitrieh commentedon Aug 4, 2026
Two remaining asks:
dimitrieh commentedon Aug 4, 2026
Status on the items raised here.
Addressed:
FLOWFUSE_DOCS_LOCAL, then a sibling checkout, then a clone) and which one CI relies on.needsback on the publish job, so a docs merge with a broken link no longer triggers a website rebuild. Confirmed the link check does fail on a broken internal link rather than passing everything.dev:nuxtdocumented but missing: the task exists inpackage.json.TMPDIR=/tmp: now set innuxt/package.json.Open, with a PR up:
scripts/watch_docs.mjsand adev:docstask, wired intodev, so editing docs in a local checkout re-syncs without restarting the dev server. It reuses the same source resolution as the build, and no-ops when the docs come from a clone. An edit to an existing page and a newly added page both reachednuxt/content/docswithin a second in testing.One open question on that PR:
writeDocs()removes and recreates the wholecontent/docstree on each sync, and how @nuxt/content's dev watcher handles that on the full docs tree is unverified. If it churns, the fix is a single-file path throughcopyDocsDir.