help-book

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[2.5.0] - 2026-05-13

A six-feature release. Most of the work is rendering: diagrams, charts, in-page find, heading anchors, edit-on-GitHub, plus a polish pass on search.

Added

• Configurable “Edit this page on GitHub” link via editUrl in chapters.json
• Heading anchor links: hover H2/H3 to reveal a # icon that copies the section URL.
• Mermaid diagram support: ```mermaid code blocks render as SVG diagrams (lazy-loaded from CDN). Chapters without diagrams pay nothing. Theme tracks the help-book light/dark toggle.
• Chart.js support: ```chart code blocks with JSON config render as interactive charts (lazy-loaded). Library is fetched from cdn.jsdelivr.net on demand — pages without a chart pay no cost. Charts re-render on theme toggle so axis/grid colors match. JSON parse and chart-init errors fall back to the original source plus an error banner.
• PR template and issue forms (bug report, feature request)
• Find-in-page: typing in the search box now highlights matches in the current chapter inline, with a counter and prev/next buttons (Enter / Shift+Enter cycle through matches). Cross-chapter results still appear below as a labeled section.

Changed

• CSP: script-src and connect-src now include https://cdn.jsdelivr.net; worker-src 'self' blob: added for mermaid’s optional layout workers. Production deployments serving an HTTP CSP header must mirror these.
• Search results now show a context snippet around the matched term, with the match highlighted.

Fixed

