Conversation
Contributor
Author
|
has a lot of changes as this stacks on top of other PRs. If those get merged, this one can follow and it will have less changes. Until then this stays a draft PR |
5 tasks
✅ Deploy Preview for flowfuse-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dimitrieh
changed the base branch from
main
to
docs/node-red-library-into-docs
September 8, 2026 08:47
dimitrieh
force-pushed
the
docs/node-red-library-into-docs
branch
from
September 8, 2026 09:04
02d2826 to
35d1a80
Compare
dimitrieh
force-pushed
the
docs/content-collections-instead-of-sync
branch
10 times, most recently
from
September 8, 2026 11:41
b17b8c5 to
68a3cb7
Compare
dimitrieh
marked this pull request as ready for review
September 8, 2026 15:23
Contributor
Author
|
@ZJvandeWeg can you have a look here? This essentially fixes your request at #5495 (comment) |
dimitrieh
force-pushed
the
docs/content-collections-instead-of-sync
branch
from
September 15, 2026 11:38
51dbb2e to
2063535
Compare
A reviewer on #5495 asked why docs-sync/guides-sync materialize files into nuxt/content/docs by hand instead of using @nuxt/content's own collection primitives. Checked against the installed @nuxt/content (3.15.2, satisfies the ^3.13.0 this repo pins): a collection's `source` can be an array, each entry with its own `cwd`, and each is globbed and parsed independently at build time. That is enough for the guides authored in nuxt/content-guides/, since they are already MDC and already local: the `docs` collection now reads them straight from that directory as a second source (prefixed onto `docs/` so they land at the same paths), and the `content:file:beforeParse` hook that already existed for the blog collection now also stamps guide pages with their editUrl/updated frontmatter, in place of a copy step that used to write it into a duplicated file. guides-sync.mjs is what is left after that: copying the guides' non-markdown assets to public/docs (a content-collection source cannot do that), and a proactive collision check against FlowFuse/flowfuse's pages (a real collision now fails anyway, since the `docs` collection's `id` is a primary key, but as a SQL error rather than a message naming the file). The section-index README.md convention the guides borrowed from GitHub is renamed to index.md throughout, since @nuxt/content only special-cases the latter and this tree is ours to rename. docs-sync.mjs (the FlowFuse/flowfuse clone) is unchanged: its full-history clone can't become @nuxt/content's own git source, which only supports a shallow clone and would flatten every page's `updated` date to the sync commit - the reason the clone is not shallow already, predating this change. core-nodes-sync.mjs is unchanged for the same reason it was never a candidate: its input is an HTTP fetch, not files on disk, so it still writes into nuxt/content/docs like a build artifact, because it is one. Verified the source/prefix mechanics against @nuxt/content's own module code (resolveSource, defineLocalSource, the collection build loop) and with a standalone experiment reproducing the exact id/path computation for both sources - not just theoretically, but with real @nuxt/content code executed against toy directories, confirming the guides source resolves to the same /docs/... paths the old copy step produced. nuxt/lib/guides-sync.test.mjs is rewritten for the slimmed-down API.
dimitrieh
force-pushed
the
docs/content-collections-instead-of-sync
branch
from
September 25, 2026 19:56
2063535 to
fbd5d63
Compare
Contributor
Author
|
FYI: the failing build here isn't caused by this PR. Tracked in https://github.com/FlowFuse/engineering/issues/460. It's resolved now, re-running the checks. |
Dropping the copy step took the guides out of the only path remark-docs-links recognised. It keys off a `/docs/` segment in the file's path on disk, which held while guides-sync materialized them into nuxt/content/docs, and stops holding now they are read straight out of nuxt/content-guides/. The plugin returned early on every guide page, so their relative image URLs reached the browser unresolved and the browser resolved them against the page's own URL: ./images/x.png on /docs/node-red/database/influxdb/ asked for /docs/node-red/database/influxdb/images/x.png and 404'd. The asset was copied to the right place throughout; only the URL was wrong. Three hundred-odd references across 33 pages, and nothing failed: the link checker sees the built HTML, where these are valid relative URLs, and the images themselves are not fetched. The path mapping moves to nuxt/lib so node --test can reach it, and it now understands both of the collection's sources. The test asserts over the real tree that every guide using a relative asset URL is one this can resolve, so the two cannot drift apart again without failing.
dimitrieh
force-pushed
the
docs/content-collections-instead-of-sync
branch
from
September 25, 2026 20:06
fbd5d63 to
ddb9c47
Compare
Contributor
Author
|
Preview affected pages:
Every guide page under these four sections is now read from |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A reviewer asked on #5495 (comment) why the docs pipeline uses a custom sync script instead of
@nuxt/content's own collection primitives. This checks that against the installed version (3.15.2) and applies it where it genuinely helps.The guides overlay (
nuxt/content-guides/) is now a second source on thedocscollection, read directly from disk instead of being copied intonuxt/content/docsfirst. The frontmatter it used to inject during that copy now happens in the existingcontent:file:beforeParsehook.nuxt/content-guides/)docs-sync.mjs)core-nodes-sync.mjs)The other two sources stay as they are:
docs-sync.mjsneeds the full git history of each file it clones (for the "updated" date).@nuxt/content's own git source only does a shallow clone, which would date every page the same.core-nodes-sync.mjsgenerates pages from an HTTP fetch, not files on disk, so there is nothing to point a collection source at.Also renamed the guides'
README.mdsection-index files toindex.md, since@nuxt/contentonly recognizes the latter.What this does not solve: two of the three sync scripts are unchanged.
scripts/sync_docs.mjs(used outside a Nuxt build) no longer copies guide pages intonuxt/content/docs, only their non-markdown assets.Related Issue(s)
#5495 (comment)
Checklist