Skip to content

docs: fix the broken links on the documentation home page and across the tree - #8491

Merged
Yndira-E merged 3 commits into
mainfrom
docs/homepage-broken-links
Sep 14, 2026
Merged

Yndira-E merged 3 commits into
mainfrom
docs/homepage-broken-links

Conversation

@dimitrieh

@dimitrieh dimitrieh commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Two mechanical link fixes. No page's content or URL changes.

1. The documentation home page had four tiles pointing at the wrong page, or at nothing.

tile went to goes to
Pipelines /docs/user/snapshots/ /docs/user/devops-pipelines/
Remote Instances /docs/user/device-groups/ /docs/device-agent/introduction/
High Availability /docs/user/device-groups/ /docs/user/high-availability/
Upgrading Teams href="" /docs/cloud/billing/#team-billing

2. 56 links across 20 pages were written as /docs/user/snapshots.md rather than
/docs/user/snapshots/. The docs site has no .md routes, so every one of them 404s today.

The rest of the detail

Also on the home page

  • Managing Teams carried Custom Domains' description.
  • Community Support has a page and a nav entry but was never linked from here. It now sits
    alongside Troubleshooting and Cloud Support.
  • The four FlowFuse Nodes links were absolute URLs into /node-red/flowfuse/, which the
    website now 301s into /docs/flowfuse-nodes/. They point at the destination directly.

On the .md links

Verified against production before and after:

$ curl -o /dev/null -w '%{http_code}' https://flowfuse.com/docs/user/snapshots.md
404
$ curl -o /dev/null -w '%{http_code}' https://flowfuse.com/docs/user/snapshots/
200

README.md and index.md resolve to their directory rather than to a /README/ path, and
anchors are preserved. Every /docs/ link in the tree, markdown and HTML, now resolves to a
file that exists.

Why the FlowFuse Nodes links stayed absolute

test/e2e/docs/valid-links.js resolves a /-prefixed link against this repository's
tree. /docs/flowfuse-nodes/ is served from FlowFuse/website, so it has no file here and
the check reports it missing. Absolute URLs are validated over HTTP instead, which is what
those pages need.

Worth noting the same check passes a link written as /docs/user/snapshots.md, because the
file does exist on disk. It validates the source tree, not the URL space, which is why these
56 links survived this long.

One thing left for someone who knows

No page documents upgrading a team's tier. Upgrading Teams points at the closest section
that exists rather than at the page it implies.

Nine feature tiles, three of which pointed at the wrong page and one of
which pointed nowhere at all:

- Pipelines went to Snapshots
- Remote Instances and High Availability both went to Device Groups
- Upgrading Teams had an empty href
- Managing Teams carried Custom Domains' description

Community Support has a page and a nav entry but was never linked from
here, so it is added alongside Troubleshooting and Cloud Support.

The four FlowFuse Nodes links were absolute URLs into /node-red/flowfuse/,
which the website now 301s into /docs/flowfuse-nodes/. They point at the
destination directly.
56 links across 20 pages were written as /docs/user/snapshots.md rather
than /docs/user/snapshots/. The docs site has no .md routes, so every one
of them 404s; verified against production before and after.

README.md and index.md resolve to their directory rather than to a
/README/ path, and anchors are preserved.
The docs link check resolves a /-prefixed link against this repository's
own tree. /docs/flowfuse-nodes/ is served by FlowFuse/website, so it has
no file here and the check reports it missing. Absolute URLs are validated
over HTTP instead, which is what these pages need.
@dimitrieh
dimitrieh force-pushed the docs/homepage-broken-links branch from dcd973f to 2a1d8f6 Compare September 14, 2026 10:32
@dimitrieh
dimitrieh requested a review from Yndira-E September 14, 2026 10:33
@dimitrieh

Copy link
Copy Markdown
Contributor Author

Review links

There is no deploy preview on this repo's docs PRs (the website job builds and link-checks
but never deploys), so these are the live pages. Every one of them is a page this PR
touches: open it, then check the diff for that file.

The home page is where the four tile fixes are: https://flowfuse.com/docs/

Click the tiles today and compare against where they now go:

tile click it today, you land on after this PR
Pipelines https://flowfuse.com/docs/user/snapshots/ https://flowfuse.com/docs/user/devops-pipelines/
Remote Instances https://flowfuse.com/docs/user/device-groups/ https://flowfuse.com/docs/device-agent/introduction/
High Availability https://flowfuse.com/docs/user/device-groups/ https://flowfuse.com/docs/user/high-availability/
Upgrading Teams nowhere, the link is empty https://flowfuse.com/docs/cloud/billing/#team-billing

Community Support is added to the Support list and 301s out to the Node-RED forum, which is
what that page is for: https://flowfuse.com/docs/community-support/

The .md links are easiest to see as a pair. First URL is what the docs link to today,
second is what they link to after:

All 20 pages whose links changed

/docs/user/introduction/ carries 22 of the 56 and is the best single page to spot-check.

@Yndira-E
Yndira-E merged commit 65f2b6d into main Sep 14, 2026
15 checks passed
@Yndira-E
Yndira-E deleted the docs/homepage-broken-links branch September 14, 2026 11:45
@dimitrieh

Copy link
Copy Markdown
Contributor Author

Correcting something I claimed in this PR's description, after finding the mechanism I had missed.

The .md links were not broken. nuxt/utils/remark-docs-links.ts in FlowFuse/website normalises them at build time: it strips .md and a trailing /README from both absolute and relative link URLs. So a page written as [Snapshots](/docs/user/snapshots.md) already rendered as href="/docs/user/snapshots", which 301s to the trailing-slash URL and resolves fine.

My "verified against production" check fetched https://flowfuse.com/docs/user/snapshots.md as a URL. That does 404, but no rendered page ever pointed at it, so the 404 was mine, not the docs'. The conclusion I drew from it was wrong.

What the second commit actually does, then: it makes the source match the URL the site serves, and skips a redirect hop. That is a small real improvement and nothing in the tree regressed, but it is a tidy-up, not a bug fix, and the description oversold it.

The first commit stands. Those were genuinely wrong: an empty href, Pipelines pointing at Snapshots, Remote Instances and High Availability both pointing at Device Groups, and a duplicated description. All confirmed fixed on the live page.

Worth recording for anyone who looks at this later: the same plugin means ~160 relative .md links elsewhere in docs/ are also fine as written, and do not need the same sweep.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants