lildocs 0.1.22 → 0.1.23

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as renderGitHubPagesWorkflow, r as repoRelativeInputPath, t as normalizeBasePath } from "./github-pages-qzowPgcG.mjs";
+import { n as renderGitHubPagesWorkflow, r as repoRelativeInputPath, t as normalizeBasePath } from "./github-pages-CbcFNgKi.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import process$1 from "node:process";

package/dist/core/github-pages.mjs

@@ -1,2 +1,2 @@
-import { n as renderGitHubPagesWorkflow, r as repoRelativeInputPath, t as normalizeBasePath } from "../github-pages-qzowPgcG.mjs";
+import { n as renderGitHubPagesWorkflow, r as repoRelativeInputPath, t as normalizeBasePath } from "../github-pages-CbcFNgKi.mjs";
 export { normalizeBasePath, renderGitHubPagesWorkflow, repoRelativeInputPath };

package/dist/{github-pages-qzowPgcG.mjs → github-pages-CbcFNgKi.mjs}

@@ -54,7 +54,7 @@ ${pnpmActionSetupOptions}      - uses: actions/setup-node@49933ea5288caeca8642d1
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm run build
-      - run: pnpm dlx --package lildocs@${patchVersionRange(options.lildocsVersion ?? "0.1.22")} lildocs ${deployArgs.map(shellQuote).join(" ")}
+      - run: pnpm dlx lildocs@${patchVersionRange(options.lildocsVersion ?? "0.1.23")} ${deployArgs.map(shellQuote).join(" ")}
       - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b
       - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa
         with:

package/docs/assets/favicon.svg

