Skip to content

docs: change sphinx theme to Clarity#995

Open
liborjelinek wants to merge 3 commits intosyncthing:mainfrom
ReadCraft-io:main
Open

docs: change sphinx theme to Clarity#995
liborjelinek wants to merge 3 commits intosyncthing:mainfrom
ReadCraft-io:main

Conversation

@liborjelinek
Copy link

I am proposing a new theme for documentation. This is a follow-up and closes #991. It includes the "Edit on GitHub" link and the version select dropdown.

The Clarity theme already has built-in support for version selection. It is less visually intrusive than today's banner

CleanShot 2026-03-06 at 09 13 47@2x

It is also JS-free because the version list is validated and prepared during the Sphinx build. It allowed me remove former JS and legacy jQuery.

I also explicitly list dependencies in requirements.txt (only Sphinx and Clarity theme).

Lastly, I have changed lsver.go script a bit to conform Clarity theme's expected structure (changed sort order (oldest→latest becomes latest→oldest) and changed output from {"entries": [...]} to an array of {"version": "..."} objects.

You can preview it at https://showcase.readcraft.io/syncthing/. But keep in mind that version selection doesn't work because, for faster working, I am deploying to the showcase website only the latest version's files.

@liborjelinek
Copy link
Author

Because I introduced the first external dependency (the theme itself 😄), I had to change the HTML build step.

But we now have an egg-chicken problem here.

The theme requires a different structure for versions.json (changes to lsver.go are already in PR), but the updated JSON must be available at https://docs.syncthing.net/versions.json to successfully build HTML. Which is obviously not now, and thus this PR build is failing.

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.

Alternative docs theme experiment (with builtin dark mode)

1 participant