• 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