zombor/pergamum
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages 2 Wiki Activity Actions

docs(homepage): replace AI-generated feature-box layout with human voice (bookshelf-tc4u) #839

Open
zombor wants to merge 2 commits from bd-bookshelf-tc4u into main
pull from: bd-bookshelf-tc4u
merge into: zombor:main
Conversation 8 Commits 2 Files changed 1 +33 -71
zombor commented 2026-06-29 13:18:47 +00:00
Owner
Copy link

Summary

Rewrite docs/content/_index.md so the homepage reads like a real person built this, not templated scaffolding.

  • Hero: kept the hextra layout, Get Started + View Source CTAs, screenshots placeholder. New headline: "A self-hosted library server built for large collections." New subtitle leads with WHY — Grimmory falls over at 50k books; this is built for 250,000+.
  • Body: two paragraphs of prose explaining the origin and the design approach, replacing the "Why Pergamum" triadic feature-card grid.
  • What you can do: six short paragraphs in plain language covering the real feature set (reader, BookDrop, metadata locking, magic shelves, multi-user, bulk ops) — no card grid, no uniform cadence bullets, no AI-pattern superlatives.
  • Quick start + Open source: kept, lightly tightened.
  • Removed: the 3-card "Why Pergamum" grid and the 11-card "Features" grid entirely.

Hugo builds clean (81 pages, 0 errors).

Test plan

  • hugo --source docs --minify builds with 0 errors
  • Homepage renders with correct hero text, prose sections, Quick start code block, Open source callout
  • Rendered screenshot posted below

Screenshots

Screenshot captured locally — full-page render of the new homepage:

(See PR comment for rendered screenshot — attaching via comment API after PR creation.)

Closes bead bookshelf-tc4u on merge.

## Summary Rewrite `docs/content/_index.md` so the homepage reads like a real person built this, not templated scaffolding. - **Hero**: kept the hextra layout, Get Started + View Source CTAs, screenshots placeholder. New headline: "A self-hosted library server built for large collections." New subtitle leads with WHY — Grimmory falls over at 50k books; this is built for 250,000+. - **Body**: two paragraphs of prose explaining the origin and the design approach, replacing the "Why Pergamum" triadic feature-card grid. - **What you can do**: six short paragraphs in plain language covering the real feature set (reader, BookDrop, metadata locking, magic shelves, multi-user, bulk ops) — no card grid, no uniform cadence bullets, no AI-pattern superlatives. - **Quick start + Open source**: kept, lightly tightened. - Removed: the 3-card "Why Pergamum" grid and the 11-card "Features" grid entirely. Hugo builds clean (`81 pages, 0 errors`). ## Test plan - [ ] `hugo --source docs --minify` builds with 0 errors - [ ] Homepage renders with correct hero text, prose sections, Quick start code block, Open source callout - [ ] Rendered screenshot posted below ## Screenshots Screenshot captured locally — full-page render of the new homepage: (See PR comment for rendered screenshot — attaching via comment API after PR creation.) Closes bead bookshelf-tc4u on merge.
homepage_full.png
332 KiB
wf-detail-older-execution.png
55 KiB
recompute-match-score-kebab-open.png
109 KiB
homepage_v2_full.png
313 KiB
wf-detail-older-execution.png
55 KiB
recompute-match-score-kebab-open.png
109 KiB
homepage_full.png wf-detail-older-execution.png recompute-match-score-kebab-open.png homepage_v2_full.png wf-detail-older-execution.png recompute-match-score-kebab-open.png
docs(homepage): replace AI-generated feature-box layout with human voice (bookshelf-tc4u)
All checks were successful
/ Hugo build (pull_request) Successful in 1m12s
Details
/ JS Unit Tests (pull_request) Successful in 1m33s
Details
/ Lint (pull_request) Successful in 3m13s
Details
/ E2E API (pull_request) Successful in 2m20s
Details
/ Integration (pull_request) Successful in 3m34s
Details
/ E2E Browser (pull_request) Successful in 3m19s
Details
/ Test (pull_request) Successful in 4m52s
Details
6800411803
 
Rewrite docs/content/_index.md so it reads like a person wrote it:

- Lead with why: Grimmory falls over at 50k books; this is the Go rewrite
  built for 250,000+ from day one
- Replace the generic hero/feature-grid/quick-start scaffolding with
  narrative prose + a short tight list of what you can actually do
- Remove the two feature-card grids (11 + 3 cards) and the "Why Pergamum"
  triads that triggered the AI-generated complaint
- Keep hextra theme, Get Started and View Source CTAs, screenshots
  placeholder comment (hj9.1 follow-up), and quick-start block
- Hugo builds clean (81 pages, 0 errors)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
zombor commented 2026-06-29 13:19:07 +00:00
Author
Owner
Copy link

Rendered screenshot

New homepage — full page render:

Homepage full render

Hero shows the new "large collections" headline + Grimmory-origin subtitle. Body has two prose paragraphs + the "What you can do with it" section as six short paragraphs (no card grid). Quick start and Open source sections below.

## Rendered screenshot New homepage — full page render: ![Homepage full render](https://git.zombor.net/attachments/fa742e23-b0de-47eb-802e-2e0f729ccdc9) Hero shows the new "large collections" headline + Grimmory-origin subtitle. Body has two prose paragraphs + the "What you can do with it" section as six short paragraphs (no card grid). Quick start and Open source sections below.
forgejo-actions commented 2026-06-29 13:25:07 +00:00
Copy link

Workflow Detail page screenshot (wf-detail-older-execution)

Older completed ContinueAsNew epoch detail — execution ID and state visible, Cancel absent.

wf-detail-older-execution

**Workflow Detail page screenshot** (wf-detail-older-execution) Older completed ContinueAsNew epoch detail — execution ID and state visible, Cancel absent. ![wf-detail-older-execution](/attachments/6b2f406e-c3d3-4201-9c25-0481af4a52d9)
forgejo-actions commented 2026-06-29 13:25:20 +00:00
Copy link

Recompute Match Score — kebab open screenshot (recompute-match-score-kebab-open)

recompute-match-score-kebab-open

**Recompute Match Score — kebab open screenshot** (recompute-match-score-kebab-open) ![recompute-match-score-kebab-open](/attachments/87052218-9022-42b9-bfc4-6c5f78b98ef1)
zombor force-pushed bd-bookshelf-tc4u from 6800411803
All checks were successful
/ Hugo build (pull_request) Successful in 1m12s
Details
/ JS Unit Tests (pull_request) Successful in 1m33s
Details
/ Lint (pull_request) Successful in 3m13s
Details
/ E2E API (pull_request) Successful in 2m20s
Details
/ Integration (pull_request) Successful in 3m34s
Details
/ E2E Browser (pull_request) Successful in 3m19s
Details
/ Test (pull_request) Successful in 4m52s
Details
to b439a45e71
All checks were successful
/ Hugo build (pull_request) Successful in 29s
Details
/ JS Unit Tests (pull_request) Successful in 40s
Details
/ E2E API (pull_request) Successful in 2m9s
Details
/ Lint (pull_request) Successful in 2m26s
Details
/ Integration (pull_request) Successful in 3m8s
Details
/ E2E Browser (pull_request) Successful in 3m15s
Details
/ Test (pull_request) Successful in 3m53s
Details
2026-06-29 14:17:30 +00:00 Compare
zombor commented 2026-06-29 14:17:40 +00:00
Author
Owner
Copy link

Revised screenshot (v2)

Fixed two issues from the first version:

  1. Visual design restored — hextra feature-card grid is back with the human copy
  2. Grimmory positioning fixed — hero subtitle now describes Pergamum on its own terms; Grimmory moved to a warm lower "Built on Grimmory's data model" section

Homepage v2 full render

## Revised screenshot (v2) Fixed two issues from the first version: 1. **Visual design restored** — hextra feature-card grid is back with the human copy 2. **Grimmory positioning fixed** — hero subtitle now describes Pergamum on its own terms; Grimmory moved to a warm lower "Built on Grimmory's data model" section ![Homepage v2 full render](https://git.zombor.net/attachments/83cd9174-bdbb-4d8d-a86b-8e412ea673a6)
forgejo-actions commented 2026-06-29 14:20:15 +00:00
Copy link

Workflow Detail page screenshot (wf-detail-older-execution)

Older completed ContinueAsNew epoch detail — execution ID and state visible, Cancel absent.

wf-detail-older-execution

**Workflow Detail page screenshot** (wf-detail-older-execution) Older completed ContinueAsNew epoch detail — execution ID and state visible, Cancel absent. ![wf-detail-older-execution](/attachments/82055b9d-31a8-4258-bd11-49b4b2b1f518)
forgejo-actions commented 2026-06-29 14:20:21 +00:00
Copy link

Recompute Match Score — kebab open screenshot (recompute-match-score-kebab-open)

recompute-match-score-kebab-open

**Recompute Match Score — kebab open screenshot** (recompute-match-score-kebab-open) ![recompute-match-score-kebab-open](/attachments/27a70e34-90a8-444b-91e1-27fa5591a332)
zombor force-pushed bd-bookshelf-tc4u from b439a45e71
All checks were successful
/ Hugo build (pull_request) Successful in 29s
Details
/ JS Unit Tests (pull_request) Successful in 40s
Details
/ E2E API (pull_request) Successful in 2m9s
Details
/ Lint (pull_request) Successful in 2m26s
Details
/ Integration (pull_request) Successful in 3m8s
Details
/ E2E Browser (pull_request) Successful in 3m15s
Details
/ Test (pull_request) Successful in 3m53s
Details
to a9923bc945
Some checks failed
/ Hugo build (pull_request) Successful in 2m17s
Details
/ Test Race (pull_request) Successful in 6m10s
Details
/ E2E API (pull_request) Successful in 4m55s
Details
/ JS Unit Tests (pull_request) Successful in 4m30s
Details
/ Coverage (pull_request) Successful in 7m50s
Details
/ Lint (pull_request) Successful in 10m28s
Details
/ E2E Browser (pull_request) Successful in 9m53s
Details
/ Integration (pull_request) Failing after 14m7s
Details
2026-08-05 15:06:16 +00:00 Compare
zombor commented 2026-08-05 20:21:26 +00:00
Author
Owner
Copy link

Security Review — PR #839 (bookshelf-tc4u)

Scope: docs/content/_index.md only — Hugo Markdown homepage copy rewrite.

No production or runtime code is touched. Assessment covers: information disclosure, injected markup, and secrets/PII exposure in the docs content.

Findings:

None.

  • No production/runtime code impact. The diff is purely Hugo-flavored Markdown rendered by the static docs site; it does not affect any Go handler, template, SQL query, workflow, or configuration.
  • No injected HTML/script. The only raw HTML in the file is pre-existing <div> wrapper elements carrying Hextra CSS utility classes (hx:mt-16 etc.). No new <script>, inline event handlers, or javascript: URLs were added.
  • No secrets or sensitive implementation details leaked. The copy references public feature names (BookDrop, Magic Shelves, Hardcover, Google Books, Open Library, Kobo, KOReader) and the public Forgejo URL — all intentionally public. No internal hostnames, tokens, API keys, DSNs, file paths, or architecture details that could aid an attacker appear in the diff.
  • No XSS surface. Hugo's Markdown renderer escapes user-supplied content at build time; this is static documentation, not server-rendered user input.
  • The warning callout accurately describes API stability vs data stability — no security-relevant inaccuracy.

REVIEW VERDICT: 0 blocker, 0 major, 0 minor

## Security Review — PR #839 (bookshelf-tc4u) **Scope:** `docs/content/_index.md` only — Hugo Markdown homepage copy rewrite. No production or runtime code is touched. Assessment covers: information disclosure, injected markup, and secrets/PII exposure in the docs content. **Findings:** None. - **No production/runtime code impact.** The diff is purely Hugo-flavored Markdown rendered by the static docs site; it does not affect any Go handler, template, SQL query, workflow, or configuration. - **No injected HTML/script.** The only raw HTML in the file is pre-existing `<div>` wrapper elements carrying Hextra CSS utility classes (`hx:mt-16` etc.). No new `<script>`, inline event handlers, or `javascript:` URLs were added. - **No secrets or sensitive implementation details leaked.** The copy references public feature names (BookDrop, Magic Shelves, Hardcover, Google Books, Open Library, Kobo, KOReader) and the public Forgejo URL — all intentionally public. No internal hostnames, tokens, API keys, DSNs, file paths, or architecture details that could aid an attacker appear in the diff. - **No XSS surface.** Hugo's Markdown renderer escapes user-supplied content at build time; this is static documentation, not server-rendered user input. - **The warning callout** accurately describes API stability vs data stability — no security-relevant inaccuracy. REVIEW VERDICT: 0 blocker, 0 major, 0 minor
zombor commented 2026-08-05 20:22:51 +00:00
Author
Owner
Copy link

Code Review — bookshelf-tc4u (docs/_index.md rewrite)

Scope: docs-only PR, one file (+42/-80). Reviewing for end-user focus, absence of source/internal references, Hugo correctness, link validity, and accuracy.

[MINOR] docs/content/_index.md:78 — "Bulk operations" card links to /docs/importing/ but the authoritative page is /docs/organizing/bulk-operations.md
The feature card titled "Bulk operations that don't block you" points to /docs/importing/, which is the BookDrop/import section. The actual bulk operations documentation is at /docs/organizing/bulk-operations.md. This mismatch was already present on main (not introduced by this PR), so it is not a regression, but the PR presents an opportunity to correct it in the same edit pass. Suggested fix: change link="/docs/importing/" to link="/docs/organizing/" on that card.

