Documentation site

The documentation site and its screenshots. Part of Experiments and decisions. Newest notes go at the top of each section.

Documentation site

Modelled on uBlacklist's documentation: an introduction, getting started with screenshots, then one page per feature, publishing, and a directory of lists.

• Tried: VitePress 1.6.4, the current stable release. It pulls in Vite 5 and an esbuild with published advisories for their development servers (npm audit: two moderate, one high). Shipped: VitePress 2.0.0-alpha.20, which uses the same Vite 8 as the extension and audits clean. It only builds the documentation, so a pre-release costs little; move to 2.0 stable when it's out.
• Not used: Hugo, which uBlacklist's site uses. It would need a second toolchain alongside Node and the Nix flake.
• Screenshots come from the e2e mock pages (node e2e/run.mjs docs), so they can be regenerated after interface changes instead of retaken by hand. They show test pages, not the real engines, and the captions say so.
• The homepage showed only the logo, which says nothing about what Anubis does. It now shows one search without and with Anubis below the heading and logo, side by side (stacked on phones): the AI answer and panels removed, a site hidden, results tagged. Both pictures are cut to the same box: the logo, the search box, and the results column. They come in light and dark, following the site's mode, and each pair is also rendered as a 1920×1080 slide for talks and posts. On the slides, the pictures run off the bottom edge rather than shrinking to fit, since they're tall shots in a wide frame and shrunk they'd be too small to read.
• Tried: the pictures without the logo, over the old Google test page (grey boxes for every panel, blank site icons, "AI Mode" as a blue link that read as the current tab). It looked fake. Letters in Google's colours didn't pass for the wordmark either. The test page now follows Google's layout: the wordmark (from the CC0 collection at github.com/gilbarbara/logos, recoloured to Google's colours), the search box's buttons, All underlined as the current tab, site names and icons above each title, and panels with headings instead of grey boxes. Only the look changed: the page structure the tests read is the same, and the full e2e run gave identical output before and after.
• Scroll-driven demo (2026-09-29): the side-by-side pictures were small, and their caption sat cramped under them. The homepage now walks through one search as you scroll (docs/.vitepress/theme/scroll-demo.ts): five short steps beside a drawn results page that stays in view, where clean-up removes the panels, a site folds into its hidden line, the rest are raised and lowered, and then tagged, with the summary above them saying what Anubis did at each step. On phones the page stays at the top and the steps pass under it, and titles drop their snippets so the page fits. It's drawn in HTML rather than cut from screenshots, so each change can animate (folds open and close, results slide to their new places) instead of cross-fading between pictures whose layouts jump. It's an illustration, not Google: a plain search box, no wordmark. Motion stays inside prefers-reduced-motion: no-preference; with reduced motion the steps still change the page, without animating. The drawn page is aria-hidden, since the steps' text says what it shows. The before and after pictures are still made for the style guide and the slides. Not used: CSS scroll-driven animations (animation-timeline: view()), which Firefox still ships behind a flag; a scroll position read once per frame works everywhere.
• Demo, second pass (2026-09-29): the first wording explained too much and didn't invite scrolling. The steps are now short and plain ("Clutter out", "Done with a site?"), the first one ends with a nudge to scroll, and each result carries the button it has in the extension: the balance tipping with its ranking, the pin, and the crossed-out eye on the hidden line. One result is pinned, in the pinned frame. The icons are copied from utils/icons.ts, which can't load outside the extension. The top bar's search button is wider and outlined, so it reads as a search box.
• Demo, rising page (2026-09-30): the drawn page used to stick where it started, in the middle of the window. It now starts there, beside the heading, and rises with the scroll until it's 24px under the top bar, then sticks, so it has the whole window for the steps. That's plain sticky positioning, so there's no animation to turn off for reduced motion. The AI answer's heading carries a simple four-pointed star, a sketch of the mark engines use rather than any engine's logo.
• Homepage layout (2026-09-29): the heading, a large logo, and two buttons filled the first screen, and the demo only began below it, opening on the cluttered page beside a mostly empty column. Three layouts were drafted as mock-ups first: the results page as the heading's neighbour with switches to turn each part off; the result menu's balance, large, tipping as you pick a ranking; and a list file beside the results it tags. Switches were turned down in favour of keeping the scroll-driven demo, so the shipped layout keeps the scroll and borrows the first idea's placement. The heading and buttons are now the demo's first step, beside the drawn page from the first screen on, and the logo stays in the top bar. A line beside the steps fills as you scroll, with a diamond at each step that turns gold once the page shows it, so it's clear how far the demo goes. Steps on wide screens are 60% of the window tall, so the ones either side show, dimmed. What else Anubis does follows as plain text between hairlines instead of VitePress's cards, then a short closing section on privacy and where it works. Titles use the extension's serif, as its welcome page does, and buttons have the style guide's 6px corners. The page's text lives in docs/index.md's frontmatter, drawn by docs/.vitepress/theme/home.ts. Fixed on the way: on phones VitePress's top bar scrolls away, but the drawn page stuck below where it had been, leaving a gap; it now sticks to the top. Each phone step was 60% of the window tall while only the 38% under the page shows, so for part of the scroll no step was readable; they're now about that 38%.
• Homepage heading in tall windows (2026-09-29): on the published site in a 2000×1015 window, the heading sat well below the drawn page beside it. Its column was centred in a box of the window's height less a margin, while the page is at most 640px tall and sits at the top, so the taller the window, the further the two drifted apart: 184px apart at 1920×1200, 304px at 2560×1440, and the other way in short windows. The heading's box is now exactly as tall as the page (--demo-stage-height in brand.css), so the two are centred on each other at any height. e2e/homepage.mjs serves the built site and checks this at six window sizes from 1024×768 to 2560×1440, plus no sideways scrolling at 320px, 360px, and 390px. It failed at all six sizes before the fix, and the docs workflow now runs it.
• Homepage, centred in the window (2026-09-29): with the heading centred on the drawn page, the pair still sat at the top of a tall window: the page stuck 32px under the top bar, so a 1300px window showed the heading and page in its upper half, a wide gap, and the first step alone at the bottom. They now sit in the middle of the window below the top bar, with the same room above as below (--demo-stage-gap), and the page sticks at that same place, so it doesn't move when scrolling starts. The same pass fixed the line beside the steps showing through their diamonds: the steps not in view were dimmed as a whole, diamond included, so its fill let the line through. Now only a step's words are dimmed. e2e/homepage.mjs checks both: the page within 8px of the window's middle at six sizes, still after scrolling starts, and every diamond fully opaque. Both checks failed on the previous styles. Its first version read the top bar's height from --vp-nav-height, which this VitePress sets in rem, and was 30px out at every size until it measured the height instead.
• Demo, as crowded as a real search (2026-09-29): the demo's page before Anubis showed only an AI answer, two videos, and three questions among five results, which undersold how crowded a results page gets. It now has an AI overview with its sources, top stories, a question list, videos, forum threads, and an image row between the results, under a plain search box and a row of tabs, still no one engine's. It has only panels of kinds clean-up removes (CLEANUP in utils/cleanup.ts), and the summary names them in that order, so the demo doesn't promise more than the extension does. There are no ads, which Anubis doesn't remove. The hidden site no longer folds into a "hidden by your list" line, which is the Collapse setting. It now leaves the page, as Remove, the default, does, and the summary counts it.
• Ranking sites, played out (2026-09-30): the page opened with the same picture of one result as Tags. The project owner asked for an animation like the Introduction's, of results being reordered with the mouse. rank-demo.ts (<RankDemo />) has a pointer pin the last result, which slides to the top into its gold frame, then lower another, which slides to the bottom with its label. The summary says each change, with Undo. Results move by measuring where each was and sliding it from there to where it lands, like the extension's reranking. With reduced motion they change places without sliding. The icons, menu, and balance it shares with hide-demo.ts moved to demo-parts.ts. e2e/homepage.mjs plays it through and checks the final order. The docs' nav lit Wiki on the Privacy page as well as Privacy, since Wiki matched everything under /guide/; it now leaves Privacy out.
• Introduction: hiding a site, played out (2026-09-29): the Introduction opened with a screenshot of a test page, taken with the test settings' Collapse, so it showed a "hidden by your list" line most people never see. On the site it's now an animation (docs/.vitepress/theme/hide-demo.ts, registered as <HideDemo />). When it scrolls into view, a pointer clicks the button beside a result and presses Hide in its menu, and the balance tips. The menu then closes as the site leaves the page, and the summary says "Hid fandom.com." with Undo, as the extension does with Remove. Play again replays it. With reduced motion there's no pointer, and the page changes without animating. It's drawn in HTML with the homepage demo's styles, and its menu copies the extension's cartouche, balance, and rankings. The page's Markdown keeps a screenshot for reading on GitHub, hidden on the site, now taken with Remove: node e2e/run.mjs docs switches to Remove for summary.png only, since hidden.png shows the Collapse line on purpose. The first version's open menu hung past the drawn page onto the caption, so the page has a fourth result. e2e/homepage.mjs plays the demo through, with normal and reduced motion.
• Demo matched to the extension (2026-09-29): on a phone the demo's hidden line wrapped into two ragged lines ("hidden by / your list"), where the extension's stays on one line and cuts the site and its reason short with an ellipsis, keeping Show on the line (.gone in shadow.css). Checked every part of the demo against what the extension draws and matched the ones that had drifted: the hidden line now starts with the crossed-out eye and is cut short the same way; the summary starts with the Anubis head, not a diamond; Pinned, Raised, and Lowered carry their icons, with Raised in regular weight and Lowered shown (it was missing); the lowered result fades to 58% and the pinned frame is gold at 55%, as in page.css. The summary's wording already matched utils/summary.ts. The demo still leaves out the summary's Load more results and settings buttons, to keep the drawn page small. The comment at the top of scroll-demo.ts lists where each part comes from, so the next change to one of them can be carried over. Later the same day: the gold pin change on main (a pinned site gets no label, and only its button turns gold) reached this branch in a merge, and the demo followed it: no Pinned label, and the buttons of raised, lowered, and hidden sites stay muted.
• A shorter summary on phones (2026-09-29): at phone width the summary's sentence ran to four lines above the results, before Show hidden, Load more results, the cog, and a row of tags. Considered: a short line with the rest behind Details; a short line with no way to see the breakdown; and only the mark and Show hidden, with everything else behind the mark. Shipped: the short line with Details. At 600px or less the summary says it in a few words (shortSummary in utils/summary.ts: "Anubis changed 4 of 9 results and cleaned up the page."), then Show hidden and Details, which shows the full sentence, Load more results, the cog, and the tags, and reads "Fewer details" while open (aria-expanded). The last change and Undo always show, since they answer what you just did. Where the full sentence is short already (only one tag's results shown, or nothing changed) it stands. Whether Details is open is kept in the content script, so the next pass keeps it. The short form is chosen by width in shadow.css, not by the engine's phone layout, so a narrow desktop window gets it too. The mobile e2e part checks that the phone shows the short form, that Details shows the full sentence and tags, and that a wide window shows the full sentence without Details; before the change it failed four of those checks. The first build left the short line showing beside the full sentence once Details was open, which the check caught. The homepage demo draws the phone summary the same way.
• Phone summary, second pass (2026-09-29): with Details open, the summary kept its wide layout: the sentence stretched across the line, which pushed Show hidden and the cog to the far edge and left "Fewer details" alone on the next line, under the mark. On phones the summary is now a two-column grid. The mark hangs on the left; the sentence, the last change, and the tags line up in the second column. The sentence and its buttons are one paragraph (.line, which is display: contents on wider screens, so the wide layout is unchanged), so the buttons follow the words and wrap with them, as the homepage demo draws it. The same pass found that the short sentence could be no shorter than the full one ("Anubis changed 1 of 7 results." for "Anubis hid 1 of 7 results."). shortSummary now gives the short form only when it's shorter. The mobile e2e part checks that no button, tag row, or change line starts left of the sentence on a phone, folded or open. On the previous build it failed with "Fewer details" and the tags under the mark.
• Images live in docs/img/ and pages link to them relatively, so the Markdown reads correctly on GitHub as well as on the site. Links to repository files outside docs/ are full GitHub links, since the site can't serve them.
• Dark mode: the screenshots were all light, so in the site's dark mode each one was a white block on a dark page. Every screenshot now comes in light and dark (result.png and result-dark.png): the mock search pages in their dark mode, and the settings and popup with the system in dark mode. Pages still link to the light one, which is what GitHub shows; the site's Markdown hook (docs/.vitepress/config.ts) adds the dark twin next to any image that has one, and CSS shows the one matching the site's mode. Not used: <picture> with a prefers-color-scheme source, which GitHub understands, but it follows the system's setting, not the site's light/dark switch.
• The lists directory page renders lists/directory.json at build time, so it can't drift from what the extension offers.
• README and wiki (2026-09-29): the README had grown into a second manual. It repeated the wiki's features in more detail, the engine list, the permissions, and the install steps, and the developer steps from DEVELOPMENT.md, so every change had to be made in two places, and nothing noticed when one was missed. It is now a front page: one line per feature linking to its wiki page, links for engines, privacy, and installing, and the few commands to start developing. Store releases and loading a build by hand moved to DEVELOPMENT.md and the Getting started page. tests/readme.test.ts checks that the README's features and the introduction's Features have the same names in the same order and link the same pages, and that every README link resolves. Not used: generating the README's feature list from the wiki with a script. It would need running after every wiki edit and a CI check that it had been, where a test that fails on a mismatch does both.
• Publishing uses GitHub Pages from a workflow. Pages has to be switched to "GitHub Actions" in the repository settings once; until then the deploy step fails.