• v1.3.0 b1856da41d

    Version 1.3.0 Stable

    miko released this 2026-11-06 15:21:32 +01:00 | 0 commits to master since this release

    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)
    Downloads
  • v1.2.0 c4328f617b

    Version 1.2.0 Stable

    miko released this 2026-11-05 21:46:13 +01:00 | 32 commits to master since this release

    Guides get working copies with publishing and a version history, print, PDF and QR code labels, a step-by-step view, difficulty, duration, protective equipment, licenses and attachments, plus export, import and duplication of guides, Atom feeds, instance backups and a reworked guide editor.

    added

    • Print: a guide prints without the titlebar, breadcrumb and buttons, with all of a step's images and their annotations, always light, and with an attribution line at the end: the instance, the guide's address, its owner and last edit, and kataba; "Print" next to the guide opens the print dialog (#90)
    • PDF download: "Download PDF" next to a guide, for everyone who may read it, gives an A4 PDF with the logo and instance name at the top of every page, page numbers, the description and all steps with their images and annotations, and the same attribution line at the end; its text is set in Inter, with Noto Sans CJK for Chinese, Japanese and Korean (#90)
    • Difficulty and estimated duration: a guide can have a difficulty (easy, medium, hard) and an estimated duration in hours and minutes, set in its properties; both are optional and show as badges in the guide's header, on its tile in the category grid, and in print and PDF (#92)
    • Protective equipment: a guide can call for any of eight kinds of personal protective equipment (eye, face, hearing and respiratory protection, safety gloves, safety shoes, protective clothing, tied-back hair and no jewellery), ticked in its properties; each shows as a pictogram in the style of an ISO 7010 mandatory sign with its name, prominently at the top of the guide and in print and PDF (#95)
    • Working copy and publishing: edits to a published guide go to its working copy, and readers keep seeing the latest published version until someone publishes again; the editor shows "Unpublished changes" with "Publish" (with an optional note) and "Discard changes", and the guide page gives editors a link to preview the working copy. Every publish keeps a version; published guides get their first version when the server starts (#106)
    • Version History: "Version History" in a guide's editor shows every published version, read-only and complete as readers saw it, with when, by whom and with which note it was published; a slider with a mark per version (and a last mark for the working copy's unpublished changes) moves between them. "Restore this version" replaces the working copy with the selected version, asking first if that loses unpublished changes; it publishes nothing (#107)
    • License: every guide has a license, chosen in its properties from Public Domain, CC0 1.0, the six Creative Commons 4.0 licenses and "All rights reserved"; it shows, linked to its text, in the guide's header and in the attribution line of print and PDF. New guides start with the default license, a new setting ("All rights reserved" at first); changing it leaves existing guides as they are, and existing guides got "All rights reserved". The license is part of a guide's versions (#103)
    • Atom feeds: /feed lists newly published and changed guides of the whole instance, /feed/<category path> those of a category and its subcategories, e.g. to post them into a Matrix or Discord channel. Each guide is one entry with its title, cover image, description, who published it and when; every new version updates it, with its change note in the summary, while saved changes to the working copy never show. Only guides guests may see appear, the 50 most recently published; pages link to the instance's feed and category pages to theirs for feed readers (#104)
    • Attachments: files can be attached to a guide for download, such as 3D models, drawings, G-code, manuals or firmware, several per guide, each with a name and an optional description; they are added (chosen or dropped), renamed and removed in the guide's properties and are part of its versions. The guide lists them with type and size below its description, and print and PDF name them with a hint where to download them. Attachments are always downloaded, never opened in the browser; programs and scripts (by extension, and every Windows program by its header) are refused. The largest attachment is a new setting, 50 MB at first (#97)
    • Export and import of guides: "Export" in a guide's editor downloads its working copy as a ZIP with all images and attachments, for everyone who may edit it; history, owner, visibility, wiki mode and menu entries stay behind. Admins import such a package under "Import guide" in the admin menu or on a category page, into a category of their choice, as a public draft of their own without wiki mode that keeps the package's license, protective equipment and attachments. Its content is checked like typed-in content, and packages from a newer kataba are refused (#108)
    • Step-by-Step View: "Step by step" in a guide's reading view opens it one step per screen, filling the window, for a tablet or phone at the machine: a start screen like a title slide, the title large and centred over the darkened cover image, with the number of steps, difficulty, duration, protective equipment, description and attachments; then each step using the whole window, its image as large as the height allows with its annotations, and its step lines and content beside it on wide screens, below it on narrow ones. Readers move by swiping, by the arrow keys or by large buttons, with "Step 4 of 12" and a progress bar at the top, and every screen has its own address (/guides/<id>/steps/<n>). The screen stays on, the view can switch to full screen, and steps can be checked off; that progress is kept only in the browser and starts over once a new version is published. A guide titled "Steps", whose address ended in /steps, now reads at /steps-2 (#98)
    • Labels with QR codes: "QR code" next to a guide's "Print" and "Download PDF", and on every category page, downloads a label as a PDF for everyone who may see the guide or category, to stick on a machine, cabinet or tool wall: a QR code with the title, the kataba mark and the instance name, laid out beside the code on a landscape label and below it otherwise. The code leads to an address by id, /guides/<id> or the new /categories/<id>, which redirects to the category page, so it keeps working after renaming or moving; internal content needs signing in, as before. The label size is a new setting, 50 × 30 mm at first, from 30 × 20 mm. A guide titled "Label", whose address ended in /label, now reads at /label-2, and a page can no longer take the slug "categories" (#94)
    • Instance backup: "Download backup" in the admin menu downloads the whole instance as a ZIP, streamed as it is written: users with their last known role, settings, categories with their images, guides with their working copies, all versions and deleted guides, pages with their images, the menu, and every image and attachment. It shares the guide packages' format version. npm run restore -- <backup.zip> restores it on the command line in the container, only into an empty instance, keeping the ids of guides, categories and pages so links and QR code labels keep working; backups from a newer kataba are refused (#109)
    • Duplicating guides: "Duplicate" in a guide's reading view and editor copies its working copy, for every author and admin who may see the guide, with all steps, step lines, images, annotations, cover image, effort, protective equipment, license and attachments; images and attachments get files of their own, so deleting the original leaves the copy whole. The copy is a draft of whoever duplicated it, titled "Copy of …", in the same category with the same visibility and without wiki mode; versions, menu entries and the status stay with the original (#100)

    changed

    • Guide Actions Menu: in a guide's reading view, signed-in users find "QR code", "Duplicate", "Edit guide", "Unpublish" and "Delete guide" in a "…" menu next to "Print" and "Download PDF", so the row of buttons stays short; "Publish" stays a button. Guests keep "QR code" as a button (#124)
    • Saving in the guide editor: one "Save" button at the top of the sidebar (along the bottom edge on narrow screens) saves the open step, the title, language and description, and the properties together, in place of "Save step", "Save guide" and "Save properties"; Enter in a field saves too. Saving stays in the editor and says whether all changes are saved; a part that fails keeps its changes and error while the others are saved. Publishing from the editor saves first and leads to the reading view; discarding the unpublished changes shows the working copy afresh, so nothing discarded can be saved back. Leaving the editor with unsaved changes anywhere in it asks first (#125)
    • Guide editor sidebar: the properties are split into the tabs "General" (visibility, category, wiki mode, owner), "Details" (difficulty, estimated duration, protective equipment, license) and "Media" (cover image, attachments), with more whitespace between the fields; switching tabs keeps unsaved changes, a tab with unsaved changes is marked, the Save button saves all tabs together, and a failed save opens the tab with the unsaved changes (#126)
    • Media buttons in the guide editor: the buttons for the cover image (and a category's image) and for each attachment show only their icon, with their text in a small tooltip bubble on hover or keyboard focus; "Add files" keeps its text; wiki mode is a toggle switch instead of a checkbox (#130)

    fixed

    • Dialogs (publish, discard, restore, crop, annotate) now darken the page behind them, and the crop frame's corner handle has its white border: the theme has no black or white, so both were silently missing; they use the new scrim colours
    • Dropdowns in forms, such as the settings' top-level child order, default language and default license, no longer jump back to the previous value after saving until the page is reloaded (#114)
    Downloads
  • v1.1.1 b1598254ce

    Version 1.1.1 Stable

    miko released this 2026-11-05 08:45:22 +01:00 | 102 commits to master since this release

    Guests' language and theme move into a display menu, so the titlebar fits on phones.

    changed

    • Guests find language and theme in a display menu next to sign-in, as signed-in users do under their name; on phones it shows just its icon, so the titlebar has room again (#87)
    Downloads
  • v1.1.0 13b480b5b0

    Version 1.1.0 Stable

    miko released this 2026-11-04 20:00:56 +01:00 | 107 commits to master since this release

    Standalone pages with a rich page editor, a curated menu and a home page above the categories, plus callouts, an admin menu and a real 404 page.

    added

    • Pages: standalone pages of rich text, such as an imprint, that admins create, edit, publish and delete under "Pages" in the titlebar (#64)
      • A page lives outside the category tree at its own address, e.g. /impressum; its slug is derived from the title and can be changed, without a redirect from the old one
      • Slugs the app uses itself, such as admin or search, are refused
      • Its visibility applies as set; a draft is seen only by admins
      • The page editor has a table block with an optional heading row; a table always spans the full width of the text or its column, and scrolls sideways where its columns would get narrower than 8rem, as on phones (#77)
      • The page editor has an image block with an optional caption: chosen, pasted or dropped, an image is uploaded at once and shown in its own format, as wide as the text at most (#67)
      • Saving a page deletes the images it no longer shows; deleting a page deletes its images
      • The page editor has a columns block: 2 or 3 columns of equal width, side by side from md on and stacked below, each holding any page block but further columns; switching from 3 to 2 columns moves the third column's blocks to the second (#68)
      • The page editor has a spacer block: empty vertical space of 1 to 20 rem, set in whole rem by typing its height or dragging its bottom edge (#73)
      • A page's content spans the page's full width, and so does its editor, which is tall enough to write in comfortably (#68)
      • Search finds pages too, for those who may see them
    • Menu: an optional menu in the titlebar that admins curate under "Menu" in the admin menu, with links to categories, guides, pages or other addresses (#65)
      • Items are added, edited, removed and sorted in one form and saved together; links to other addresses must be absolute http:// or https:// URLs and need a label
      • Without a label, an item shows the current title of what it links to
      • Each visitor only sees the items whose targets they may open; links to other addresses open in a new tab
      • Deleting a category or page removes its items; a deleted guide's item is hidden until the guide is restored
      • The item for where the visitor is shows in the accent colour: a category in its whole subtree, including its guides
      • From md up the menu stands in the titlebar; below md a button left of the logo folds it out
    • Home page: a page that always exists and whose content shows above the categories at / (#83)
      • Admins edit it under "Pages", where it always comes first, or with "Edit home page" above the categories; it cannot be deleted
      • It has the page editor's blocks, a visibility and a status, but no title or slug of its own; it starts published and empty
      • It is not found by search and offered in no menu item; the logo already leads to it

    changed

    • Admin links moved from the account menu into an admin menu in the titlebar; each entry shows only to those with its permission (#66)
    • The titlebar wraps instead of centring the search: when the logo, the menu and the account leave the search too little room, it moves below them (#65)
    • Warnings in descriptions and step content are now callouts with four kinds: warning, error, note and success, each with its own icon and colour; the kind is chosen in the block's settings, and existing warnings stay warnings (#62)
    • Visibility and status are chosen from a row of buttons with icons instead of a dropdown, when editing pages, categories and a guide's properties (#75)
    • A missing page or guide shows kataba's own 404 page, with the logo hopping as the zero of "404", its own tab title and a link back to the start page, instead of Next.js's plain one (#80)

    fixed

    • The callout icon is drawn in its kind's colour while editing, so it is readable in dark mode; the warning icon was black (#62)
    • Missing addresses, and pages, categories and guides hidden from guests, now answer guests and search engines with status 404 instead of 200; signed-in visitors see the same not-found page, still with status 200 (#80)
    • The logo in the titlebar is centred in its row and its wordmark stands on the baseline of the menu; it sat about 3px too high. The menu also starts twice as far from the logo (#82)
    Downloads
  • v1.0.1 482680526e

    v1.0.1 Stable

    miko released this 2026-11-03 19:18:14 +01:00 | 147 commits to master since this release

    Images can now be pasted and dropped, step lines can hold inline code, and the editor has two fixes.

    added

    • Images for steps, covers and categories can be pasted from the clipboard or dropped onto an image editor (#53)
      • A "Paste from clipboard" button reads the clipboard and says when it holds no image or the browser denies access
      • Ctrl/⌘+V pastes into the focused image editor; outside every editor, an image pasted without text goes to the active step's images (or the category's image), even from a text field
      • Of several dropped files only the first is taken; files dropped outside an editor are ignored instead of opened
      • A step that already has the most images refuses further ones with a message
    • Inline code in step lines, with a button in the line toolbar and Editor.js's shortcut Ctrl/⌘+Shift+M, so step lines offer all of Editor.js's inline tools (#54)
    • The Docker database name and user can be set in docker/.env (DB_NAME, DB_USER); both default to kataba, so existing setups keep working
    • The README shows the kataba logo and documents the Docker Hub image mikognn/kataba

    fixed

    • A paragraph can hold more than one inline code; after the first one, no other word could be formatted as code (#55)
    • The link field of Editor.js's inline toolbar is readable in dark mode; its text was white on a light background (#52)
    Downloads
  • v1.0.0 5fa1a7403c

    v1.0.0 Stable

    miko released this 2026-11-02 20:20:59 +01:00 | 161 commits to master since this release

    The first release of kataba — open, visual documentation: step-by-step guides with annotated photos, organised in a category tree, self-hosted for one organisation.

    Features

    Content

    • Category tree of any depth with category pages and admin management (#6); categories get a description and an image (#41)
    • Manual child order for subcategories and guides, alphabetical by default (#40)
    • Guides — create, read, publish and delete; drafts and published guides, edits to published guides go live immediately, admins can restore deleted guides (#22, ADR-0008)
    • Steps with their own edit route and a step list (#23)
    • Step lines — coloured bullets and icon lines (caution, note, reminder), indented up to two levels (#24)
    • Step images — upload, 4:3 crop and re-crop, image variants, served through a guarded media route (#25, #36, ADR-0006)
    • Annotations — rectangle and circle outlines on step images, each belonging to a step line and taking its colour, highlighted in the reading view (#26, ADR-0011)
    • Cover images for guides; without one, a coloured tile (#29)
    • Full-text search across guides, filtered by what the reader may see (#33)

    Access

    • Sign-in with Auth.js and Authentik (OIDC); roles viewer, author and admin derived from Authentik groups and checked against the database (#4, ADR-0009)
    • Visibility public or internal; the most restrictive value along the category chain wins — in listings, search and image delivery (#20, ADR-0002)
    • Ownership and wiki mode: authors edit their own guides; owners can open a guide to all authors (#27, ADR-0003)

    Interface

    • Visual theme with semantic tokens, light and dark mode, logo and tiles (#16, ADR-0010)
    • Freely chosen accent colour, adjusted for contrast in light and dark mode (#32, ADR-0012)
    • Guide editor with the guide's properties in a sidebar (#28)
    • Admin settings page — instance name, session lifetime, accent colour, default language (#31)
    • Translated UI in English and German with Lingui/gettext (#34, ADR-0007), and a per-user interface language (#44)
    • Titlebar with a user menu and centred search (#48)

    Operations

    • Docker image built from the Next.js standalone output, and an example Compose setup with MariaDB; pending migrations are applied on container start (#50, ADR-0014)

    Fixes

    • Rich text is kept when a form is sent before Editor.js has loaded (#45)
    • No more deadlocks between parallel step and image saves: transactions run under READ COMMITTED behind guide row locks (#46, ADR-0013)
    • mysql:// connection strings are converted to mariadb:// for the driver adapter

    Quality and documentation

    • End-to-end tests with Playwright against their own database (#35), unit tests with Vitest
    • Domain glossary (GLOSSARY.md) and 14 Architecture Decision Records in docs/adr/
    • README as a full project introduction, with screenshots

    Installation

    Requires Node.js, MariaDB and an Authentik OIDC application. See the README for setup with Node.js or Docker:

    git clone --branch v1.0.0 https://git.mike-ochmann.de/MassiveDynamic/kataba.git
    cd kataba/docker
    cp .env.example .env    # fill in
    docker compose up -d --build
    

    Not in this release

    Tool and part lists, difficulty and time estimates, prerequisites, revisions and working copies, comments, PDF export, videos and translation of guide content.

    Downloads