@@ -0,0 +1,13 @@
+<svg width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_1_2)">
+<path d="M5.11698 5.72303L5.98949 5.72097C6.59708 5.72008 7.08739 5.65352 7.55885 6.12297C7.95541 6.51779 8.35186 6.91721 8.74704 7.31365L9.24895 7.81657C9.43919 8.00722 9.63506 8.18194 9.77234 8.41446C9.91283 8.65252 9.98544 8.92681 9.98739 9.20283C9.98957 9.49719 9.98819 9.7926 9.98773 10.0871L9.97935 12.1872L9.97923 13.483C9.97877 13.8008 9.9944 14.1797 9.93076 14.486C9.85721 14.8302 9.68906 15.1468 9.44539 15.3998C9.07008 15.7914 8.58322 15.9935 8.04536 15.9943C7.58056 15.995 7.11542 15.9943 6.65062 15.9944L3.82548 15.9941L2.60156 15.9947C2.29086 15.9952 1.896 16.0116 1.60101 15.9508C1.24514 15.8756 0.918547 15.6985 0.660645 15.441C0.25402 15.0383 0.0981978 14.5938 0.0957624 14.0317L0.0955787 9.46246L0.0954981 8.22245C0.0951419 7.42557 0.0571172 6.89988 0.667044 6.28567C0.922399 6.026 1.24665 5.8455 1.60122 5.76565C1.86805 5.70362 2.37682 5.7209 2.67353 5.72104L4.04813 5.72239C4.34301 5.72764 4.8299 5.73676 5.11698 5.72303Z" fill="#091C33"/>
+<path d="M2.04379 6.78103C2.17184 6.77242 2.36456 6.77756 2.49755 6.7776L3.29003 6.77796L5.74893 6.7777L5.74859 8.46547C5.74974 8.90719 5.81108 9.2971 6.14136 9.6232C6.30489 9.78293 6.50783 9.89601 6.72931 9.95081C7.00984 10.0227 7.46017 10.0062 7.76081 10.0062L8.90753 10.0047C8.89363 10.9628 8.90178 11.9481 8.90006 12.9086L8.89868 13.6674C8.89845 13.8445 8.90845 14.0326 8.87961 14.2073C8.80379 14.6663 8.46467 14.9129 8.01653 14.9271L3.99575 14.9281L2.62705 14.929C2.22627 14.9286 1.79021 14.9989 1.46933 14.7209C1.13264 14.4292 1.17662 14.0814 1.17672 13.6788L1.17708 12.9021L1.17749 10.4668L1.17707 8.55905C1.17703 8.4395 1.17689 8.31799 1.17691 8.19937C1.177 7.71465 1.11037 7.19671 1.59524 6.91083C1.75343 6.81756 1.86165 6.79418 2.04379 6.78103Z" fill="white"/>
+<path d="M6.83109 6.93333C6.89094 6.97812 7.03305 7.12698 7.08773 7.18283L7.48004 7.57966C7.91624 8.01946 8.39517 8.48566 8.81643 8.93523C8.45548 8.96719 8.04134 8.92623 7.67522 8.94146C7.48567 8.94942 7.27246 8.94746 7.08463 8.93281C6.95803 8.923 6.85085 8.81211 6.84109 8.6861C6.82259 8.48566 6.83052 8.27957 6.83052 8.07821L6.83109 6.93333Z" fill="white"/>
+<path d="M4.64024 3.16599C4.7998 2.9671 4.78717 2.864 4.84736 2.62633C5.23623 1.09003 6.73321 0.205269 8.21906 0.0470532C8.4047 0.0272979 8.58874 0.0193244 8.77542 0.0187243C9.03918 0.0199014 9.24378 -0.0112317 9.25722 0.318193C9.298 1.30861 8.99828 2.2963 8.312 3.02507C7.70658 3.6732 6.8844 4.02573 6.00477 4.05069C5.76697 4.05744 5.42451 4.02056 5.25541 4.19796C5.19283 4.26412 5.14962 4.34633 5.13054 4.43556C5.11905 4.49036 5.11549 4.54508 5.11526 4.60215C5.114 4.97203 5.11503 5.34211 5.11595 5.71201L5.11698 5.72303C4.8299 5.73676 4.34301 5.72764 4.04813 5.72239C4.09486 5.72103 4.12416 5.72814 4.1587 5.70563C4.17531 5.64458 4.17068 5.27943 4.16628 5.18513C4.14614 4.7547 4.31143 4.10338 3.68541 4.06024C3.43078 4.04269 3.1976 4.05786 2.95147 4.03014C1.95779 3.91024 1.07329 3.3404 0.550384 2.48322C0.143758 1.82427 -0.0276751 1.00772 0.024951 0.238698C0.0426423 -0.0197594 0.333676 0.023213 0.508763 0.0213898C1.91144 0.00678102 3.447 0.641374 4.14908 1.91744C4.25061 2.10333 4.33388 2.29872 4.39773 2.50082C4.49193 2.7935 4.44345 2.9276 4.64024 3.16599Z" fill="#36AC0F"/>
+</g>
+<defs>
+<clipPath id="clip0_1_2">
+<rect width="10" height="16" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/docs/assets/logo.svg

@@ -0,0 +1,12 @@
+<svg width="1170" height="279" viewBox="0 0 1170 279" fill="none" xmlns="http://www.w3.org/2000/svg">
+<style>
+  .wordmark { fill: #192638; }
+  @media (prefers-color-scheme: dark) {
+    .wordmark { fill: #fff; }
+  }
+</style>
+<path d="M538.97 7.16949C567.35 4.30853 564.81 24.1859 564.83 44.5269C564.87 72.7909 564.83 101.091 564.85 129.356L564.88 208.38C564.87 223.64 566.78 250.157 561.64 264.321C558.08 274.11 544.6 276.68 535.98 271.434C527.36 266.183 526.52 262.47 523.88 252.908C518.86 256.928 514.26 260.913 508.73 264.293C477.122 283.633 439.882 279.403 409.644 259.955C406.854 257.996 404.16 255.902 401.573 253.681C391.933 245.352 384.07 235.164 378.454 223.727C372.839 212.291 369.587 199.839 368.892 187.118C368.03 174.003 369.795 160.848 374.083 148.424C378.371 136.001 385.096 124.558 393.865 114.767C421.971 83.2562 470.672 73.4967 507.47 95.5806C510.8 97.5806 520.43 105.545 523.54 105.358C528.09 98.6633 522.31 30.5359 526.66 18.816C529.11 12.2311 532.99 9.97048 538.97 7.16949ZM527.18 177.097C525.37 144.43 497.575 119.325 464.893 120.845C431.8 122.384 406.31 150.61 408.141 183.688C409.972 216.766 438.423 242.006 471.483 239.882C504.13 237.785 528.99 209.764 527.18 177.097Z" class="wordmark"/>
+<path d="M684.93 82.7676C738.83 75.2808 788.58 112.948 796 166.861C803.42 220.774 765.69 270.48 711.77 277.832C657.94 285.171 608.35 247.523 600.94 193.705C593.53 139.887 631.12 90.2406 684.93 82.7676ZM758.58 177.227C756.88 144.421 729.11 119.087 696.28 120.398C685.678 120.823 675.378 124.051 666.43 129.755C657.483 135.459 650.21 143.434 645.35 152.866C640.491 162.299 638.22 172.852 638.77 183.449C639.32 194.046 642.671 204.309 648.48 213.188C654.292 222.067 662.356 229.246 671.847 233.992C681.339 238.738 691.92 240.882 702.51 240.205C735.29 238.109 760.29 210.033 758.58 177.227Z" class="wordmark"/>
+<path d="M1087.55 84.282C1090.71 83.9967 1093.88 83.8283 1097.06 83.777C1116.06 83.619 1163.23 92.858 1162.99 117.179C1162.96 119.45 1162.48 121.692 1161.58 123.776C1160.67 125.86 1159.37 127.745 1157.73 129.321C1140.91 145.563 1121.35 113.103 1100.21 115.319C1086.61 116.743 1068.7 120.798 1069.25 138.47C1069.77 155.398 1095.97 159.763 1108.32 163.856C1137.68 172.439 1169.68 183.581 1169.48 219.67C1169.24 262.956 1132.41 276.609 1094.87 276.687C1070.51 275.53 1041.6 268.552 1026.25 248.042C1019.3 238.747 1026.87 222.658 1038.97 221.733C1051.25 220.793 1058.67 230.522 1067.67 236.72C1083.12 247.353 1115.46 249.972 1127.48 232.689C1146.8 204.017 1091.71 193.731 1073.1 187.922C1035.79 176.277 1016.6 144.553 1039.91 109.213C1049.89 94.071 1069.55 86.933 1087.55 84.282ZM840.15 230.585C826.55 205.705 822.15 181.089 830.25 153.349C833.73 141.224 839.584 129.911 847.472 120.067C855.36 110.223 865.125 102.044 876.2 96.005C901.63 82.221 932.98 80.533 960.37 88.777C969.69 91.582 988.76 98.983 993.25 108.081C995.68 112.984 996.6 116.698 994.93 122.031C994.124 124.569 992.818 126.92 991.091 128.947C989.363 130.974 987.248 132.635 984.87 133.834C968.17 142.119 943.08 106.915 901.1 126.001C893.916 129.251 887.452 133.9 882.084 139.676C876.717 145.452 872.555 152.24 869.84 159.643C864.343 174.282 864.857 190.501 871.27 204.763C884.6 233.777 914.23 245.687 944.4 237.905C960.53 233.743 982.69 214.204 993.75 235.346C1001.24 250.541 988.28 260.196 976.16 265.806C949.19 278.286 917.23 280.162 889.18 270.264C872.74 264.463 851.81 250.097 843.17 234.519L840.15 230.585ZM18.122 9.31499C24.009 8.55199 29.788 8.79499 35.243 11.32C41.083 14.023 44.037 18.875 45.566 24.913C48.727 37.391 47.081 52.426 47.059 65.276C47.009 95.889 43.559 196.579 51.67 218.224C58.43 236.263 72.178 231.22 86.138 237.692C90.11 239.534 93.323 242.257 94.775 246.5C96.392 251.227 96.022 258.549 93.731 263.024C90.593 269.156 84.682 271.889 78.501 273.905C31.295 279.975 4.32701 249.42 2.24701 204.616C-0.373987 148.151 1.85201 90.582 1.14301 33.983C0.98401 21.309 6.58401 13.994 18.122 9.31499ZM267.001 9.30098C272.593 8.45198 278.356 8.67599 283.575 11.02C289.278 13.581 292.76 18.341 294.435 24.246C297.923 36.54 296.171 51.995 296.145 64.767C296.09 92.546 292.482 197.937 300.666 218.934C307.359 236.105 320.853 231.46 334.369 237.649C338.447 239.516 342.254 242.231 343.822 246.622C345.531 251.41 344.658 258.576 342.41 263.125C339.516 268.982 333.772 271.602 327.969 273.655C234.238 286.258 251.888 176.431 250.686 117.8C250.112 89.753 250.532 61.507 250.598 33.453C250.628 20.873 255.694 14.317 267.001 9.30098ZM155.184 87.15C160.262 86.848 165.085 87.321 169.757 89.446C174.595 91.646 178.915 95.987 180.64 101.071C184.459 112.325 183.816 232.736 182.387 251.112C182.106 254.728 181.44 257.912 179.831 261.201C176.357 268.304 170.782 271.047 163.735 273.48C159.129 273.885 154.64 273.504 150.343 271.751C145.18 269.644 140.705 265.411 138.625 260.192C134.477 249.79 135.477 129.202 136.736 110.527C136.991 106.731 137.392 103.215 139.019 99.709C142.349 92.528 148.214 89.743 155.184 87.15Z" class="wordmark"/>
+<path d="M199.746 0.414981C203.01 0.0379807 203.675 -0.00801298 206.916 0.458987L207.92 1.89199C206.65 13.757 195.765 37.607 188.095 46.823C175.275 62.228 161.086 67.176 141.892 69.356C138.494 69.784 134.59 70.755 131.72 69.146C131.445 68.669 131.018 67.795 131.031 67.259C131.504 48.139 135.432 26.655 151.694 14.459C165.386 4.19099 183.235 2.08398 199.746 0.414981Z" fill="#38AC3C"/>
+</svg>

package/docs/config.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "../schemas/config.schema.json",
+  "link": {
+    "underline": "hover"
+  },
+  "favicon": "./assets/favicon.svg",
+  "logo": {
+    "image": "./assets/logo.svg"
+  },
+  "navigation": {
+    "order": [
+      "getting-started.md",
+      "features/content.md",
+      "features/navigation.md",
+      "features/search.md",
+      "features/mermaid.md",
+      "features/api-reference.md",
+      "guides/",
+      "reference/"
+    ],
+    "duration": 125
+  }
+}

package/docs/features/api-reference.md

@@ -0,0 +1,34 @@
+# Generated API Reference
+
+> Generate static API pages from a package's exported TypeScript declarations.
+
+Set `reference.packageJson` to a docs-root-relative package manifest:
+
+```json
+{
+  "reference": {
+    "packageJson": "../package.json"
+  }
+}
+```
+
+When the manifest exposes TypeScript declarations, lildocs generates API pages
+under `/reference/`. If `reference.packageJson` is not configured, lildocs also
+checks for a `package.json` next to the docs root. Sibling package manifests
+without an `exports` field are ignored.
+
+## Export Paths
+
+Reference pages are generated with `exports-md`. Package export maps follow
+relative imports and re-exports by default, and property comments render below
+declaration blocks.
+
+Each export uses its full package specifier as its pathname. For a package named
+`foo`, the `.` export is written to `/reference/foo.html`, while `./bar` is
+written to `/reference/foo/bar.html`.
+
+When the nearest package metadata points to a GitHub repository, generated
+symbol sections include GitHub code search links.
+
+See the [configuration reference](../reference/configuration.md#generated-reference)
+for the field summary.

package/docs/features/content.md

@@ -0,0 +1,86 @@
+# Writing Content
+
+> Use Markdown, frontmatter, links, assets, callouts, and page metadata to write
+> lildocs pages.
+
+Write normal Markdown files in your docs folder. lildocs supports standard and
+GitHub-flavored Markdown, syntax-highlighted code blocks with copy buttons,
+heading anchors, frontmatter, and local assets.
+
+## Page Titles
+
+Page titles are inferred in this order:
+
+1. `title` in frontmatter
+2. The first `h1`
+3. The filename
+
+Use frontmatter when the navigation label should differ from the visible page
+heading:
+
+```md
+---
+title: CLI Reference
+---
+
+# Command Line
+```
+
+## Page Subtitles
+
+Place a plain blockquote immediately after the page `h1` to render short
+supporting copy as a subtitle:
+
+```md
+# Command Line
+
+> Choose the command and flags for building, previewing, or deploying docs.
+```
+
+Keep subtitles brief and descriptive. Blockquotes elsewhere on the page continue
+to render as regular quoted notes unless they use GitHub-style callout syntax.
+
+## Links And Assets
+
+Use normal relative Markdown links:
+
+```md
+Read the [CLI reference](../reference/cli.md).
+```
+
+Use normal Markdown images for local assets:
+
+```md
+![Small example image](../images/example.svg)
+```
+
+![Small example image](../images/example.svg)
+
+Local assets referenced by Markdown are copied into the generated site.
+
+## Callouts
+
+Use GitHub-style blockquote callouts to highlight notes, tips, important
+details, warnings, and cautions:
+
+```md
+> [!NOTE]
+> Useful context for readers who are skimming.
+
+> [!WARNING]
+> Something readers should check before continuing.
+```
+
+Supported callout types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and
+`CAUTION`.
+
+> [!TIP]
+> Callouts are rendered as regular static HTML and work without client-side
+> JavaScript.
+
+## Related Features
+
+- [Navigation and page structure](navigation.md) explains how files become a
+  site hierarchy.
+- [Mermaid diagrams](mermaid.md) covers build-time diagram rendering.
+- [Local search](search.md) explains how page content is indexed.

package/docs/features/mermaid.md

@@ -0,0 +1,34 @@
+# Mermaid Diagrams
+
+> Add themed diagrams that lildocs renders to static SVG during the build.
+
+Use fenced `mermaid` code blocks:
+
+````md
+```mermaid
+flowchart LR
+  Markdown --> Build
+  Build --> StaticHTML[Static HTML]
+```
+````
+
+```mermaid
+flowchart LR
+  Markdown --> Build
+  Build --> StaticHTML[Static HTML]
+```
+
+## Static Rendering
+
+lildocs renders Mermaid diagrams during the build. Generated pages contain
+static SVG and do not load Mermaid from a CDN or require Mermaid client
+JavaScript.
+
+Readers can expand a rendered diagram to fill the viewport. Diagram colors come
+from the active Shiki theme and follow configured light and dark themes.
+
+Invalid Mermaid syntax fails the build with the source page and diagram number
+in the error message.
+
+See [Themes and styling](../reference/theming.md) to configure the themes used
+for syntax highlighting and diagrams.

package/docs/features/navigation.md

@@ -0,0 +1,92 @@
+# Navigation And Page Structure
+
+> Turn a Markdown file tree into a home page, sidebar groups, breadcrumbs, and
+> previous and next links.
+
+## Docs Root And Home Page
+
+When the input is a folder, lildocs treats that folder as the docs root and
+looks for a home page in this order:
+
+1. `README.md`
+2. `readme.md`
+3. `index.md`
+4. `intro.md`
+5. `introduction.md`
+6. `getting-started.md`
+7. `quickstart.md`
+
+If none of those files exists, the first Markdown file found in the folder tree
+is used as the home page.
+
+When the input is a Markdown file, that file becomes the home page and its
+parent folder becomes the docs root:
+
+```bash
+lildocs ./docs/index.md
+```
+
+## Generated Navigation
+
+Nested folders become nested navigation groups, and hidden or system files are
+ignored.
+
+```text
+docs/
+  index.md
+  getting-started.md
+  guides/
+    github-pages.md
+  reference/
+    cli.md
+```
+
+This tree creates a top-level sidebar link for `getting-started.md`, plus
+`Guides` and `Reference` groups. The home page is not repeated in the sidebar;
+the generated header brand links back to it instead.
+
+Pages inside folders show a small group breadcrumb above the page content. The
+label comes from the folder name.
+
+## Ordering Pages
+
+When the home page links to local Markdown documents, those pages are hoisted in
+the sidebar in first-reference order. Unlinked pages continue to use generated
+folder order.
+
+Use `navigation.order` when you want to make the order explicit:
+
+```json
+{
+  "navigation": {
+    "order": ["getting-started.md", "features/", "reference/"]
+  }
+}
+```
+
+Entries are docs-root-relative Markdown files or folders. Unlisted pages keep
+home-page link order, then generated order after listed siblings.
+
+Multi-page sites also get previous and next links at the bottom of each page.
+Those links follow the same order as the sidebar.
+
+## Page Transitions
+
+Enhanced page navigation can use a transition preset and custom timing:
+
+```json
+{
+  "navigation": {
+    "transition": "slide",
+    "duration": 160,
+    "easing": "cubic-bezier(0.16, 1, 0.3, 1)"
+  }
+}
+```
+
+`navigation.transition` accepts `fade`, `slide`, `scale`, or `instant`.
+`navigation.duration` is measured in milliseconds, and `navigation.easing`
+accepts any valid CSS timing function.
+
+See the [configuration reference](../reference/configuration.md#navigation) for
+the complete field summary.

package/docs/features/search.md

@@ -0,0 +1,28 @@
+# Local Search
+
+> Give readers fast section-level search without a hosted service.
+
+Search is generated locally at build time from page titles, headings, and body
+text. The generated `search-index.json` is emitted with the static site, so no
+external search service is required.
+
+## Section Results
+
+`h2` and `h3` sections get their own search entries. Results can link directly
+to the most useful section instead of only opening the top of a page:
+
+```md
+## Install
+
+Run the package manager command.
+
+### Local Files
+
+Place screenshots in the docs folder and reference them with relative paths.
+```
+
+## Search Interface
+
+The search UI highlights matching terms and supports Arrow Up, Arrow Down,
+Enter, and Escape. It also prefetches local result pages while readers browse
+results.

package/docs/getting-started.md

@@ -0,0 +1,94 @@
+# Getting Started
+
+> Install lildocs, build your first static docs site, and start the local
+> development server.
+
+Run lildocs directly with `pnpm dlx`:
+
+```bash
+pnpm dlx lildocs@0.1.x ./docs
+```
+
+Or add it to a project:
+
+```bash
+pnpm add -D lildocs
+```
+
+Then call it from package scripts:
+
+```json
+{
+  "scripts": {
+    "docs:build": "lildocs build ./docs",
+    "docs:dev": "lildocs dev ./docs"
+  }
+}
+```
+
+## Build A Site
+
+The shortest build command is:
+
+```bash
+lildocs ./docs
+```
+
+This treats `./docs` as the docs root, finds a home page, generates navigation
+from the folder structure, builds a local search index, copies assets, and writes
+the site to `dist`.
+
+Use the explicit `build` subcommand when a script or CI job should make the
+intent obvious:
+
+```bash
+lildocs build ./docs
+```
+
+If the input 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
+```
+
+The 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.
+
+## Preview Locally
+
+Use the development server while writing:
+
+```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 the 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.
+
+## Next Steps
+
+Read [Writing content](features/content.md) and
+[Navigation and page structure](features/navigation.md) to organize your docs.
+Then explore [local search](features/search.md),
+[Mermaid diagrams](features/mermaid.md), and the
+[generated API reference](features/api-reference.md), or use the
+[CLI reference](reference/cli.md) and
+[configuration reference](reference/configuration.md) for option details.

package/docs/guides/github-pages.md

@@ -0,0 +1,61 @@
+# GitHub Pages
+
+> Generate GitHub Pages-ready output and wire it into an Actions workflow without
+> changing how the static site is built.
+
+Use `deploy` to build GitHub Pages-ready output:
+
+```bash
+lildocs deploy ./docs
+```
+
+`deploy` builds the same static site as `build`, then adds Pages deployment
+metadata:
+
+- `.nojekyll`
+- `lildocs-deploy.json`
+
+The command prepares files only. It does not commit, push, or publish your site.
+
+## Project Pages
+
+Use `--base` for GitHub project pages metadata:
+
+```bash
+lildocs deploy ./docs --out ./site --base /repo-name/
+```
+
+Generated page links remain relative so the site can still be opened directly
+from disk.
+
+## GitHub Actions Workflow
+
+Use `init github-pages` to create a Pages workflow:
+
+```bash
+lildocs init github-pages ./docs --out ./site
+```
+
+This writes `.github/workflows/lildocs-pages.yml` if it does not already exist.
+The workflow installs dependencies with pnpm, builds the project, runs
+the current lildocs major and minor release line with `pnpm dlx`, uploads the
+output with `actions/upload-pages-artifact`, and deploys with
+`actions/deploy-pages`. Lildocs does not need to be a project dependency.
+
+Pass the same output and base path that the workflow should use:
+
+```bash
+lildocs init github-pages ./docs --out ./site --base /repo-name/
+```
+
+In the repository settings, set Pages source to **GitHub Actions** before relying
+on the workflow.
+
+## Repository Link
+
+Generated sites include a GitHub icon button before search when lildocs can
+detect a GitHub repository.
+
+During GitHub Actions builds, lildocs reads `GITHUB_REPOSITORY` as
+`<owner>/<repo>`. For local builds, it walks up from the docs root to the nearest
+`package.json` and uses the `repository` field when it points to GitHub.

package/docs/images/example.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="240" height="120" role="img" aria-label="Example image">
+  <rect width="240" height="120" fill="#f6f8fa"/>
+  <circle cx="72" cy="60" r="32" fill="#2563eb"/>
+  <path d="M120 42h72v12h-72zm0 24h54v12h-54z" fill="#111111"/>
+</svg>

package/docs/index.md

@@ -0,0 +1,46 @@
+# Introducing lildocs
+
+> A map of the lildocs documentation, from first build through content,
+> navigation, search, diagrams, configuration, and deployment.
+
+`lildocs` builds a static, searchable documentation site from Markdown files.
+The default path is intentionally short:
+
+```bash
+lildocs ./docs
+```
+
+Use this documentation to learn how lildocs resolves input, turns folders into
+site navigation, applies configuration, and prepares output for local preview or
+GitHub Pages.
+
+## Start Here
+
+- [Getting started](getting-started.md) covers installation, the first build, and
+  local development.
+- [CLI reference](reference/cli.md) lists every command and flag.
+
+## Features
+
+- [Writing content](features/content.md) covers Markdown, page metadata, links,
+  assets, and callouts.
+- [Navigation and page structure](features/navigation.md) explains home-page
+  discovery, generated sidebars, ordering, breadcrumbs, and transitions.
+- [Local search](features/search.md) covers the static index, section-level
+  results, and keyboard navigation.
+- [Mermaid diagrams](features/mermaid.md) explains build-time static rendering,
+  themes, and error reporting.
+- [Generated API reference](features/api-reference.md) turns exported TypeScript
+  declarations into static reference pages.
+
+## Configuration And Styling
+
+- [Configuration reference](reference/configuration.md) lists `config.json`
+  fields, schema support, precedence, and CLI flag mappings.
+- [Themes and styling](reference/theming.md) covers built-in themes, Shiki
+  themes, local `theme.ts`, fonts, backgrounds, and link styling.
+
+## Publishing
+
+- [GitHub Pages deployment](guides/github-pages.md) shows how to generate
+  Pages-ready output and initialize a deployment workflow.

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.22",
+  "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,7 +11,8 @@
     "lildocs": "dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "scripts": {