Skip to content

Add an end-user Overview of all add-ons + credit upstream fork #3

Description

@timlinux

User story

As a new timvim user, I want a single Overview page that shows every
add-on in the distribution and what it is for, so that I can understand what the
editor gives me and jump to the right guide — without reading the Nix config.

As a maintainer, I want that Overview generated from a source-of-truth
manifest and drift-checked against the live config/ tree, so it can never
silently fall out of date when we add or remove a plugin.

Context

flowchart LR
    cfg["config/*.nix<br/>(live add-ons)"] -->|drift-check| gen["lib/gen-addons-docs.py"]
    man["lib/addons.json<br/>(source of truth)"] --> gen
    gen --> svg["addons.svg<br/>(diagram)"]
    gen --> tbl["overview/addons.md<br/>(linked table)"]
    svg --> book["Handbook · Overview"]
    tbl --> book
    man -. "add a plugin without<br/>documenting it" .-> fail["build fails"]
Loading

Success criteria

  • New Overview section in the handbook, between Getting Started and the
    User Guide, with an end-user diagram + a fully linked add-ons table.
  • Diagram is a Python-generated, brand-coloured SVG (kartozaColors).
  • Table + diagram render from lib/addons.json; adding/removing a plugin
    without updating the manifest fails nix run .#handbook-addons.
  • Generator wired into the docs + release CI and the PDF chapter order.
  • Upstream Schrovimger (jack-thesparrow) fork and NVF credited in the
    README and the handbook.

Job size

M (~1 day).

Epic

Documentation handbook.

Tags

documentation, enhancement, handbook

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions