CUF Wiki is a local‑first, single‑binary wiki focused on Markdown content, a strict taxonomy, and a comfortable terminal UI. The application stores pages as Markdown files on disk and lets you browse, edit, preview, and commit changes without leaving your terminal.

Features

• Keyboard‑only terminal UI built with tview
• Markdown editing with an instant preview popup
• File tree navigation with unsaved‑change protection
• YAML frontmatter metadata (title, tags, categories) validated against a taxonomy loaded from ./config/taxonomy.yaml
• In‑memory tag/category index and a basic full‑text search
• Git helpers for commit, diff, and blame
• Page management commands (new, rename, discard)

Requirements

• Go 1.21+ (repo currently targets Go 1.26.2)
• A Git repository initialized at the repo root
• A taxonomy file at ./config/taxonomy.yaml

Getting Started

# Run the wiki using the repo's config/ and data/
go run ./cmd/wiki

# Point the wiki at a different root that contains config/ + data/
go run ./cmd/wiki --root /path/to/another/wiki

When --root (or a positional path) is provided, the binary expects that directory to contain config/taxonomy.yaml and a data/ tree. Sample content and a taxonomy live inside this repo under ./data and ./config.

Command Workflow

• Press Esc to switch focus to the command bar (and again to cancel).
• Commands can optionally be prefixed with :.
• Hit Enter to execute the command.

Available Commands

Command	Description
open <path>	Open a page relative to the data directory.
save, w	Save the current page to disk.
quit, q	Exit the application (blocked if unsaved edits exist).
tag add/remove <tag>	Manage tags on the current page.
cat add <category>	Add a category.
search tag=foo, search cat=foo, search text=foo, search foo	Filter the tree by taxonomy or full text. search clear resets.
new <path> [title]	Create a new Markdown page (frontmatter generated).
rename <path>	Rename the current page file.
discard	Revert unsaved edits to the last saved version.
commit "<msg>"	Stage config and data, then run git commit.
diff	Show git diff.
blame	Run git blame on the current page.
preview	Render the current page (content + metadata) in a popup.
fullscreen	Hide or restore the left navigation and page tree panes.
meta	Show page metadata.
meta edit	Edit metadata via a popup form.
taxonomy	Show the allowed tags/categories and usage counts.
help	Show command reference.

Navigation Bar (TUI)

The left-hand pane in the TUI is a navigation tree, separate from the file tree. It is rebuilt automatically whenever taxonomy or page metadata changes (e.g., after save, tag add, or cat add) and groups entries into three sections:

• Directories – top-level subdirectories under data/. Selecting one filters the file tree to pages beneath that directory. The leading (all) entry clears any active filter and restores the full tree.
• Tags – every tag declared in config/taxonomy.yaml, each followed by the count of pages currently using it. Selecting a tag filters the file tree to pages carrying that tag.
• Categories – every category declared in the taxonomy, with usage counts. Selecting a category filters the file tree to pages in that category.

Section headers (Directories, Tags, Categories) are themselves selectable: pressing Enter on a header collapses or expands the section. Selecting any leaf entry switches focus to the file tree so you can pick a page from the filtered list. Ctrl+N focuses the navigation pane from anywhere; Ctrl+L jumps to the file tree, Ctrl+E jumps to the editor, and Ctrl+W hides or restores the entire left sidebar so the editor can fill the main area.

Navigation Bar (Web Server)

cuf-serve renders a sticky left sidebar on every page (index, tag pages, category pages, and individual articles) with the same three sections:

• Directories – links to /<dir>/ listing pages under each top-level directory in data/, with page counts.
• Tags – links to /tags/<tag> for every taxonomy tag, with usage counts.
• Categories – links to /category/<cat> for every taxonomy category, with usage counts.

The sidebar is generated from the live taxonomy and page index when the server starts, so it always reflects the configured taxonomy. On viewports narrower than 720px the sidebar collapses above the main content. A breadcrumb (<nav class="crumbs">) at the top of the main area always links back to the index.

Keyboard Shortcuts

• Ctrl+S – save
• Ctrl+Q – quit (requires clean buffer)
• Ctrl+L – focus tree
• Ctrl+E – focus editor
• Ctrl+W – toggle fullscreen editor
• Esc – enter command mode (or close popups/command mode)

Customizing the Wiki

1. Update ./config/taxonomy.yaml with your desired tags, categories, and aliases.
2. Add Markdown files underneath ./data. Each file should include YAML frontmatter with Title, Tags, and Categories.
3. Launch the UI with go run ./cmd/wiki [--root DIR] and start editing.

Troubleshooting

• Unknown command – ensure you pressed Esc first. Commands are case insensitive and don’t require a colon, but search foo (no =) defaults to a text search.
• Unsaved changes warning – run save or discard before switching pages, renaming, or running git commands.
• No taxonomy – double‑check ./config/taxonomy.yaml exists. The app will refuse to start without it.

License

MIT