Positive findings (no findings needed, but noting quality):

  • End-user focus: fully compliant. Every card and section describes what the user can do or see, not how it is implemented internally. No file:line citations, no internal field names, no Go symbol references anywhere in the diff.
  •   entities in hero-headline: safe. The hextra/hero-headline shortcode runs its inner content through {{ .Inner | markdownify }}, which preserves HTML entities. The three &nbsp; in the headline will render as non-breaking spaces as intended.
  • Hugo frontmatter/shortcodes: all shortcodes are syntactically valid ({{< >}} paired correctly; no unclosed blocks). Frontmatter fields (title, layout) are unchanged and correct.
  • Links: all six /docs/* link targets (/docs/reading/, /docs/importing/, /docs/metadata/, /docs/organizing/, /docs/accounts-access/, /docs/start-here/) resolve to existing content sections in the repository. The bare-URL link in the Open Source section (git.zombor.net/zombor/pergamum) works as standard Markdown hyperlink syntax.
  • Accuracy: the Grimmory compatibility paragraph ("same table names, same folder layout, same cover paths / no conversion step") matches the project's own stated compatibility goal. The callout box accurately narrows the stability claim to on-disk data + DB layout while flagging the HTTP/JSON API as potentially changing.
  • Voice/style: consistently human, concrete, and end-user-oriented throughout. No AI-generic superlatives. The feature grid consolidation from 11 cards to 6 is well-chosen — the removed features (Reading Stats, Notebook, Similar Books, Comics, Audiobooks, Audit Log) are legitimately secondary discovery items.

REVIEW VERDICT: 0 blocker, 0 major, 1 minor

## Code Review — bookshelf-tc4u (docs/_index.md rewrite) **Scope:** docs-only PR, one file (+42/-80). Reviewing for end-user focus, absence of source/internal references, Hugo correctness, link validity, and accuracy. --- [MINOR] docs/content/_index.md:78 — "Bulk operations" card links to `/docs/importing/` but the authoritative page is `/docs/organizing/bulk-operations.md` The feature card titled "Bulk operations that don't block you" points to `/docs/importing/`, which is the BookDrop/import section. The actual bulk operations documentation is at `/docs/organizing/bulk-operations.md`. This mismatch was already present on `main` (not introduced by this PR), so it is not a regression, but the PR presents an opportunity to correct it in the same edit pass. Suggested fix: change `link="/docs/importing/"` to `link="/docs/organizing/"` on that card. --- **Positive findings (no findings needed, but noting quality):** - **End-user focus:** fully compliant. Every card and section describes what the user can do or see, not how it is implemented internally. No file:line citations, no internal field names, no Go symbol references anywhere in the diff. - **&nbsp; entities in hero-headline:** safe. The hextra/hero-headline shortcode runs its inner content through `{{ .Inner | markdownify }}`, which preserves HTML entities. The three `&nbsp;` in the headline will render as non-breaking spaces as intended. - **Hugo frontmatter/shortcodes:** all shortcodes are syntactically valid (`{{< >}}` paired correctly; no unclosed blocks). Frontmatter fields (`title`, `layout`) are unchanged and correct. - **Links:** all six `/docs/*` link targets (`/docs/reading/`, `/docs/importing/`, `/docs/metadata/`, `/docs/organizing/`, `/docs/accounts-access/`, `/docs/start-here/`) resolve to existing content sections in the repository. The bare-URL link in the Open Source section (`git.zombor.net/zombor/pergamum`) works as standard Markdown hyperlink syntax. - **Accuracy:** the Grimmory compatibility paragraph ("same table names, same folder layout, same cover paths / no conversion step") matches the project's own stated compatibility goal. The callout box accurately narrows the stability claim to on-disk data + DB layout while flagging the HTTP/JSON API as potentially changing. - **Voice/style:** consistently human, concrete, and end-user-oriented throughout. No AI-generic superlatives. The feature grid consolidation from 11 cards to 6 is well-chosen — the removed features (Reading Stats, Notebook, Similar Books, Comics, Audiobooks, Audit Log) are legitimately secondary discovery items. --- REVIEW VERDICT: 0 blocker, 0 major, 1 minor
Some checks failed
/ Hugo build (pull_request) Successful in 2m17s
Details
/ Test Race (pull_request) Successful in 6m10s
Required
Details
/ E2E API (pull_request) Successful in 4m55s
Required
Details
/ JS Unit Tests (pull_request) Successful in 4m30s
Details
/ Coverage (pull_request) Successful in 7m50s
Required
Details
/ Lint (pull_request) Successful in 10m28s
Required
Details
/ E2E Browser (pull_request) Successful in 9m53s
Required
Details
/ Integration (pull_request) Failing after 14m7s
Required
Details
This pull request is blocked because it's outdated.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin bd-bookshelf-tc4u:bd-bookshelf-tc4u
git switch bd-bookshelf-tc4u
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
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
zombor/pergamum!839
No description provided.