docs: slim index hub, cut em-dash spam, fix flat docs-html README links #86

Merged
yuuhikaze merged 1 commit from docs/index-polish into master 2026-10-25 07:54:23 -05:00
Owner

Owner feedback, three parts:

1. docs/index.md redundancy + broken README link

  • The intro paragraph restated the README overview and the Screens table duplicated the README's; the index is now a true hub page: a two-sentence orienting paragraph plus the link lists. The Screens table is gone (the captures live in the README).
  • The [README](../README.md) link rendered broken in compiled docs-html because every page compiles flat into docs-html/, so ../README.md pointed outside the site.

2. Em-dash overuse

  • Prose pass across README.md and docs/*.md: 76 em dashes down to 7, and the 7 that remain are all inside code blocks (mermaid diagrams, the repo-layout block, a shell comment) that must stay byte-identical. Dashes became commas, colons, parentheses, semicolons or restructured sentences; no technical content, links, image paths or code blocks changed.

3. Consistency

  • Dropped the stale "the interface is Spanish/English" phrasing along with the rest of the index intro; checked the other pages against the current feature set (per-section tutorials, splash/login, anonymous-by-default, opt-in SSO) — no other drift found, no new marketing added.

Build change (filter)

  • New .tern/docs-html.lua, wired into the pandoc/docs profile options in .tern/config.toml (between the mermaid filter and md-links.lua). It runs on docs pages only and rewrites link targets before md-links.lua swaps the extension:
    • ../README.md and README.md → README.md (→ sibling README.html)
    • docs/*.md self-references → *.md (→ sibling *.html)
  • The pandoc/readme profile and .tern/readme-html.lua are untouched; docs-html/README.html's link/image treatment is verified byte-identical to master. Raw markdown keeps plain repo paths (../README.md in docs/index.md is correct on the forge); the filter only affects compiled docs-html. The filter lives directly in .tern/ (not .tern/data/) so tern --update cannot wipe it.

Verification

  • tern --update + tern clean; docs-html/index.html README link is href="README.html" (same directory).
  • No ../README* or href="docs/…" targets left anywhere in docs-html/.
  • README.html href/src sets identical to master's build (docs pages carry no <img> after the table removal; mermaid script src only).

Closes nothing; implements the owner's review feedback on docs structure, dash usage and the compiled-docs link fix.

Owner feedback, three parts: **1. `docs/index.md` redundancy + broken README link** - The intro paragraph restated the README overview and the Screens table duplicated the README's; the index is now a true hub page: a two-sentence orienting paragraph plus the link lists. The Screens table is gone (the captures live in the README). - The `[README](../README.md)` link rendered broken in compiled docs-html because every page compiles flat into `docs-html/`, so `../README.md` pointed outside the site. **2. Em-dash overuse** - Prose pass across `README.md` and `docs/*.md`: 76 em dashes down to 7, and the 7 that remain are all inside code blocks (mermaid diagrams, the repo-layout block, a shell comment) that must stay byte-identical. Dashes became commas, colons, parentheses, semicolons or restructured sentences; no technical content, links, image paths or code blocks changed. **3. Consistency** - Dropped the stale "the interface is Spanish/English" phrasing along with the rest of the index intro; checked the other pages against the current feature set (per-section tutorials, splash/login, anonymous-by-default, opt-in SSO) — no other drift found, no new marketing added. ## Build change (filter) - New `.tern/docs-html.lua`, wired into the `pandoc/docs` profile options in `.tern/config.toml` (between the mermaid filter and `md-links.lua`). It runs on docs pages only and rewrites link targets before `md-links.lua` swaps the extension: - `../README.md` and `README.md` → `README.md` (→ sibling `README.html`) - `docs/*.md` self-references → `*.md` (→ sibling `*.html`) - The `pandoc/readme` profile and `.tern/readme-html.lua` are untouched; `docs-html/README.html`'s link/image treatment is verified byte-identical to master. Raw markdown keeps plain repo paths (`../README.md` in `docs/index.md` is correct on the forge); the filter only affects compiled docs-html. The filter lives directly in `.tern/` (not `.tern/data/`) so `tern --update` cannot wipe it. ## Verification - `tern --update` + `tern` clean; `docs-html/index.html` README link is `href="README.html"` (same directory). - No `../README*` or `href="docs/…"` targets left anywhere in `docs-html/`. - `README.html` href/src sets identical to master's build (docs pages carry no `<img>` after the table removal; mermaid script src only). Closes nothing; implements the owner's review feedback on docs structure, dash usage and the compiled-docs link fix.
docs: slim index hub, cut em-dash spam, fix flat docs-html README links
All checks were successful
ci / web (pull_request) Successful in 41s
ci / rust (pull_request) Successful in 2m6s
ci / image (oven/bun:1.4.2-debian=docker-image://git.yhkze.net/actions/bun:1.4.2-debian node:22-bookworm-slim=docker-image://git.yhkze.net/actions/node:22-bookworm-slim , web, web.Dockerfile, rgxr-web) (pull_request) Has been skipped
ci / image (rust:1-slim-bookworm=docker-image://git.yhkze.net/actions/rust:1-slim-bookworm debian:bookworm-slim=docker-image://git.yhkze.net/actions/debian:bookworm-slim , ., api.Dockerfile, rgxr-api) (pull_request) Has been skipped
c62bfe06f5
Owner feedback, three parts:

- docs/index.md restated the README overview and duplicated its Screens
  table; it is now a true hub page (short orienting paragraph plus the
  link lists only).
- The [README](../README.md) link rendered broken in compiled docs-html:
  all pages compile flat into docs-html/, so ../README.md pointed
  outside the site. New .tern/docs-html.lua, wired into the pandoc/docs
  profile in .tern/config.toml, rewrites in docs pages: ../README.md and
  README.md -> README.html, and docs/*.md self-references -> sibling
  .html (normalized to .md before md-links.lua does the extension swap).
  The pandoc/readme profile and .tern/readme-html.lua are untouched;
  README.html's link/image treatment is byte-identical to before. Raw
  markdown keeps plain repo paths for the forge.
- Prose pass across README.md and docs/*.md: 76 em dashes down to 7,
  all of the remainder inside code blocks (mermaid diagrams, the repo
  layout block, a shell comment), which stay byte-identical. Replaced
  with commas, colons, parentheses, semicolons or restructured
  sentences; no technical content, links or paths changed.

Co-Authored-By: GLM (OpenCode) <dev@yhkze.net>
yuuhikaze merged commit 8ad65bb495 into master 2026-10-25 07:54:23 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
k8s-services/rgxr!86
No description provided.