Make the Application Guide part of the documentation - #5745
Open
dimitrieh wants to merge 3 commits into
Open
Conversation
/docs is now assembled from two repos instead of one. FlowFuse/flowfuse keeps the product documentation, and the Application Guide keeps being authored here, but the two are published as a single documentation set. Why the split falls where it does. Diataxis separates material that serves work from material that serves study. The flowfuse docs/ tree is how-to and reference: install on Kubernetes, what an env var does. It changes when the product changes, so it belongs next to the code it describes and is versioned with it. The Application Guide is explanation: what shapes an app can take, why a server sits in OT rather than IT, what good form looks like in a flow. It is read away from the work and changes when our understanding changes, not when a release ships. Two repos matches the two release cadences. What was wrong was not the split but the seam. The guide lived in its own URL space with its own sidebar, its own breadcrumb root and its own Algolia category, so a reader at work in /docs never met it, and a reader studying the guide could not step across into the how-to it prepares them for. Mechanically, nuxt/lib/guides-sync.mjs overlays nuxt/content-guides/ onto nuxt/content/docs after docs-sync has populated it (that order matters, since docs-sync wipes the tree before writing). @nuxt/content therefore sees one `docs` collection, and the sidebar builder, page route, breadcrumbs, TOC, prerender list, sitemap and search treat both sources identically. A guide landing on a path the product docs already occupy fails the build rather than silently replacing that page. Consequences worth naming: - Nothing changes in FlowFuse/flowfuse. The new sidebar group ranks itself with navGroupOrder 0, so no existing group had to be renumbered. - "Edit this page" resolves per source repo: pages carry either `originalPath` (flowfuse) or `editUrl` (here). The split stays invisible to readers and correct for contributors. - The guides gain what /docs already had: docs search, a TOC, git-derived lastmod in the sitemap, and prerendering off one route list. - Flat `parent:` nesting becomes real directory nesting, which is what the docs nav and breadcrumbs derive structure from. That deletes the bespoke parent-walking breadcrumb helper, the two guide page routes, the applicationGuideDoc collection and its prerender collector. - Every previously published URL 301s to its new home, and the handbook, the header/footer nav and llms.txt point at the new ones.
Contributor
Author
|
Reading a product doc (
A guide page itself, now in the docs frame (search, breadcrumb, TOC,
|
✅ Deploy Preview for flowforge-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
Author
Contributor
Author
|
Still in progress, but can already give a view/indication |
…column Both boxes widened themselves by a negative right margin sized to the width of the right-hand column, on the stated assumption that guide pages had no table of contents. Guide pages are docs pages now, and that column holds a real TOC, so the widened box ran underneath it. It looked wrong before this move too: the box was ~1024px while the prose around it was ~710px, so the tab strip and any flow diagram visibly overhung the text on both sides. The FlowDiagram rule had a second problem. It was unscoped and keyed on .ag-diagram, a class ArchDiagram also uses, but it shipped in FlowDiagram's own style block. So an arch diagram widened only when a flow diagram happened to be on the same page and pulled that stylesheet in, which is why the guide's diagrams were inconsistently sized page to page. Both now follow the content column. The diagrams are SVG and scale to whatever width they are given, so nothing is clipped at the narrower size.
Eight of the twelve docs sections were missing from the sidebar's grouping:
admin, cloud, contribute, device-agent, hardware, install, migration and user.
They appeared under a catch-all "Other" heading, titled by raw path segment
("user", "admin"), and the Device Agent, FlowFuse Cloud and Contributing groups
came out empty and were filtered away, so they did not render at all.
The cause: each of those section index pages is a `layout: redirect` stub
pointing at the section's introduction page, and buildDocsNav dropped every
page carrying `redirect`. Dropping them was right as far as linking goes -
a sidebar entry pointing at a URL that 301s makes nuxt-link-checker's
`redirects` inspection flag every docs page - but it also threw away the
navGroup, navGroupOrder, navTitle and navOrder those pages carry. With the
index gone, the section node was built only from the paths of its children,
which have no group of their own.
So the frontmatter is kept and applied to the node the children create, and
only the link is withheld. `link: false` marks such a node as a label rather
than a destination; navigationMenu omits `to` for it. The node keeps its own
path, which is what the menu's auto-expand and the breadcrumb trail match on,
so both now work through a stubbed section and breadcrumbs read "Using
FlowFuse" rather than "user".
A stub with no pages beneath it still contributes nothing, so leaf redirects
like docs/community-support.md do not become dead, unclickable labels.
This is a fix to the nav builder only. Every group name, order and title it now
honours was already declared in FlowFuse/flowfuse; nothing changes there.
Contributor
Author
|
Two follow-up fixes, both green. Sidebar grouping. 8 of 12 docs sections were missing from grouping: their index page is a
Tab / diagram width. Both widened themselves by a negative right margin sized to the right-hand column, assuming guide pages had no TOC. They are docs pages now, so that ran under the TOC; it also made the box ~1024px against ~710px of prose. The FlowDiagram rule was additionally unscoped and keyed on
|
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
/docsis now assembled from two repos. FlowFuse/flowfuse keeps the product docs (how-to and reference, versioned with the code); the Application Guide keeps being authored here (explanation, which changes when our understanding changes, not when a release ships).nuxt/lib/guides-sync.mjsoverlaysnuxt/content-guides/onto the docs content tree afterdocs-syncpopulates it, so @nuxt/content sees onedocscollection and the sidebar, breadcrumbs, TOC, search, sitemap and prerendering treat both sources identically. Nothing changes in FlowFuse/flowfuse.The guide moves from
/application-guide/{guide}/{slug}/to/docs/application-guide/**and/docs/node-red-guide/**, every old URL 301s, and "Edit this page" resolves to whichever repo owns the page.One call for the reviewer: the new sidebar group sits first, above "FlowFuse User Manuals" (
navGroupOrder: 0, chosen so no existing group needed renumbering in the other repo). Happy to drop it lower if the manuals should stay top.Related Issue(s)
None.
Checklist