nxdns/website/PLAN.md

# nxdns.sh — marketing and docs website plan

Agreed in an interview on 2026-08-15, revised on 2026-10-02, 2026-10-19 (screenshots in, section order set, the personal story moved to the owner's blog) and 2026-10-20 (install tabs, phone and light/dark screenshots). This directory will hold the site's source.

## Purpose

Convince, then teach. A marketing front page sells the project; the docs sit one click away. mediabunny.dev is the structural model (landing on top, docs behind it), not the visual one.

## Domain and hosting

- Domain: `nxdns.sh` (already owned).
- Host: Cloudflare, as a Worker serving the built site as static assets (`website/wrangler.jsonc`, which also binds the `nxdns.sh` custom domain). Cloudflare has folded Pages into Workers: wrangler's Pages commands now delegate to `wrangler deploy`.
- Deploy: `.gitea/workflows/site.yml` builds the site on push to master and runs `wrangler deploy`. The Cloudflare API token is the Gitea secret `CLOUDFLARE_API_TOKEN`, and the account id the variable `CLOUDFLARE_ACCOUNT_ID`. Cloudflare has no Gitea integration, so CI uploads directly.

## Stack and layout

- Astro + Starlight, in this `website/` directory.
- Starlight reads the existing `docs/` Diátaxis tree in place. Docs and code version together; nothing moves or syncs.

## Landing page

Four sections, in this order:

1. Hero: the README pitch — "A DNS sinkhole for your LAN. It blocks the names you do not want, and forwards the rest over an encrypted connection." — with the README's flow diagram animated. The install commands sit in their own section near the end, in three tabs: docker, tarball, nix. Each tab is a complete path or names the guide that finishes it; the docker tab writes the smallest config that starts, so nobody faces an empty file. Commands use no shell variables and plain `curl -O`. The registry allows anonymous pulls (verified 2026-10-02 against v0.0.21), so the Docker tab works without an account. The site goes live only with a release that contains aa8c9e2 (the compose file pins its own version, so the tab ends in a plain `docker compose up -d`) and f351469 (the `services.nxdns` NixOS module the nix tab uses): 0.0.23 or later.
2. Screenshots of the web UI, taken from a running instance with realistic data: Overview, Activity, Query detail, Clients, Diagnostics. Each comes in the admin UI's light and dark theme, behind a light/dark switch with light first. Phones get their own set, captured at a 390px viewport where the admin UI switches to its drawer layout, served through `<picture>`, so a phone shows readable screens instead of a shrunken desktop. All twenty images come from one session on the release the site launches with; the current set is from 0.0.24, shot on 2026-10-21 with `website/demo/`.
3. Feature grid: filtering, config-as-code, DoH/DoT, per-client groups, metrics, query log.
4. Comparison table vs Pi-hole, AdGuard Home, Technitium — only to help people choose. Seven rows: how it ships; config as a file in git that the tool converges onto; encrypted upstreams built in; serves DoH/DoT to clients; signed, reproducible releases; DHCP server; DNSSEC validation. The last two are rows nxdns loses, kept because a table that only lists wins does not help anyone choose. Competitor cells were checked against Pi-hole 6.5 (FTL 6.8), AdGuard Home 0.107.79 and Technitium 15.6.2 on 2026-10-19.

The pitch leads with what nxdns does, not with attacks on the incumbents. The page is about the tool: why the owner built it is a blog article, not a landing-page section.

## Docs section

- The full `docs/` tree (tutorial, how-to, reference, explanation) plus a changelog page rendered from `CHANGELOG.md`.
- `PLAN.md` (root) and `specs/` stay repo-only.
- Pagefind search (Starlight built-in) is on. No analytics. No live demo instance.

## Look

Approved on 2026-10-20 from a local mock (concept 2), after one rejected direction that copied Wispr Flow's landing page too closely. The mock is the reference for the build.

- Light only. No dark mode, no toggle. Warm paper, ink and amber: paper `#f5f2ea`, card `#fbf9f4`, ink `#1c1b18`, muted `#5f5b52`, amber `#f2a93b`, amber text `#a14d0a`. Every text pair passes 4.5:1. Two sections (screenshots, install) sit on rounded ink slabs.
- Type: Fraunces for headings and the wordmark, Figtree for body text, JetBrains Mono for labels and code. All three self-hosted and subset; no request leaves for Google Fonts.
- Brand is the lowercase `nxdns` wordmark in Fraunces with an amber `x`. No drawn logo.
- Section labels are dig-style comments: `;; ANSWER SECTION`, `;; VERIFY`, `;; FEATURES`. The footer ends with a zone-file line: `nxdns.sh. 3600 IN TXT "…"`.
- The hero is the README's flow diagram, animated: one query at a time travels from the devices to nxdns, a tag shows the decision, and the packet goes on to the upstream or the sinkhole and back. Slow enough to read. A still frame for `prefers-reduced-motion`.
- No illustrations, unless an image model makes them.
- Design fundamentals from the emil-design-engineering rules, not from any one site's look: no layout shift (tab panels share one grid cell), 44px tap targets, hover only under `(hover: hover)`, copy buttons on code, grey/black/white focus rings.
- Copy tone: the honest, direct voice the docs already use, about the tool. The personal story is the blog's. No personal email address on the site.

## Links

Source links point to `git.mial.net/mokhtar/nxdns` only. No GitHub mirror.

## Open questions

1. Re-check the comparison cells against the then-current competitor versions before publication. AdGuard Home had a 1.0 beta on 2026-09-30, so its cells are the most likely to move.