- HTML 90.4%
- JavaScript 7.4%
- CSS 2.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
* site: refresh screenshots for Sable 1.9.0 * site: publish Sable 1.9.0 updates Adds a DHCP group to /compare (Sable vs Technitium, BIND, Pi-hole, AdGuard Home), refreshes competitor versions, and lists the DHCP server in the homepage marquee. * PR screenshots (removed in next commit) * Remove PR screenshots |
||
| .claude | ||
| public | ||
| scripts | ||
| src | ||
| .gitignore | ||
| AGENTS.md | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| wrangler.jsonc | ||
sabledns.io
Marketing and documentation site for Sable, deployed with Cloudflare Workers Static Assets.
Layout
public/— the deployable static site (HTML pages, shared CSS/JavaScript underpublic/assets/, raw markdown docs underpublic/docs/, optimized demo screenshots,llms.txt, and link-preview assets)- The HTML pages are built artifacts. Source of truth for docs content is
docs/in the main sable repo; page templates are maintained insrc/templates/. - Product screenshots are captured from the main repo's deterministic demo and published as optimized WebP assets under
public/assets/product/. Keep each light/dark comparison pair matched to the same demo data and capture. Every homepage feature section shows a light/dark comparison, so a new section or carousel slide needs both captures.
Cloudflare Workers setup
The site deploys as a Workers Static Assets project. wrangler.jsonc names the
Worker and points Wrangler at the checked-in public/ directory, so no build
step or Worker script is required. The connected build may use
npx wrangler versions upload; Wrangler will include the static asset bundle in
the uploaded version. Preview URLs are explicitly enabled, so an uploaded PR
version can be reviewed without changing production traffic.
Attach the custom domain sabledns.io to the Worker in Cloudflare after the
first deployment.
Workflow
Update documentation content
The handbook currently targets Sable 1.9.0. The hero keeps the install command and
the Get started and Download buttons, with a short icon list below them that links the GitHub release notes and the Technitium migration
guide. The migration guide is also in the Start here navigation group. A short "Why Sable" problem section sits between the protocol ticker and the features, followed by "One tool. Every answer.", a pinned scroll scene where four config files are pulled into the Sable mark (scroll position drives it; reduced motion shows the end state). The features section opens with Blocking, then Insights, whose carousel walks through the overview, findings with charts, devices, an app, and the query explanation; Alerts, the MCP server, and Dynamic DNS are cards. Refresh the product and guide screenshots from the deterministic demo with npm run screenshots whenever a major console UI update ships.
Keep the main sable repository alongside this checkout. Edit Markdown there,
and add or reorganize pages in sable/docs/navigation.json. Then run:
npm ci
npm run check
npm run dev
The local preview is http://127.0.0.1:4371/docs/. Set SABLE_SOURCE to use a
different main-repository path. The build copies the Markdown and referenced
guide screenshots, renders complete article HTML, and updates llms.txt.
The website changelog includes only dated stable releases. Unreleased and
pre-release sections remain in Sable's source changelog but are omitted from
both the rendered page and its raw Markdown URL.
The /compare page compares Sable with Technitium, BIND 9, Pi-hole, and
AdGuard Home. Its rows live in scripts/comparison.mjs; the other projects'
cells follow their own documentation as of the date at the top of that file, so
re-check a cell against its source and update the date when you change it.
The /license page renders the root LICENSE file from the main Sable
repository, and the footer links to it.
The original design is preserved in src/templates/; edit the homepage and
benchmark templates there instead of changing generated HTML in public/.
Commit updated public/ output with source changes; Cloudflare serves static
assets without requiring a build-time checkout of the main repository.
There is no browser-side unpacking. Docs and benchmarks are ordinary HTML;
the docs menu uses a small deferred script, with no React dependency or
article fetch. The homepage retains its interactive design runtime with local
shared scripts. Fonts, images and runtime assets extracted from the original
export live under public/assets/site/. Treat fingerprinted assets as immutable;
use a new content hash when changing one. The build fingerprints docs CSS and
JavaScript, and _headers lets browsers cache these shared assets for a year.
The document body, table of contents, and sidebar are present even without
JavaScript. scripts/docs-page.mjs renders the documentation layout.
The sidebar opens one topic group at a time, automatically revealing the active
page's group when following a link. The entry page is Getting Started; all
reference pages remain available without showing the entire inventory at once.
Optional collections in each navigation group nest related pages under a
subheading (for example, Installation or Addresses and aliases). Collection
entries reference page slugs in the same group. The build rejects missing or
duplicate assignments and aligns previous/next links with the nested reading
order. Sidebar-only styles live in src/docs-navigation.css.
The manifest's optional navigationLabels map provides short sidebar labels
without changing the full article titles or previous/next descriptions.
Its versionLabel appears quietly beside the documentation breadcrumb; do not
use a site-wide warning banner for normal version context.
At mobile widths the sidebar becomes a Browse docs control that opens an
off-canvas navigation panel. Keep its Escape, backdrop, selection-close, scroll
lock, reduced-motion, and focus-return behavior when changing the controller.
The small docs controller is maintained in src/docs-controller.js; Markdown
rendering and link resolution live in scripts/markdown.mjs. Old links such as
/docs#backup remain supported. Document section links use
/docs/guides/backup#heading. Each article has a static HTML entry point and
article-specific browser title and canonical URL. Cloudflare removes trailing
slashes; the controller redirects historical hash routes to their clean URLs.
Guide images live in the main repository's docs/assets/guide-screenshots/.
Current images are real Sable 1.9.0 captures using the deterministic Vandelay
demo data. Product gallery images are optimized WebP versions of the same demo
captures in public/assets/product/. Keep both sets in step with the described
task and preserve the release version shown in the screenshots.
Update the site for a Sable release
After a stable release is published, ask Claude Code in this repository to "run
the release-website workflow for 1.6.0". The saved workflow in
.claude/workflows/release-website.js reads the release notes, adds a Sable
worktree at the release tag under _work/release-<version>/sable, retakes the
screenshots, updates the version text in both repositories, rebuilds, and
checks the result. It fixes what is mechanical, sends a skeptic after every
feature it finds covered, and opens a PR on each repository without merging
either. Copy, new sections, and anything else a visitor would read differently
come back as a list to review instead of being changed. Pass ship: false to
stop before commits and PRs, or screenshots: false to keep the current images.
Each piece also runs on its own:
npm run screenshots -- --version 1.6.0 --sable ../sable
npm run screenshots -- --version 1.6.0 --sable ../sable --step capture --shots insights,query-explain
SABLE_SOURCE=../sable npm run check:browser
npm run screenshots builds bin/sable stamped with the release so the console
shows it, starts the Vandelay demo (which also writes Sable's own
docs/assets/screenshots), photographs every shot in scripts/screenshots.mjs
in dark and light, stops the demo, and publishes 2000px homepage WebP pairs and
1600px dark guide images. The building, the demo, and the photographs come from
Sable's screenshot engine, scripts/browser/screenshots.cjs in the Sable
checkout; this repository keeps only its shot list and the WebP publishing.
--step runs one stage at a time: build, demo, capture, stop, or publish. It
refuses to start while another demo holds the demo's ports, and it needs
magick, cwebp, and Playwright from Sable's scripts/browser. check:browser loads every built page at phone and desktop
widths and fails on sideways scrolling, failed requests, or script errors. It
adds Safari's engine when WebKit is installed for Playwright.
scripts/release.test.mjs fails when the homepage, README, or docs name a
release other than the current one.
Publish reviewed changes
- Push to
main→ production deploy at sabledns.io - Open a PR → use the branch or commit preview URL in Cloudflare's PR comment
- Promote the reviewed version → production updates at sabledns.io