Conversation
2 of 11 tasks
dimitrieh
marked this pull request as draft
September 25, 2026 15:31
✅ Deploy Preview for flowfuse-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
Author
dimitrieh
changed the title
dimitrieh
requested review from
KristopherLeads,
ZJvandeWeg,
dgatti0213 and
robmarcer
September 25, 2026 16:11
Contributor
Author
|
@dgatti0213 @KristopherLeads @robmarcer @ZJvandeWeg this is the tip of the iceberg for restructuring changes to docs, starting with the homepage, plus it brings back the FlowFuse expert on the website as a AI docs support agent. For now, can you have a look around on the homepage and see how this makes sense to you? A quick recording in which you share your thoughts would also work. Thanks 🙏 Slack thread: https://flowfuse.slack.com/archives/C09QS57R8AD/p1790348670427239 |
Contributor
Author
|
@Steve-Mcl can you have a look around here as well and see what we might want to do on the BE side for the expert to make this expert up to date and ensure it has the right access, plus includes understanding of the application guide (see docs: https://FlowFuse.com/docs/application-guide |
Contributor
|
Hey @dimitrieh, looking good! Would you be open to removing the “Docs” next to the FlowFuse logo? Or maybe making it much smaller, like a superscript? It feels a bit too visually heavy as it is, especially since it appears on every docs page. |
Contributor
Author
|
100% agreed it is not ideal yet. As the page shifted from being a default docs page to a more docs landing page, I wanted it to be more clear that in fact you are now at the docs portal. I'll try out some variations. I have some more work to do in regards to docs beyond this PR, so will take a holistic approach for it |
dimitrieh
force-pushed
the
docs/home-landing
branch
from
September 29, 2026 12:22
a4c5655 to
7e65445
Compare
dimitrieh
changed the title
Contributor
Author
|
"Docs" is now a small superscript beside the logo: 13px, grey, its capital level with the top of the wordmark. Before: After: @Yndira-E scoped the ask FlowFuse out for now. Don't like the "docs" setting yet. Would you have a proposal or want to take a spin at it? This PR still needs a deeper content review. Getting to that later in the week |
5 tasks
The group name rendered at caption size, the same weight as the pages under it, so the grouping had to be read rather than seen. It now takes body size and the links sit indented from it. Shared component, so this applies to the handbook and the guides too.
…op the lone crumb The sidebar started 1.5rem above the page body, so nothing lined up across the top. Its items sit indented further from their group header. A breadcrumb trail of one item names the page you are already on. It now renders only when there is somewhere to go back to.
FfExpertAsk carries the markup of the old /ai/ page's chat interface and modal and runs the same src/js/ai-expert-modal.js. The script now starts through a named init that runs whether or not DOMContentLoaded has fired, can run again after client-side navigation, and replaces its page-wide click listeners instead of stacking them. Answers come from the Expert service for the hosted site; in a local preview the request fails, as the script itself notes.
…home box The Expert conversation modal now lives once in the layout for all docs pages. The home page box carries the FlowFuse Expert branding above the text box, an Ask Docs button and support questions instead of workflow ideas. Elsewhere, and on the home page once that box scrolls away, an Ask FlowFuse Expert button at the top of the right-hand column opens the same conversation. ai-expert-modal.js: the entry button is handled by delegation so a box mounted after start-up works, the morph from the box only runs when the box opened the modal, a page can set the greeting, and window.ffExpertOpen() opens it from any button.
The docs search moves from above the article to the top of the sidebar, where the Documentation link was, and opens its results in a centred dialog (full screen on a phone). Cmd+K or Ctrl+K opens it from anywhere on a docs page. AlgoliaSearch gains opt-in detached and shortcut props, so the blog, changelog, handbook and support searches are unchanged, and results without an image no longer show a broken one.
Below lg the docs sidebar and right-hand column are folded away, so docs pages get a search button and the FlowFuse Expert button in the header, styled like the Expert button in the FlowFuse app. To keep Book a demo on one line, the Expert button shows the FlowFuse mark alone below 600px and on tablets, and the square logo holds until 520px on docs pages. Measured from 360 to 1000px: no overflow beyond what the header already allows.
…r back on the button The dialog header now reads like a plain search bar: the input sits flat above the header's divider with no box or focus ring, the search icon is grey, and Cancel is an X (still named Close for screen readers). The input's own clear button is hidden so the X is the only one. The dialog carries an ff-search-dialog class, so the blog, changelog and handbook phone dialogs are unchanged. The sidebar button lost its border to algolia-theme.css, whose #algolia-search rule outranked the component's classes; the component's rule now includes the id.
…ents /docs now shows its single Docs crumb, so every docs page opens the same way. The right-hand Expert button moves below the table of contents and reads Ask Expert with the FlowFuse mark, like the compact header button, instead of the FlowFuse wordmark. On wide screens the column is capped to the window and a long table of contents scrolls inside itself, so the button under it stays in view.
The question box and the conversation modal now render FlowFuse Expert from one DocsExpertBrand component at the modal's size; the box's was larger. When the box morphs into the modal, its brand gets its own view transition and moves up into the modal header while the rest of the box morphs into the input area as before, and back again on close. Pages without a branded box (the Eleventy /ai/ page) are unaffected.
FlowFuse Expert now has one entry point on docs pages: a round Ask Docs button in the bottom-right corner at every screen width, which steps aside while a page's own question box is on screen. The Expert buttons in the right-hand column and in the phone and tablet header are gone, so the header keeps only the docs search there. DocsExpertButton is removed with them.
The right-hand column started 22px lower than the other two because the table of contents pads its own container. It now starts where the sidebar's search field does and centres its first line the same way, so the three columns share one top line. The column also no longer reserves room for the Expert button that moved to Ask Docs.
A 1px gray-200 line separates the sticky header from the page on every page, Nuxt and Eleventy alike, since both link this stylesheet. It is a shadow rather than a border, so the header height that --ff-header-height tracks does not change.
The floating button is now white with the FlowFuse mark and a slowly turning brand-red to indigo border, as the Expert button in the FlowFuse app is. Its box matches the header's Book a demo button (40px tall, 16px text, the same padding), keeping the pill shape.
A docs page whose frontmatter sets landing: true gets the full page width: no sidebar, no table of contents, no previous and next cards, and its body is not wrapped in .prose, because every block on it styles itself. The breadcrumb stays. Three content components build such a page from markdown, next to Nuxt UI's own cards, tabs and steps: - docs-hero: heading and line, the docs search (the page's Cmd+K search, since there is no sidebar), a row of buttons from a markdown list, and an aside slot beside them. - docs-section: eyebrow, heading and one line, then the section's cards or tiles. - docs-tiles: a markdown list of links as a grid of tiles, each clickable across its whole area; the links stay plain markdown so the flowfuse link check still sees them. AlgoliaSearch gains a taller lg size for the hero. The copy-command block no longer picks up the site-wide code box inside itself on pages outside .nohero.
docs-choices and docs-choice list the ways into FlowFuse, one open at a time: each opens to a line or two on what the option is, then its next step as a button and a guide as a link. They route to the pages that already walk through setup (the Device Agent install, the AI agent picker) rather than repeating them. Each choice is a native details element sharing one name, so the browser keeps a single one open with no script. docs-columns sets two blocks side by side, two thirds and one third, stacked on phones.
A card on a landing page that opens with a paragraph holding only a link takes that link as its title, and the link covers the whole card with a hover state. This replaces Nuxt UI's to attribute, whose URL the flowfuse docs link check misreads (it autolinks the text and keeps the closing quote and brace), and which left internal card links unchecked. A #title slot cannot stand in for it: inside these wrapper components MDC attaches a nested card's #title to the wrapper and swallows the card's closing fence.
FfExpertAsk lays out its box and its prompts as a two-row grid, and the box fills the height its row gives it. DocsColumns hands its first block both rows through subgrid, so that block's box shares the top row with the second column and the two stretch to one height, with the prompts below. The row gaps match; a subgrid with a different gap spreads the difference into its rows and left the box 4px taller.
The trail on /docs would be the single word Docs, so the home page leaves it out; every other docs page, landing or not, keeps its breadcrumb.
Autocomplete loads from a CDN after the page renders, so a detached search showed nothing but its Cmd+K hint until then; on the docs home, where the field leads the hero, that read as a missing search. A stand-in button of the same size now renders with the page and gives way once autocomplete mounts, with no layout shift. A click or Cmd+K before then opens the dialog as soon as it can; the shortcut listeners are set up right away.
FfExpertAsk drops its six prompt pills, so it is the question box alone and simply fills the height it is given; DocsColumns no longer needs a subgrid to line it up with the card beside it, plain grid stretching does. A card beside the Expert box now gets the same compact padding and type as cards in a card-group, and cards that follow the two-column block keep their distance. docs-choice states the rule for its links: one main call to action and at most one secondary action.
Docs pages show Docs beside the logo, linking to the docs home while the logo still goes to the site. On wide screens it pairs with the wordmark as one lockup: capitals as tall as the wordmark's (28px) on the same baseline, lighter and grey so the brand leads. Below 1024px it pairs with the square mark. On tablets the row had no other room (the menus cannot fold into More), so on docs pages Free Trial gives way there and Book a demo keeps its margin; it stays from 1024px up and on every other page.
The gap between the sidebar search and the first group heading was Nuxt UI's label padding, meant to separate a group from the one above, plus the nav's own top padding. The first heading has no group above, so both go, and the space under the search is set so the heading's capitals start on the same line as the page title's.
Docs beside the wordmark is now Heebo 700, whose stems (4px) match the wordmark's (3.9px), at 29px, which splits Heebo's proportions against the wordmark's (capitals 0.6px taller, lowercase 0.4px shorter), on the same baseline. On docs pages the wordmark now waits for xl: between 1024 and 1280px it brought the menus within 16px of Docs, while the square mark keeps at least 45px there, 70px or more from 1100px.
Between 1280 and 1536px the docs page and the header stop at the same max width but were padded differently (the page on the left only), so the sidebar search sat 12px right of the logo. The page now mirrors the header's padding from lg up. Group headings also drop Nuxt UI's label inset, which put them 10px right of the search field: they are headings over indented links, not link text.
Below xl the docs header no longer swaps in the separate square logo, which is drawn larger and in a lighter red: it shows the wordmark itself cropped to its mark, so the logo keeps one shape, colour and size and only its lettering comes and goes. Docs stays 29px at every width, now weight 600: its stems sit just under the wordmark's, 700 read too heavy. On phones below 390px the row cannot hold the mark, Docs, search, Book a demo and the menu, so there Book a demo gives way; from 390px it fits.
Without the prompt pills the box sat in a flex row that sized it to its content, so it shrank to a narrow strip and clipped its footnote. It now grows to the column's width as well as its height.
/docs spans more than the FlowFuse/flowfuse docs: the guides and the Node-RED library come from this repo. Its home therefore lives here, as nuxt/content-guides/README.md, which guides-sync overlays as the docs index. docs-sync stops copying the README at the root of the flowfuse docs tree, which stays that repository's own readme for its docs folder; syncing it neither writes nor removes the home page. Tests cover both the dev watcher's single-file sync and a full sync. The page is the landing page built from the docs-* components, with links to other pages of this site written relative so they resolve on any host, deploy previews included.
In the docs home's list of ways in, the second link of every option now leads to the page that explains the option: about FlowFuse Cloud, the Device Agent, self-hosting, FlowFuse MCP and FlowFuse applications. The first stays the step that starts it. The AI agent option, which had only its first step, gains its about link too.
Opening another option no longer moves the home page heading or the sections below. The hero aligns its columns to the top instead of centring the heading on the list, and the list keeps the height of its tallest open option, measured once mounted and again when its width changes (each option opened in turn with transitions off, in one synchronous pass). Opening and closing an option now animate its height with a short fade, using ::details-content and interpolate-size; a browser without them opens the option immediately, and reduced motion turns the animation off.
FlowFuse Expert on the docs (the Ask Docs button, the question box on the docs home and the conversation modal) ran on src/js/ai-expert-modal.js, which the Eleventy retirement removed from main, and the endpoint that script calls no longer answers without sign-in. This PR keeps the docs home, the header and the search dialog, and Ask Docs follows separately. Removed: DocsAskFab, DocsExpertHost, DocsExpertBrand, FfExpertAsk, useDocsExpert, and DocsColumns, which only held the question box. The layout goes back to main's. The Help section on the docs home keeps its wording without the Expert sentence, and the support card joins the other three cards in a two-column group.
At the wordmark's own size (29px, weight 600) the label read as a second logo on every docs page. It is now 13px, grey, set high beside the logo with its capital level with the wordmark's, like a superscript: it still says this is the docs, without competing with the brand. The smaller label frees room on phones, so Book a demo now gives way only below 360px instead of below 390px (at 360px the row has 20px to spare). The mark-only logo below xl stays: with the whole wordmark the menus would come within about 28px of "Docs" at 1100px.
dimitrieh
added a commit
that referenced
this pull request
Oct 5, 2026
With the guides read as a collection source rather than copied in, a section index has to be named index.md, so the docs home added in #5866 follows the other guide indexes.
dimitrieh
force-pushed
the
docs/home-landing
branch
from
October 5, 2026 16:40
7e65445 to
9f91b7d
Compare
This branch has not been 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
2 participants
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
The docs home becomes a landing page owned by this repo:
nuxt/content-guides/README.md, laid out full width (no sidebar or table of contents) from newdocs-*content components. docs-sync stops copying the rootREADME.mdof FlowFuse/flowfuse, which stays that repo's own readme for its docs folder.Docs-wide changes alongside: a search dialog opened from the sidebar, the phone header or Cmd+K; a small "Docs" label beside the header logo; a grey line under the site header; and sidebar alignment fixes. Ask Docs (FlowFuse Expert on the docs) moves to a follow-up PR, because the modal script it runs on left main with the Eleventy retirement.
Related Issue(s)
Companion PR (premium support redirect): FlowFuse/flowfuse#8655
Checklist