fix: point the site at documentation that still exists - #6
Merged
Conversation
Six of the site's links into srcfl/ftw are stale. Five are README anchors the README no longer has: the four install buttons point at #option-a-raspberry-pi-sd-card-image through #option-d-build-from-source and the closing "Get started" button at #quick-start, all dropped when that section was reorganized into "Install on Linux" and "Install on Home Assistant". GitHub discards a fragment it does not recognize instead of erroring, so each of those buttons quietly left the visitor at the top of a long README. The sixth, "Browse drivers", still opens srcfl/ftw/tree/master/drivers -- and finds no drivers there. They moved to srcfl/device-drivers; drivers/*.lua is gitignored in FTW now and fetched at build time from a pinned commit. Raspberry Pi image goes to docs/rpi-image.md, the Docker installer and Home Assistant buttons to the two install headings the README actually has, build from source to #local-development. Both driver links go to srcfl/device-drivers -- docs/WRITING-A-DRIVER.md and drivers/lua/ -- which is where a driver pull request belongs now, so "Contribute the integration back through a pull request" sends people to the repository that can accept one. The example filename in the code window follows the same path. Co-authored-by: HuggeK <48095810+HuggeK@users.noreply.github.com>
frahlg
marked this pull request as ready for review
July 30, 2026 08:57
This was referenced Jul 30, 2026
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
3 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.
Six of the site's links into
srcfl/ftware stale — five README anchors the README no longer has, and one that still opens but no longer shows what it promises.ftw#option-a-raspberry-pi-sd-card-imageftw/blob/master/docs/rpi-image.mdftw#option-b-docker-installerftw#install-on-linuxftw#option-c-home-assistant-os-add-onftw#install-on-home-assistantftw#option-d-build-from-sourceftw#local-developmentftw#quick-startftw#install-on-linuxftw/blob/master/docs/writing-a-driver.mddevice-drivers/blob/main/docs/WRITING-A-DRIVER.mdftw/tree/master/driversdevice-drivers/tree/main/drivers/luaThe example filename in the code window follows the driver move too:
drivers/my_inverter.lua→drivers/lua/my_inverter.lua.Why the five anchors failed silently rather than 404ing
GitHub serves the README whatever fragment you ask for, and simply drops one it cannot find. So a visitor clicking Raspberry Pi image got the FTW README scrolled to the top — no error, no hint that the page meant to take them somewhere specific. The install section was reorganized into
## Install on Linuxand## Install on Home Assistant, and the four#option-…headings plus#quick-startwent with the old structure.Why both driver links now leave the FTW repository
Driver source moved to
srcfl/device-drivers, which is now FTW's default signed driver channel. In FTW,drivers/*.luais gitignored and fetched at build time from the commit pinned indrivers/BUNDLED_SOURCE.json— softw/tree/master/driversstill resolves, but the only thing left in it is that pin file. FTW's README says it plainly: "There is no file to open a pull request against; fix it upstream and move the pin."That matters for this section specifically, because its own copy says "Contribute the integration back through a pull request" — it should send people to the repository that can accept one.
device-driversis also where the contributor documentation now lives, including ablueprint/BLUEPRINT.luathat is verified like a shipped driver.ftw/docs/writing-a-driver.mdstill exists and still describes the host API, so that link was not broken — it now points at the canonical version instead, which is the one that ends in a PR template.Verification
Every remaining link into
srcfl/ftwwas resolved againstsrcfl/ftw@master— file tracked in git,#fragmentmatching a real heading — by the checker proposed in the companion PR:Run against the currently published
index.html, the same checker reports the five dead anchors this PR fixes.Companion PR in FTW adds that check to its merge pipeline so the next heading rename shows up here as a warning instead of as a dead button: srcfl/ftw#719
🤖 Generated with Claude Code