Release of Version 1.3.0 #156

Merged
miko merged 31 commits from development into master 2026-11-06 15:21:24 +01:00
Owner

Version 1.3.0

A handbook for readers, authors and admins, problem reports on guides, and references to other guides, categories and pages.

added

  • Problem reports: readers, guests included, report that a guide or one of its steps is wrong or unclear, with the flag beside a step's heading or the link at the end of the guide; authors find the reports on the guides they may edit under Problem reports in the menu under their name, admins all of them in the admin menu, each with the number still open, and mark them resolved; spam is kept out by a hidden honeypot field and a limit of five reports per fifteen minutes per guest address or user (#99)
  • Emails: with an SMTP server set in the settings' new section Email, which sends a test email to check it, a guide's owner gets an email about every new problem report, in their language, or the admins once the owner is no longer an author; without one, kataba sends no mail; the SMTP password is stored encrypted with AUTH_SECRET (#99)
  • Handbook: kataba has a handbook at https://pages.mike-ochmann.de/kataba/, with a user handbook for readers and authors and an administration handbook for admins and for running an instance, in kataba's look in light and dark mode; it is built from handbook/ with Zensical and published with every release (#138)
  • Help: signed-in users find Help in the menu under their name, opening the user handbook, and admins find the administration handbook in the admin menu; both open in a new tab, guests see neither (#142)
  • References: in a guide's description and step content, a category's description and a page's content, authors turn selected words into a reference to a guide, category or page they pick by searching, with the new bookmark in the inline toolbar; readers see the target's current title, with a card of its image and title on hover, and the plain text where the target is gone or hidden from them; PDFs link to the full address, and exported guides keep their references (#101)

changed

  • Backups also hold the problem reports; older backups are restored without any (#99)
  • The address /reports now belongs to kataba: a page with the slug reports is no longer reachable there (#99)
  • README: installing, Docker, configuration, Authentik, roles and backup and restore moved into the handbook's administration part, which is now the single place for them; the README keeps a short Docker Compose quickstart and links into the handbook (#139)
  • Settings: the settings page is split into the tabs General, Content, Email and Access, each saving only its own settings, with more space between fields and sections (#149)

fixed

  • Rich text editor: in dark mode, the buttons of the inline toolbar (italic, link, inline code, reference) no longer turn white on white under the pointer
  • References: the list of guides, categories and pages to pick from in the inline toolbar is three times as wide, so their titles no longer wrap early; on a phone it takes the screen's width (#152)
## Version 1.3.0 A handbook for readers, authors and admins, problem reports on guides, and references to other guides, categories and pages. ### added * Problem reports: readers, guests included, report that a guide or one of its steps is wrong or unclear, with the flag beside a step's heading or the link at the end of the guide; authors find the reports on the guides they may edit under **Problem reports** in the menu under their name, admins all of them in the admin menu, each with the number still open, and mark them resolved; spam is kept out by a hidden honeypot field and a limit of five reports per fifteen minutes per guest address or user (#99) * Emails: with an SMTP server set in the settings' new section **Email**, which sends a test email to check it, a guide's owner gets an email about every new problem report, in their language, or the admins once the owner is no longer an author; without one, kataba sends no mail; the SMTP password is stored encrypted with `AUTH_SECRET` (#99) * Handbook: kataba has a handbook at https://pages.mike-ochmann.de/kataba/, with a user handbook for readers and authors and an administration handbook for admins and for running an instance, in kataba's look in light and dark mode; it is built from `handbook/` with Zensical and published with every release (#138) * Help: signed-in users find **Help** in the menu under their name, opening the user handbook, and admins find the administration handbook in the admin menu; both open in a new tab, guests see neither (#142) * References: in a guide's description and step content, a category's description and a page's content, authors turn selected words into a reference to a guide, category or page they pick by searching, with the new bookmark in the inline toolbar; readers see the target's current title, with a card of its image and title on hover, and the plain text where the target is gone or hidden from them; PDFs link to the full address, and exported guides keep their references (#101) ### changed * Backups also hold the problem reports; older backups are restored without any (#99) * The address `/reports` now belongs to kataba: a page with the slug `reports` is no longer reachable there (#99) * README: installing, Docker, configuration, Authentik, roles and backup and restore moved into the handbook's administration part, which is now the single place for them; the README keeps a short Docker Compose quickstart and links into the handbook (#139) * Settings: the settings page is split into the tabs **General**, **Content**, **Email** and **Access**, each saving only its own settings, with more space between fields and sections (#149) ### fixed * Rich text editor: in dark mode, the buttons of the inline toolbar (italic, link, inline code, reference) no longer turn white on white under the pointer * References: the list of guides, categories and pages to pick from in the inline toolbar is three times as wide, so their titles no longer wrap early; on a phone it takes the screen's width (#152)
miko added 31 commits 2026-11-06 15:20:44 +01:00
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #143
npm run handbook:screenshots seeds the e2e database with a makerspace
example instance (written as a backup and restored like one), builds and
starts kataba on port 3200 and writes 30 PNGs to
handbook/docs/assets/screenshots/ in light mode, English, at 1280 x 800.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #144
Reading guides covers finding guides (categories, search, the menu),
reading one (steps, step images and annotations, step lines, callouts),
the step-by-step view, print and PDF, labels, signing in, language and
theme. Writing guides covers creating a guide, the editor, steps, step
images, step lines and step content, annotations, the properties tabs,
drafts, publishing, the working copy and version history, visibility,
ownership and wiki mode, and guide packages; illustrated with the
screenshots from #140.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #145
The administration handbook gets a page per topic: categories, pages and
the home page, the menu, settings, importing and restoring guides, backup
and restore, installation, Docker, configuration, sign-in and roles, and
updating. The README keeps a short Docker Compose quickstart and links
into the handbook instead of its own operator sections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #146
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #147
Readers, guests included, report that a guide or one of its steps is
wrong or unclear; owners and wiki-mode authors see the reports on their
guides at /reports, admins all of them, with a badge of the open ones,
and mark them resolved. A honeypot and an in-memory rate limit keep spam
out; with SMTP_URL set, the owner (or the admins) get an email. Reports
are part of instance backups. Decisions in ADR-0025.

nodemailer 10 makes npm nest @auth/core under next-auth (its optional
nodemailer peer range stops at 8), so the JWT augmentation now targets
next-auth/jwt, as Auth.js v5 documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admins set the SMTP server under Settings → Email: host, port, security
(TLS, STARTTLS, none), user, password and sender, and send themselves a
test email that shows the server's error if it fails. Without a host,
kataba sends no emails, as before.

The password is stored beside the other settings, and so in backups,
sealed with AES-256-GCM under a key derived from AUTH_SECRET, and never
sent back to the browser; an empty field keeps it. After a restore into an
instance with another AUTH_SECRET it cannot be opened, and the settings
ask for it again (ADR-0025).

SMTP_URL and SMTP_FROM are gone from .env.example, the Compose file and
the handbook; they were never released.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #148
Authors select words in a guide's description or step content, a
category's description or a page's content, choose the bookmark in the
inline toolbar and pick a guide, category or page by searching its
title. The reference is stored by id in the inline text, as
<span data-ref="kind:id">, with the title it was written with.

Readers see the target's current title, as lists show it, linked, with a
card of its cover or category image and title on hover (plain CSS). Every
page resolves its references for the reader; a target that is gone or
hidden from them shows the stored text, unlinked. PDFs link to the
absolute address; guide packages and backups keep references as they are.
Decisions in ADR-0026.

The e2e helpers for the rich text editor move to e2e/richTextEditor.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Editor.js hard-codes a light background on its inline tool buttons under
the pointer, so the icons of italic, link, inline code and reference,
drawn in the theme's text colour, turned white on white in dark mode.
They now take the theme's sunken surface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The editor's reference search matched a guide's working copy title and
any version's, so an author could find a published guide by a rename
that was not published yet, under another title (ADR-0020). It now
offers only what matches the title readers see.

Cleanups from the review: the referenced guides' query and cover mapping
live in one place (readReferencedGuides); a reference's kind and id are
one type (ReferenceTarget); the resolved references' types and the empty
map sit in a module of their own without dependencies, which the client
renderers and the PDF share; alignment and import order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #150
npm run build:nodb builds like the Docker image, with an empty
DATABASE_URL, into .next-nodb; there, any query fails with a message
naming the cause instead of the driver's connection string error. The
release skill runs it first, so a page that reaches the database while
prerendering (#121, #134) stops the release instead of the image build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #153
The settings page gets the tabs General, Content, Email and Access, with
more space between fields and sections. Every tab has a form of its own;
saving one leaves the other tabs' settings as they are, and what is typed
in a tab survives switching to another.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The settings' tabs and the sidebar's share TabList and tabForKey instead of
each keeping a copy of the keyboard handling and the tab buttons. The
settings form binds each tab's save from SETTINGS_TABS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #154
Editor.js renders the reference tool's search in a nested popover fixed
at --width (200px), so the search's own 18rem never applied and titles
wrapped at 186px. The popover now takes the search's width, 36rem at
most and never wider than the viewport.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #155
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit b1856da41d into master 2026-11-06 15:21:24 +01:00
Sign in to join this conversation.
No reviewers
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
MassiveDynamic/kataba!156
No description provided.