From 2a6f6f8764657e44c88d5688947d099c1edc83a2 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Thu, 5 Nov 2026 09:56:08 +0100 Subject: docs: add HardenedPass docs section design Wiki-like bilingual section on the site, with a shared page tree, one reading order across sections and collapsible navigation on mobile. Co-Authored-By: Claude Opus 5.5 --- .../specs/2026-11-05-hardenedpass-docs-design.md | 113 +++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md (limited to 'docs') diff --git a/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md b/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md new file mode 100644 index 0000000..d81e177 --- /dev/null +++ b/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md @@ -0,0 +1,113 @@ +# HardenedPass docs section: design + +## Goal + +Document the HardenedPass Android app on danix.xyz in a wiki-like section: what it +is, how it works, how to do things with it. Readers include complete beginners who +have never used `pass`, OpenPGP or git. Only the maintainer writes pages, so no +in-browser editing is needed, and a subdomain with wiki software was rejected. + +## Location + +New top-level section, bilingual: `/hardenedpass/` and `/it/hardenedpass/`. Menu +entry in both languages directly after `slackware`; `legal` moves to weight 7. + +## Page tree + +Eleven pages, three section indexes and the landing page, in EN and +IT. Each page has a unique `weight` that sets one reading order across all sections. + +| Path | Weight | Covers | +|---|---|---| +| `_index` | | What it is, why the fork exists, what differs from upstream | +| `getting-started/concepts` | 10 | pass, OpenPGP and git in plain words, and each one's role | +| `getting-started/install` | 20 | Get the APK, verify checksum and signing certificate, update | +| `getting-started/create-store` | 30 | From zero: PGP key, store, private git remote | +| `getting-started/connect` | 40 | Clone on the phone, SSH key or password, import PGP key | +| `using/entries` | 50 | Read, search, copy, create, edit, move, delete, generator | +| `using/otp` | 60 | TOTP codes | +| `using/sync` | 70 | Pull, push, conflicts and recovery | +| `using/autofill` | 80 | Enable, fill, save, phishing warning, browsers | +| `reference/settings` | 90 | Every setting and what it does | +| `reference/security` | 100 | Where secrets live, what the app protects from and what it does not | +| `reference/troubleshooting` | 110 | Common errors, their meaning, the fix | + +`getting-started` reads in order. A reader who already has a store starts at +`connect`. No FAQ page (it lives in `troubleshooting`), no changelog (GitHub Releases +has it), no build-from-source page (the README has it). + +## Layout + +Desktop, from the theme's `lg` breakpoint (1060px): a sticky left column holds the +page tree and, below it, the current page's table of contents. The right column +holds breadcrumb, title, content and prev/next links. + +Mobile: the tree and the table of contents collapse into two native `
` +elements above the content. No JavaScript. + +Prev/next walk `RegularPagesRecursive.ByWeight` of the section, because +`.PrevInSection` stops at section borders. Section index pages list their own pages. +`project-row` is not reused: it is built for projects with status badges. + +## Search + +Site search indexes title and the first 160 characters of the summary, not body +text. The section is added to `index.json` as is. Every page therefore needs a +`date`, which the index prints, and a summary that names its topic. Full-text search +would change search site-wide and is out of scope. + +## Changes + +Theme repo (`themes/danix-xyz-hacker`): + +- `layouts/hardenedpass/list.html`, `layouts/hardenedpass/single.html` +- `layouts/partials/docs-nav.html`: tree, table of contents, prev/next +- `layouts/index.json`: add the section +- Tailwind utilities only, then `npm run build` to refresh `main.min.css` + +Content repo: + +- `hugo.toml`: menu entries for both languages +- `i18n/en.yaml`, `i18n/it.yaml`: new keys +- `content/{en,it}/hardenedpass/` +- `static/uppies/2026/11/`: banner and screenshots +- Submodule pointer bump + +HardenedPass repo, once the section is live: link the docs from the README and remove +the website item from `TODO.md`. + +## Content rules + +- Voice: first-person site tone on the landing page only. How-tos use plain second + person. +- Both languages are drafted together; the maintainer reviews the Italian. +- Every step is checked against the code or on the emulator before it is written. + Nothing is carried over from upstream docs unverified. +- Values that drift, such as dependency versions, stay out of the pages. +- Examples use example.org addresses and placeholder hostnames. + +## Screenshots + +Taken from the `aps-test` emulator running windowed, with the throwaway e2e store +only, in both languages. The agent drives the emulator and says what to capture; the +maintainer takes each screenshot from the host. `FLAG_SECURE` blocks `screencap`, not +the emulator window, so secure screens are expected to be capturable this way; the +first such capture confirms it. If it fails, those screens stay text only. + +## Verification + +- `hugo --gc --minify` builds clean with `relref` for internal links, so a broken + link fails the build. +- Local `hugo server -D` checked at desktop and mobile widths, in both languages. + +## Publishing + +All pages start with `draft = true`. The maintainer flips them after review and +merges `master` into `production` to deploy. The agent never touches `production`. + +## Order of work + +1. Theme, layouts and menu, with placeholder pages. +2. `getting-started`, for review. +3. `using`, for review. +4. `reference` and the landing page, for review. -- cgit v1.2.3