docs: actual docs page

tale · tale · commit b197ec28c103 · 2026-02-19T12:53:15.000-05:00
diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -7,16 +7,23 @@ export default defineConfig({
   title: "Rootbeer",
   description: "Deterministically manage your dotfiles",
   themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'Modules', link: '/modules/zsh' },
     ],
 
     sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Core API', link: '/guide/core-api' },
+        ]
+      },
       {
         text: 'Modules',
         items: [
-          { text: 'Zsh', link: '/modules/zsh' }
+          { text: 'Zsh', link: '/modules/zsh' },
         ]
       }
     ],
diff --git a/docs/guide/core-api.md b/docs/guide/core-api.md
@@ -0,0 +1,78 @@
+# Core API
+
+The core API is available via `require("rootbeer")` and provides the
+primitives for writing files, creating symlinks, and querying system info.
+
+```lua
+local rb = require("rootbeer")
+```
+
+## Writing Files
+
+Write content to any path. Parent directories are created automatically,
+and `~` expands to `$HOME`.
+
+```lua
+rb.file("~/.config/starship.toml", [[
+[character]
+success_symbol = "[➜](bold green)"
+]])
+```
+
+<!--@include: ../_generated/core.file.md-->
+
+## Symlinking
+
+Symlink files from your source directory into place. The source path is
+relative to `~/.local/share/rootbeer/source/`. Idempotent — existing
+correct links are skipped, stale links are replaced.
+
+```lua
+rb.link_file("config/gitconfig", "~/.gitconfig")
+rb.link_file("config/nvim", "~/.config/nvim")
+```
+
+<!--@include: ../_generated/core.link_file.md-->
+
+## System Info
+
+Query the current machine to write conditional configs that work across
+multiple systems.
+
+```lua
+local d = rb.data()
+
+if d.os == "Darwin" then
+    rb.file("~/.config/homebrew/env", 'export HOMEBREW_PREFIX="/opt/homebrew"\n')
+end
+```
+
+<!--@include: ../_generated/core.data.md-->
+
+## JSON Serialization
+
+Generate JSON config files for tools like VS Code or Alacritty.
+
+```lua
+rb.file("~/.config/alacritty/alacritty.json", rb.to_json({
+    terminal = { shell = "/bin/zsh" },
+    font = { size = 14 },
+}))
+```
+
+<!--@include: ../_generated/core.to_json.md-->
+
+## Low-Level Primitives
+
+These are building blocks used internally by modules. Prefer `rb.file()`
+with module renderers for most use cases.
+
+<!--@include: ../_generated/core.line.md-->
+
+<!--@include: ../_generated/core.emit.md-->
+
+## Utilities
+
+<!--@include: ../_generated/core.interpolate_table.md-->
+
+<!--@include: ../_generated/core.register_module.md-->
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -0,0 +1,121 @@
+# Getting Started
+
+Rootbeer is a dotfile manager that lets you define your system configuration
+in Lua scripts. Think [chezmoi](https://www.chezmoi.io/), but with the full
+power of a real scripting language instead of Go templates.
+
+## Installation
+
+Rootbeer is built from source using Meson and Ninja. LuaJIT and cJSON are
+vendored as subprojects — no extra dependencies required.
+
+```bash
+meson setup build
+meson compile -C build
+```
+
+The binary is built to `./build/src/cli/rb`.
+
+If you have [mise](https://mise.jdx.dev/) installed:
+
+```bash
+mise run build
+```
+
+## Initializing
+
+Set up a new source directory, or clone an existing dotfiles repo:
+
+```bash
+# Create a fresh source directory with a starter manifest
+rb init
+
+# Or clone from a GitHub repo
+rb init tale/dotfiles
+```
+
+This creates `~/.local/share/rootbeer/source/` with a `rootbeer.lua` manifest
+file. This directory is your dotfiles repo — commit it, push it, clone it on
+another machine.
+
+## Your First Config
+
+Open `~/.local/share/rootbeer/source/rootbeer.lua`:
+
+```lua
+local rb = require("rootbeer")
+local zsh = require("rootbeer.shells.zsh")
+
+rb.file("~/.zshrc", zsh.config({
+    env = {
+        EDITOR = "nvim",
+        LANG = "en_US.UTF-8",
+    },
+    aliases = {
+        g = "git",
+        v = "nvim",
+    },
+    extra = "autoload -Uz compinit && compinit",
+}))
+```
+
+This writes a generated `.zshrc` to your home directory.
+
+## Applying
+
+```bash
+# Preview what would change
+rb apply -n
+
+# Apply for real
+rb apply
+```
+
+`rb apply` evaluates your manifest and writes/links files into place. Use
+`-n` (dry run) to see what would happen without touching the filesystem.
+
+## Conditionals
+
+Use `rb.data()` to branch on the current machine:
+
+```lua
+local d = rb.data()
+
+if d.os == "Darwin" then
+    rb.file("~/.config/homebrew/env", 'export HOMEBREW_PREFIX="/opt/homebrew"\n')
+end
+
+if d.hostname == "workstation" then
+    -- work-specific config
+end
+```
+
+`rb.data()` returns a table with:
+
+| Field | Description |
+|-------|-------------|
+| `os` | Operating system name (e.g. `Linux`, `Darwin`) |
+| `arch` | CPU architecture (e.g. `x86_64`, `arm64`) |
+| `hostname` | Machine hostname |
+| `home` | Home directory path |
+| `username` | Current username |
+
+## Symlinking
+
+For files you want to edit directly (like a gitconfig), use `rb.link_file()`
+to symlink them from your source directory:
+
+```lua
+-- Source path is relative to the source directory
+-- Target path supports ~ expansion
+rb.link_file("config/gitconfig", "~/.gitconfig")
+rb.link_file("config/nvim", "~/.config/nvim")
+```
+
+Symlinks are idempotent — if the link already points to the right place,
+nothing happens. Stale links are replaced.
+
+## Next Steps
+
+- [Modules](/modules/zsh) — Declarative config generators for shells and tools
+- [Core API](/guide/core-api) — Full reference for `rb.*` functions
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,22 @@
+---
+layout: home
+
+hero:
+  name: Rootbeer
+  tagline: Manage your dotfiles with Lua
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/tale/rootbeer
+
+features:
+  - title: Real Scripting, No Templates
+    details: Use Lua's loops, conditionals, and functions instead of learning a templating DSL. Your config is code.
+  - title: Declarative Modules
+    details: Describe what your shell config, git config, or SSH config should look like with simple Lua tables.
+  - title: Cross-Platform
+    details: Detect OS, architecture, and hostname at runtime. One config repo, multiple machines.
+---
diff --git a/lua/rootbeer/core.lua b/lua/rootbeer/core.lua
@@ -0,0 +1,62 @@
+--- @meta
+--- Stubs for the native rootbeer core API (implemented in C).
+--- This file is not loaded at runtime — it exists for LuaLS
+--- type checking and lua2md documentation generation.
+
+local rb = {}
+
+--- @class rb.DataInfo
+--- @field os string Operating system name (e.g. `"Linux"`, `"Darwin"`).
+--- @field arch string CPU architecture (e.g. `"x86_64"`, `"arm64"`).
+--- @field hostname string Machine hostname.
+--- @field home string Home directory path.
+--- @field username string Current username.
+
+--- Writes content to a file path.
+--- The `~` character is expanded to `$HOME`. Parent directories are
+--- created automatically. In dry-run mode, prints what would be written.
+--- @param path string The destination file path (supports `~` expansion).
+--- @param content string The content to write.
+function rb.file(path, content) end
+
+--- Creates a symlink from a source file to a destination path.
+--- The source is relative to the rootbeer source directory
+--- (`~/.local/share/rootbeer/source/`). The destination supports `~`
+--- expansion. Idempotent — existing correct links are left alone, stale
+--- links are replaced.
+--- @param src string Source path, relative to the source directory.
+--- @param dest string Destination path (supports `~` expansion).
+function rb.link_file(src, dest) end
+
+--- Returns a table with information about the current machine.
+--- @return rb.DataInfo
+function rb.data() end
+
+--- Serializes a Lua table to a JSON string.
+--- @param tbl table The table to serialize.
+--- @return string
+function rb.to_json(tbl) end
+
+--- Appends a line (with trailing newline) to the internal output buffer.
+--- This is a low-level primitive — prefer `rb.file()` with module
+--- renderers like `zsh.config()` for most use cases.
+--- @param str string The line to append.
+function rb.line(str) end
+
+--- Appends raw text to the internal output buffer without a trailing newline.
+--- @param str string The text to append.
+function rb.emit(str) end
+
+--- Passes a table through a transform function and returns the result.
+--- @param tbl table The input table.
+--- @param fn fun(tbl: table): table The transform function.
+--- @return table
+function rb.interpolate_table(tbl, fn) end
+
+--- Registers a native Lua module under the given name.
+--- Used internally by the plugin system.
+--- @param name string The module name to register.
+--- @param tbl table The module table.
+function rb.register_module(name, tbl) end
+
+return rb
diff --git a/lua/rootbeer/init.lua b/lua/rootbeer/init.lua
@@ -0,0 +1,5 @@
+local M = {}
+
+M.zsh = require("rootbeer.shells.zsh")
+
+return M
diff --git a/scripts/lua2md.ts b/scripts/lua2md.ts
@@ -59,8 +59,12 @@ interface Module {
 
 // ── Parsing ────────────────────────────────────────────────────────
 
-/** Match a type that may contain generics and union pipes: table<string, string>, string|string[] */
-const TYPE_RE = /(?:\S+<[^>]+>|\S+(?:\|(?:\S+<[^>]+>|\S+))*)/
+/** Match a LuaLS type annotation:
+ *  - fun(tbl: table): table     — function signatures with parens/spaces
+ *  - table<string, string>      — generics with angle brackets
+ *  - string|string[]            — union types
+ */
+const TYPE_RE = /(?:fun\([^)]*\)(?:\s*:\s*\S+)?|\S+<[^>]+>|\S+(?:\|(?:\S+<[^>]+>|\S+))*)/
 
 function parseFile(filepath: string, root: string): Module | null {
 	const rel = relative(root, filepath)
@@ -205,29 +209,42 @@ function renderBlock(block: DocBlock, mod: Module): string {
 	}
 
 	if (block.params.length) {
-		for (const p of block.params) {
-			const classDef = mod.classes.get(p.type)
-			if (classDef) {
-				out.push(`**\`${p.name}\`** \`${escapeCell(p.type)}\` — ${escapeCell(p.desc)}`)
-				out.push("")
-				renderFields(out, classDef.fields)
-				out.push("")
-			} else {
-				out.push("**Parameters:**")
-				out.push("")
-				out.push("| Name | Type | Description |")
-				out.push("|------|------|-------------|")
+		// Split params into class-typed (expanded inline) and plain
+		const classParams = block.params.filter((p) => mod.classes.has(p.type))
+		const plainParams = block.params.filter((p) => !mod.classes.has(p.type))
+
+		if (plainParams.length) {
+			out.push("**Parameters:**")
+			out.push("")
+			out.push("| Name | Type | Description |")
+			out.push("|------|------|-------------|")
+			for (const p of plainParams) {
 				out.push(`| \`${p.name}\` | \`${escapeCell(p.type)}\` | ${escapeCell(p.desc)} |`)
-				out.push("")
 			}
+			out.push("")
+		}
+
+		for (const p of classParams) {
+			const classDef = mod.classes.get(p.type)!
+			out.push(`**\`${p.name}\`** \`${escapeCell(p.type)}\` — ${escapeCell(p.desc)}`)
+			out.push("")
+			renderFields(out, classDef.fields)
+			out.push("")
 		}
 	}
 
 	if (block.returns.length) {
-		out.push("**Returns:** ", "")
+		out.push("**Returns:**", "")
 		for (const r of block.returns) {
-			const desc = r.desc ? ` — ${r.desc}` : ""
-			out.push(`- \`${escapeCell(r.type)}\`${desc}`)
+			const classDef = mod.classes.get(r.type)
+			if (classDef) {
+				out.push(`- \`${escapeCell(r.type)}\`${r.desc ? ` — ${r.desc}` : ""}`)
+				out.push("")
+				renderFields(out, classDef.fields)
+			} else {
+				const desc = r.desc ? ` — ${r.desc}` : ""
+				out.push(`- \`${escapeCell(r.type)}\`${desc}`)
+			}
 		}
 		out.push("")
 	}
