lildocs 0.1.21 → 0.1.23

package/docs/reference/cli.md

@@ -0,0 +1,138 @@
+---
+title: CLI Reference
+---
+
+# Command Line
+
+> Choose the right lildocs command, understand each flag, and map one-off CLI
+> choices to persistent configuration.
+
+lildocs supports these command shapes:
+
+```bash
+lildocs <path>
+lildocs build <path>
+lildocs dev <path>
+lildocs deploy <path>
+lildocs init github-pages <path>
+```
+
+`<path>` can be a Markdown folder or a single Markdown file.
+
+## Bare Build Command
+
+Build a static documentation site from a Markdown folder or file.
+
+```bash
+lildocs ./docs
+```
+
+This is the shortest form of the build command. It treats `./docs` as the
+documentation root, finds the home page, generates navigation from the folder
+structure, builds a search index, and writes the site to `dist`.
+
+If the path points to a Markdown file, that file becomes the home page and its
+parent folder becomes the docs root:
+
+```bash
+lildocs ./docs/index.md
+```
+
+Use this form for simple local scripts, CI jobs, or one-off builds.
+
+## Build Command
+
+Build a static documentation site with the explicit `build` subcommand.
+
+```bash
+lildocs build ./docs
+```
+
+`build` does the same generation work as the bare `lildocs <path>` form, but it
+is clearer in package scripts and CI configuration:
+
+```bash
+pnpm lildocs build ./docs
+```
+
+Build output is self-contained. Page links are relative, local assets are copied
+into the output folder, and `search-index.json` is generated next to the HTML
+files.
+
+## Dev Command
+
+Start a local development server that rebuilds the generated site when docs
+files change.
+
+```bash
+lildocs dev ./docs
+```
+
+The dev server writes generated files to `.lildocs` by default and serves them
+through Vite from `127.0.0.1:3000`. Add `--open` to launch the preview in your
+default browser.
+
+Choose a different output folder when you want to inspect generated files:
+
+```bash
+lildocs dev ./docs --out ./.docs-preview
+```
+
+Choose the host or port when the defaults conflict with another local service:
+
+```bash
+lildocs dev ./docs --host 0.0.0.0 --port 4173
+```
+
+The dev output directory must stay inside the current workspace, cannot be the
+repository root, and cannot contain the docs root.
+
+## Deploy Command
+
+Build GitHub Pages-ready output.
+
+```bash
+lildocs deploy ./docs
+```
+
+`deploy` builds the same static site as `build`, then adds Pages deployment
+metadata. See [GitHub Pages](../guides/github-pages.md) for the full publishing
+workflow.
+
+## Init GitHub Pages Command
+
+Create a GitHub Actions workflow that deploys lildocs output to GitHub Pages.
+
+```bash
+lildocs init github-pages ./docs
+```
+
+This command writes `.github/workflows/lildocs-pages.yml` if it does not already
+exist. The workflow obtains the current lildocs major and minor release line
+with `pnpm dlx`, runs `lildocs deploy`, uploads the generated output, and
+publishes it with GitHub's Pages deployment action. Lildocs does not need to be
+a project dependency.
+
+## Options
+
+| Option | Applies to | Description |
+| --- | --- | --- |
+| `--out <dir>` | build, dev, deploy, init github-pages | Output directory for generated files. Build, deploy, and init github-pages default to `dist`; dev defaults to `.lildocs`. |
+| `--theme <name>` | build, dev, deploy | Built-in lildocs theme or bundled Shiki theme name. |
+| `--font.heading <name-or-file>` | build, dev, deploy | Heading font from Google Fonts or a local font file. |
+| `--font.body <name-or-file>` | build, dev, deploy | Body and interface font from Google Fonts or a local font file. |
+| `--font.code <name-or-file>` | build, dev, deploy | Code font from Google Fonts or a local font file. |
+| `--background.image <url-or-file>` | build, dev, deploy | Background image URL, CSS image function, or docs-relative image path. |
+| `--background.gradient <gradient>` | build, dev, deploy | CSS background gradient. |
+| `--background.blendMode <mode>` | build, dev, deploy | CSS `background-blend-mode` for the theme color and background layers. |
+| `--link.underline <style>` | build, dev, deploy | Content link underline behavior: `always`, `hover`, or `none`. |
+| `--host <address>` | dev | Host address for the local development server. |
+| `--port <number>` | dev | Port for the local development server. |
+| `--open` | dev | Open the local development server in the default browser. |
+| `--base <path>` | deploy, init github-pages | GitHub Pages base path, such as `/repo/` for project pages. |
+
+CLI flags override matching `config.json` values. See
+[Configuration](configuration.md) for persistent defaults.
+
+Favicon and logo settings are configuration-only and do not have CLI flags. See
+[Themes and styling](theming.md) for examples.

package/docs/reference/configuration.md

@@ -0,0 +1,137 @@
+# Configuration Reference
+
+> Look up persistent project settings, schema support, precedence, and matching
+> CLI overrides.
+
+lildocs works without configuration. Add `config.json` to the docs root when you
+want persistent defaults:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/aleclarson/lildocs/main/schemas/config.schema.json",
+  "projectName": "Acme Docs",
+  "theme": {
+    "light": "github-light",
+    "dark": "github-dark"
+  },
+  "favicon": "./images/favicon.svg",
+  "font": {
+    "heading": "Inter",
+    "body": "Source Sans 3",
+    "code": "Roboto Mono"
+  },
+  "logo": {
+    "image": "./images/logo.svg",
+    "text": "Acme Docs",
+    "font": "Onest"
+  },
+  "background": {
+    "gradient": "linear-gradient(135deg, rgb(121 184 255 / 0.14), transparent 38%)",
+    "blendMode": "screen"
+  },
+  "link": {
+    "underline": "hover"
+  },
+  "reference": {
+    "packageJson": "../package.json"
+  },
+  "navigation": {
+    "order": ["index.md", "getting-started.md", "guides/", "reference/"],
+    "transition": "fade",
+    "duration": 160,
+    "easing": "cubic-bezier(0.16, 1, 0.3, 1)"
+  }
+}
+```
+
+CLI flags override `config.json` values for one command run.
+
+## Schema
+
+`$schema` points editors and language servers at the lildocs JSON schema:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/aleclarson/lildocs/main/schemas/config.schema.json"
+}
+```
+
+This field is optional and does not change build behavior.
+
+## Fields
+
+Configuration fields are grouped by the part of the generated site they affect.
+Feature pages provide examples and explain the resulting behavior.
+
+### Project
+
+| Field         | Description                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| `projectName` | Project name appended to each browser document title. Defaults to the nearest `package.json` `name`. |
+
+### Appearance
+
+See [Themes and styling](theming.md) for theme resolution, local theme files,
+branding examples, font sources, backgrounds, and link presentation.
+
+| Field                  | Description                                                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `theme`                | Built-in lildocs theme, bundled Shiki theme name, or `{ "light": "...", "dark": "..." }` system theme pair. |
+| `favicon`              | Browser icon from a URL, data URL, absolute URL path, or docs-relative image path.                          |
+| `font.heading`         | Font used for page titles and headings.                                                                     |
+| `font.body`            | Font used for normal text and interface text.                                                               |
+| `font.code`            | Font used for inline code and fenced code blocks.                                                           |
+| `logo.image`           | Header logo image from a URL, data URL, absolute URL path, or docs-relative image path.                     |
+| `logo.text`            | Header brand text. Defaults to the nearest `package.json` `name` when no logo image is configured.          |
+| `logo.font`            | Font used for header brand text.                                                                            |
+| `background.image`     | Background image from a URL, CSS image function, or docs-relative file path.                                |
+| `background.gradient`  | CSS background gradient.                                                                                    |
+| `background.blendMode` | CSS `background-blend-mode` for the theme color and configured background layers.                           |
+| `link.underline`       | Content link underline behavior: `always`, `hover`, or `none`.                                              |
+
+### Navigation
+
+See [Navigation and page structure](../features/navigation.md) for generated
+ordering, breadcrumbs, previous and next links, and transition examples.
+
+| Field                   | Description                                                                                                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigation.order`      | Docs-root-relative Markdown files or folders, in generated navigation order. Unlisted pages keep entry-point link order, then generated order after listed siblings. |
+| `navigation.transition` | Enhanced navigation transition preset: `fade`, `slide`, `scale`, or `instant`.                                                                                       |
+| `navigation.duration`   | Enhanced navigation transition duration in milliseconds.                                                                                                             |
+| `navigation.easing`     | CSS timing function used by enhanced navigation transitions.                                                                                                         |
+
+### Generated Reference
+
+See [Generated API reference](../features/api-reference.md) for export discovery,
+generated paths, declaration handling, and GitHub links.
+
+| Field                   | Description                                                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `reference.packageJson` | Docs-root-relative path to a `package.json` whose exported TypeScript declarations generate `/reference/` API pages. |
+
+## CLI Flag Mappings
+
+| Flag                               | JSON config            |
+| ---------------------------------- | ---------------------- |
+| `--theme <name>`                   | `theme`                |
+| `--font.heading <name-or-file>`    | `font.heading`         |
+| `--font.body <name-or-file>`       | `font.body`            |
+| `--font.code <name-or-file>`       | `font.code`            |
+| `--background.image <url-or-file>` | `background.image`     |
+| `--background.gradient <gradient>` | `background.gradient`  |
+| `--background.blendMode <mode>`    | `background.blendMode` |
+| `--link.underline <style>`         | `link.underline`       |
+
+`--out <dir>` has no JSON config equivalent. It sets the generated site
+directory for the current command. Build and deploy default to `dist`; dev
+defaults to `.lildocs`.
+
+`--host <address>`, `--port <number>`, and `--open` are dev-only server options
+and have no JSON config equivalent.
+
+`--base <path>` applies to `deploy` and `init github-pages`, and has no JSON
+config equivalent.
+
+`favicon`, `logo.image`, `logo.text`, `logo.font`, and
+`reference.packageJson` are configuration-only and have no CLI flag equivalents.

package/docs/reference/theming.md

@@ -0,0 +1,218 @@
+# Themes And Styling
+
+> Control the generated site's visual system with theme selection, local theme
+> files, fonts, logos, backgrounds, and links.
+
+Theme and styling options are resolved at build time and emitted as static CSS.
+
+## Theme
+
+By default, generated sites follow the visitor's system color scheme. lildocs
+uses `vitesse-light` in light mode and `vitesse-dark` in dark mode.
+
+Set `theme` to a string to force one visual theme and syntax highlighting theme:
+
+```json
+{
+  "theme": "github-dark"
+}
+```
+
+Use `default`, `minimal`, or any bundled Shiki theme name, such as
+`github-light` or `github-dark`.
+
+Set `theme.light` and `theme.dark` to customize the system color-scheme pair:
+
+```json
+{
+  "theme": {
+    "light": "github-light",
+    "dark": "github-dark-dimmed"
+  }
+}
+```
+
+If the docs root contains `theme.ts`, lildocs loads it when `theme` is not set
+and no `--theme` flag is provided.
+
+Theme resolution order is:
+
+1. `--theme`
+2. `theme` from `config.json`
+3. `theme.ts` in the docs root
+4. The built-in system theme pair
+
+## Local Theme Files
+
+Create `theme.ts` in the docs root when you need a local theme object instead of
+a named built-in or Shiki theme:
+
+```ts
+export default {
+  color: {
+    background: "#ffffff",
+    text: "#111111",
+    mutedText: "#666666",
+    border: "#e5e5e5",
+    link: "#2563eb",
+    codeBackground: "#f6f8fa",
+  },
+  font: {
+    body: "system-ui, sans-serif",
+    code: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  },
+  background: {
+    gradient:
+      "linear-gradient(180deg, rgb(37 99 235 / 0.06), transparent 220px)",
+  },
+};
+```
+
+Local themes keep the token surface small: colors, font families, and syntax
+highlighting theme configuration. `background.gradient` and
+`background.blendMode` can be set on a local theme when the background should
+come from the active light or dark theme.
+
+Local themes can also tune code foreground color, sidebar background color, and
+the Shiki theme used for syntax highlighting and Mermaid diagrams:
+
+```ts
+export default {
+  color: {
+    background: "#ffffff",
+    text: "#111111",
+    mutedText: "#666666",
+    border: "#e5e5e5",
+    link: "#2563eb",
+    codeBackground: "#f6f8fa",
+    codeForeground: "#24292e",
+    sidebarBackground: "#fafafa",
+  },
+  font: {
+    body: "system-ui, sans-serif",
+    mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  },
+  shiki: {
+    theme: "github-light",
+  },
+};
+```
+
+Use `font.code` when you want to name the code font directly. Use `font.mono`
+when a local theme should provide a general monospace fallback for code.
+
+## Fonts
+
+`font` configures the generated site's font families:
+
+The default built-in theme uses Baloo 2 (600 and 700) for headings, Inter (400
+and 500) for body and interface text, and JetBrains Mono for code.
+
+```json
+{
+  "font": {
+    "heading": "Inter",
+    "body": "Source Sans 3",
+    "code": "Roboto Mono"
+  }
+}
+```
+
+Font values can be Google Fonts family names or local `.woff2`, `.woff`, `.ttf`,
+or `.otf` file paths.
+
+`font.heading` sets the font used for page titles and headings.
+
+`font.body` sets the font used for normal text and interface text.
+
+`font.code` sets the font used for inline code and fenced code blocks.
+
+## Favicon
+
+`favicon` configures the generated site's browser icon:
+
+```json
+{
+  "favicon": "./images/favicon.svg"
+}
+```
+
+The value can be a URL, data URL, absolute URL path, or docs-relative image
+file. Local image files are copied into the generated site's assets.
+
+## Logo
+
+`logo` configures the generated site's header brand:
+
+```json
+{
+  "logo": {
+    "image": "./images/logo.svg",
+    "text": "Acme Docs",
+    "font": "Onest"
+  }
+}
+```
+
+`logo.image` can be a URL, data URL, absolute URL path, or docs-relative image
+file. Local image files are copied into the generated site's assets.
+
+`logo.text` sets the visible brand text. When both `logo.text` and `logo.image`
+are omitted, the generated header uses the nearest `package.json` `name` as the
+brand text.
+
+`logo.font` sets the brand text font. Values can be Google Fonts family names or
+local `.woff2`, `.woff`, `.ttf`, or `.otf` file paths.
+
+## Background
+
+`background` configures optional page background layers:
+
+```json
+{
+  "background": {
+    "image": "./images/background.svg",
+    "gradient": "linear-gradient(135deg, rgb(121 184 255 / 0.14), transparent 38%)",
+    "blendMode": "screen"
+  }
+}
+```
+
+`background.image` adds a background image from a URL, CSS image function, or
+docs-relative file path. Local image files are copied into the generated site's
+assets.
+
+```json
+{
+  "background": {
+    "image": "radial-gradient(circle at top, rgb(37 99 235 / 0.18), transparent 42%)"
+  }
+}
+```
+
+`background.gradient` adds a CSS background gradient.
+
+`background.blendMode` sets `background-blend-mode` for the theme color and
+configured background layers.
+
+No background gradient is generated by default. Add a `background` entry in
+`config.json`, pass the matching CLI background flags, or define `background` in
+a local theme when a page should use background layers.
+
+## Links
+
+`link` configures link presentation in generated Markdown content:
+
+```json
+{
+  "link": {
+    "underline": "hover"
+  }
+}
+```
+
+`link.underline` controls generated content link underlines. Use `always`,
+`hover`, or `none`.
+
+See the [configuration reference](configuration.md#appearance) for a compact
+summary of every appearance field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lildocs",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "A lightweight CLI that turns Markdown docs into a static searchable documentation site.",
   "homepage": "https://aleclarson.github.io/lildocs/",
   "repository": {
@@ -11,20 +11,27 @@
     "lildocs": "dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && node scripts/build-renderers.mjs",
     "docs:serve": "pnpm run build && node dist/cli.mjs build ./docs --out ./dist/docs && sirv ./dist/docs",
-    "format": "prettier --write src schemas package.json tsconfig.json tsdown.config.ts vitest.config.ts .oxlintrc.json .prettierrc.json .vscode/settings.json",
-    "format:check": "prettier --check src schemas package.json tsconfig.json tsdown.config.ts vitest.config.ts .oxlintrc.json .prettierrc.json .vscode/settings.json",
-    "lint": "oxlint src tsdown.config.ts vitest.config.ts",
+    "format": "prettier --write src scripts schemas package.json tsconfig.json tsdown.config.ts vitest.config.ts .oxlintrc.json .prettierrc.json .vscode/settings.json",
+    "format:check": "prettier --check src scripts schemas package.json tsconfig.json tsdown.config.ts vitest.config.ts .oxlintrc.json .prettierrc.json .vscode/settings.json",
+    "lint": "oxlint src scripts tsdown.config.ts vitest.config.ts",
     "test": "pnpm run build && vitest run",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "beautiful-mermaid": "^1.1.3",
+    "shiki": "^4.0.2"
+  },
+  "devDependencies": {
+    "@tsrx/prettier-plugin": "^0.3.93",
+    "@types/culori": "^4.0.1",
+    "@types/node": "^24.0.0",
     "cmd-ts": "^0.15.0",
     "culori": "^4.0.2",
     "entities": "^8.0.0",
@@ -33,19 +40,10 @@
     "marked": "^18.0.3",
     "marked-shiki": "^1.2.1",
     "octane": "^0.1.3",
-    "shiki": "^4.0.2",
-    "swup": "^4.9.0"
-  },
-  "peerDependencies": {
-    "vite": "^8.0.0"
-  },
-  "devDependencies": {
-    "@tsrx/prettier-plugin": "^0.3.93",
-    "@types/culori": "^4.0.1",
-    "@types/node": "^24.0.0",
     "oxlint": "^1.65.0",
     "prettier": "^3.9.5",
     "sirv": "^3.0.2",
+    "swup": "^4.9.0",
     "tsdown": "^0.22.0",
     "typescript": "^5.9.0",
     "vite": "^8.0.0",