• <img> paths in chapter markdown are now resolved relative to the chapter’s own directory (PR #40 documented this, but help.js never wired it up — relative paths 404’d against the SPA root).
• DOMPurify’s URI allowlist accepts bare relative paths like images/foo.jpg; previously only ./ and ../-prefixed paths survived, so the sanitizer silently stripped src from any plain-relative image.

Documentation

• Documented image-embedding convention (Markdown syntax, suggested folder layout, sanitizer behavior).
• Demo chapters rewritten as a feature showcase: every new feature has its own chapter under What’s New, with the Images chapter as the single place where images and sizing are demonstrated.

2.4.0 - 2026-04-20

Install/update ergonomics: one-shot update command, automatic rollback snapshot. No breaking changes — existing installs keep working unchanged until they update once.

Added

• help/update wrapper script — shipped inside the release ZIP. After one install, updating is:

  bash help/update          # → latest release
  bash help/update v2.4.0   # → pin a specific version
  

  No more copy-pasting the full curl | bash URL. The wrapper always targets the help/ folder it lives in, regardless of CWD.

• Pre-update backup — before overwriting code files, the previous versions of index.html, help.css, help.js, logo.svg, update are snapshotted to help/.help-book-backup/ (one generation deep). Rollback hint is printed in the output.
• Version-diff output on update:

  [help-book] update complete — v2.3.0 → v2.4.0 in ./help
  [help-book] backup of previous version: ./help/.help-book-backup/
  [help-book] rollback: cp ./help/.help-book-backup/*.* ./help/ ...
  

Changed

• install.sh file-list split into REQUIRED (core 4 code files — must be in ZIP) and OPTIONAL (update). Older ZIPs without the wrapper install gracefully; downgrades keep the existing wrapper in place.
• Release ZIP now contains 5 files (previously 4) — the update wrapper is bundled alongside index.html, help.css, help.js, logo.svg.

2.3.0 - 2026-04-20

Audit pass driven by impeccable /audit — addresses every P0/P1/P2/P3 finding. No breaking changes to the public surface (accent, CSP, chapters.json schema, install.sh).

Added

• Collapsible “On this page” TOC for mobile viewports (<details> element in .help-content). The header TOC bar used to disappear under 768px with no replacement, leaving long chapters unnavigable on phones.

Changed

• Typography swap: Inter → Geist Sans as the body/UI face. Inter is on every “default AI font” list; Geist pairs naturally with the already-loaded Geist Mono.
• Article width capped at 72ch + 64px padding. Body text on wide monitors used to wrap at 100+ chars; content still anchors left against the sidebar.
• H4 scale opened: 16 → 18px. Previous scale had H4 = body size, distinguished only by weight; the new ratio matches the ~1.25 step used elsewhere.
• Accent shades are now theme-aware: --help-accent-deep / --help-accent-light redefine themselves under [data-theme="dark"]. Six [data-theme="dark"] override blocks collapsed into the token definition.
• Scrollbar tinted toward brand accent (color-mix with accent at 6%/10%).
• Sidebar-header divider removed — replaced 1px border-bottom with whitespace (DESIGN.md already mandated no dividers).
• Search input width no longer animates on focus — animating width forces a reflow every frame. Input sized for its typical content across three breakpoints.

Fixed

• Blockquote border-left stripe removed (impeccable BAN 1). Full background tint + italic now signal the quote; the 3px accent side-stripe is the #1 AI-design tell in admin/doc UIs.
• --help-text-tertiary lifted to WCAG AA 4.5:1: #888 → #6e6e6e on light, #888 → #9a9a9a on dark. Affects footer (11px), prev/next labels, copy-button label.
• H1 mobile letter-spacing (-0.4px at 28px) — previously missing while 40px and 32px both had tracking.

Accessibility

• Interactive targets enlarged: nav-item 30 → 36px (mobile 44px), TOC-bar link 32 → 36px, copy-button 28 → 32px (mobile 44px). WCAG 2.5.5 compliant on touch.

Polish

• .help-content max-width now fluid via clamp(72ch, 62vw, 84ch) so ultra-wide viewports gain breathing room while 1024-1440 stays at the 72ch readability target.
• Heading scale opened: H1 40 → 44, H2 24 → 26, H3 stays 20 (H2/H3 ratio now 1.30, ≥1.25 target). H4 repurposed as uppercase muted eyebrow label since a 4th size level is rarely earned in docs.
• <ol> / <ul> markers now use the brand accent for subtle cohesion.
• Inline <code> gains a 1px border for clearer boundary against body text.

2.2.2 - 2026-04-20

Fixed

• Custom accent in chapters.json now propagates consistently across all UI states (#33):
  • Five hardcoded rgba(232,121,29,...) sites (selection, search-glow, sidebar-active, TOC-active, code-highlight) replaced with color-mix(in srgb, var(--help-accent) XX%, transparent) so tints track the override
  • --help-accent-deep and --help-accent-light now derived from var(--help-accent) via color-mix() instead of hardcoded orange tones — fixes light-mode text reverting to default orange when a custom accent is set

2.2.0 - 2026-04-19

Added

• Fox brand logo: 28×28 SVG in the sidebar header (uses currentColor to inherit the accent), plus logo.svg registered as the browser tab favicon
• Installer and release workflow now ship logo.svg as a fourth code asset alongside index.html, help.css, help.js

2.1.0 - 2026-04-18

Added

• scripts/install.sh — one-line installer/updater for downstream projects (curl ... | bash)
• Release workflow publishes a code-only ZIP asset (help-book-vX.Y.Z.zip) on every tag, containing only index.html, help.css, help.js
• README documents install, version-pinned install, custom target dir, manual ZIP download, and inspect-before-run flow
• .help-book-installed marker file for robust install/update detection

Changed

• Default accent reverted from Mintlify green (#18E299) back to warm orange (#e8791d); --help-accent-deep and --help-accent-light adjusted to matching tones
• Release workflow: ZIP is built from the tag commit (via git archive), attached atomically through gh release create (avoids release-without-asset state on partial failure)
• Release workflow: drop unused pull-requests:write permission; git push retries 3× with rebase + backoff
• README manual-download snippet now resolves the latest tag dynamically and uses unzip -n to never overwrite existing files
• Code cleanup: removed decorative section-header comments across help.js, help.css, changelog.mjs; kept WHY-comments

Fixed

• Five hard-coded rgba(24,226,153,...) (green) sites in help.css — selection, search-glow, code-highlight, sidebar-active and TOC-active backgrounds now use the orange accent
• changelog.mjs: removed dead BODY_REF_RE loop
• changelog.mjs: resolve CHANGELOG.md against GITHUB_WORKSPACE (CWD fallback) so local invocation from a subdir writes to the right path

Security

• installer: validate version tag against ^v[0-9]+\.[0-9]+\.[0-9]+(-pre)?$ before embedding in URLs (defeats injection via crafted API response or CLI arg)
• installer: abort on unsafe HELP_BOOK_DIR (system paths, $HOME directly)
• installer: extract ZIP to a fresh tmp dir then whitelist-copy only the 3 expected files (defeats zip-slip + symlink-follow); refuse to overwrite symlinked target files (TOCTOU mitigation)
• installer: integrity check via unzip -tq; bounded curl --connect-timeout/--max-time/--retry; trap covers EXIT INT TERM HUP
• workflow: every $ in run: blocks is mapped through env: first (defeats script-injection via crafted workflow_dispatch tag input or malicious tag name); explicit tag-format validation
• workflow: set -euo pipefail at the top of every run: block
• changelog.mjs: escape Markdown special chars in commit subjects + scopes before rendering (prevents phishing links / HTML injection in auto-generated release notes)

2.0.0 - 2026-04-18

Changed (BREAKING)

• Complete visual redesign inspired by Mintlify and macOS Settings
• Default brand accent switched from orange (#e8791d) to Mintlify green (#18E299) — still overridable via chapters.json
• Typography swapped to Inter (UI/body) and Geist Mono (code/labels), loaded from Google Fonts
• Layout reworked: floating sidebar bubble (full viewport height, fixed left), header fixed top with backdrop blur edge-to-edge, content runs full-width and anchors left
• TOC bar moved from a separate sticky band into the header center
• Title moved from header into the sidebar bubble
• All section dividers and border-lines removed in favour of whitespace and subtle background tints
• Code blocks, tables, prev/next cards use 16px radius and 5%-opacity borders
• Search input and copy buttons reshaped to pills (radius 9999px)

Added

• Mintlify-inspired DESIGN.md reference at repo root (via npx getdesign)
• CSP <meta> policy with strict allowlist
• Color-scheme <meta> and FOUC-preventing inline theme bootstrap
• ARIA: skip-link, combobox search pattern, aria-pressed/aria-expanded sync, focus trap on Esc
• prefers-color-scheme change listener (auto-follow OS while no manual choice exists)
• Cross-tab theme sync via storage event (falls back to OS pref when storage cleared)
• prefers-reduced-motion and @supports not (backdrop-filter) fallbacks
• @media print stylesheet
• Production deployment notes in README (security headers, hardened express config, symlink warning)
• iPhone safe-area insets for sidebar and header

Fixed

• Race condition in navigate(): stale fetch could overwrite newer chapter — now bails on navId !== currentId
• hashchange re-entry: currentId set before hash update, plus decodeURIComponent to handle percent-encoded ids
• scrollSpyLocked leaked when a chapter had fewer than two <h2>s — now released
• Sidebar group did not auto-expand when navigating to a child via hash or search
• Mobile overlay z-index was below the header (49 → 105) — overlay now covers the header
• Skip-link was hidden behind the fixed header — now position: fixed
• TOC justify-content: center collapsed the scroll start at many items — now safe center
• 4px misalignment between header content and article body
• Sidebar border-radius clipped the scrollbar — sidebar now overflow: hidden, inner <ul> scrolls
• Inline code lost its visual hierarchy in dark mode (now uses --help-bg-secondary)
• Memory leaks: copy buttons and TOC links use event delegation, single timer for scrollToHeading
• Mobile sidebar slid under iPhone notch — now respects env(safe-area-inset-top)

Security

• Explicit DOMPurify config: ALLOWED_URI_REGEXP, FORBID_TAGS, FORBID_ATTR, controlled target/rel
• Validate accent (CSS-color regex) and chapter.file (path regex with traversal-depth guard) from chapters.json
• Object maps switched to Object.create(null) (prototype pollution dicht)
• target="_blank" links get rel="noopener noreferrer"
• referrerpolicy="no-referrer" on all CDN tags
• Removed frame-ancestors from <meta> CSP (only valid as HTTP header)
• README documents required production headers (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy)

1.1.0 - 2026-03-30

Security

• XSS protection: Markdown output sanitized with DOMPurify before rendering
• SRI hashes on all CDN scripts (marked.js, highlight.js, DOMPurify)
• HTML injection: chapter IDs escaped with encodeURIComponent in href attributes

Fixed

• Search race condition: chapters fully preloaded before search is enabled
• TOC bar gap: sidebar and layout dynamically adjust when TOC bar is hidden (56px) vs visible (92px)
• Config loading: response status checked before parsing JSON
• Copy buttons always visible on code blocks with proper light/dark mode support

Changed

• Removed unused global config variable
• Replaced DOM-based escapeHtml with efficient string replacement

1.0.0 - 2026-03-30

Added

• Standalone drop-in documentation system (no build step, no npm)
• Sidebar navigation with nested chapters
• Sticky TOC bar with scroll spy for in-page sections
• Full-text search across all chapters (Ctrl+K / Cmd+K)
• Dark / light theme with system preference detection
• Syntax highlighting via highlight.js with copy buttons
• Previous / next chapter navigation
• Mobile responsive with sidebar overlay
• Customizable accent color via chapters.json

Fixed

• TOC bar: reset state on chapter change, correct scroll offset
• Light mode code blocks and prev/next navigation bug
• Dark mode: neutral gray/black instead of blue-tinted Catppuccin

This site is open source. Improve this page.