@nikala-ui/folio 0.13.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Giorgi Magradze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO QUALITY AND FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @nikala-ui/folio
+
+![Folio documentation site](.github/assets/screenshot.png)
+
+`@nikala-ui/folio` is a file-based documentation engine for SolidJS projects.
+It compiles MDX content with Vite, renders server-side pages, and provides a
+responsive documentation theme with navigation, search, syntax highlighting,
+and Tailwind CSS v4 design tokens.
+
+## Features
+
+- File-based MDX routes from a configurable content directory.
+- Automatic sidebar categories derived from content directories.
+- Server-rendered production pages with client-side navigation.
+- Responsive sidebar, top navigation, breadcrumbs, table of contents, and
+  previous/next page navigation.
+- Local search and configurable page metadata.
+- Shiki syntax highlighting with lazy language and theme loading.
+- Custom themes, layouts, components, CSS, logos, and site metadata.
+- CLI initialization for a complete documentation project.
+
+The default theme uses the Nikala UI design system. Additional Nikala UI
+capabilities can be added from a generated project with:
+
+```bash
+bunx @nikala-ui/cli
+```
+
+## Installation
+
+Install the engine in an existing SolidJS project with your preferred package
+manager:
+
+```bash
+# Bun
+bun add @nikala-ui/folio
+
+# pnpm
+pnpm add @nikala-ui/folio
+
+# npm
+npm install @nikala-ui/folio
+
+# yarn
+yarn add @nikala-ui/folio
+```
+
+## Initialize a project
+
+Run the initializer from the project directory:
+
+```bash
+# Bun
+bunx @nikala-ui/folio init .
+
+# pnpm
+pnpm dlx @nikala-ui/folio init .
+
+# npm
+npx @nikala-ui/folio init .
+
+# yarn
+yarn dlx @nikala-ui/folio init .
+```
+
+The initializer creates the documentation structure, prepares the default
+theme, configures the `@/*` TypeScript alias, and installs the dependencies
+required by the generated project.
+
+```text
+.
+├── docs/
+│   └── index.mdx
+├── docs.config.ts
+├── nikala.config.json
+├── public/
+│   └── favicon.ico
+└── src/
+    ├── components/ui/
+    ├── hooks/
+    ├── index.css
+    ├── lib/
+    ├── providers/
+    └── themes/default/
+```
+
+The generated project receives `dev`, `build`, and `preview` scripts when
+they are not already defined. Existing `docs.config.ts` and
+`nikala.config.json` files are preserved.
+
+## Run a documentation project
+
+From the generated project root:
+
+```bash
+# Development server
+bun run dev
+
+# Production build
+bun run build
+
+# Production preview
+bun run preview
+```
+
+The equivalent commands are `pnpm run ...`, `npm run ...`, and `yarn ...`.
+The default development server runs at `http://localhost:1862/`.
+
+The CLI commands can also be run directly:
+
+```bash
+bunx @nikala-ui/folio dev
+bunx @nikala-ui/folio build
+bunx @nikala-ui/folio preview
+```
+
+## Content structure
+
+The default content directory is `docs/`. Every MDX file becomes a route and
+directories become sidebar categories:
+
+```text
+docs/
+├── index.mdx              -> /
+├── getting-started.mdx    -> /getting-started
+├── components/
+│   ├── button.mdx         -> /components/button
+│   └── dialog.mdx         -> /components/dialog
+└── guides/
+    └── theming.mdx        -> /guides/theming
+```
+
+Page metadata is defined with frontmatter:
+
+```mdx
+---
+title: Button
+description: A flexible action button for SolidJS applications.
+order: 1
+toc: true
+---
+
+# Button
+
+Button documentation goes here.
+```
+
+Supported page metadata includes `title`, `description`, `order`,
+`categoryOrder`, `icon`, `badge`, `addedAt`, `prev`, `next`, and `toc`.
+
+## Configuration
+
+Create `docs.config.ts` in the project root:
+
+```ts
+import type { DocsConfig } from "@nikala-ui/folio";
+
+const config: DocsConfig = {
+  title: "Project Documentation",
+  description: "Documentation for my SolidJS project.",
+  siteUrl: "https://docs.example.com",
+  contentDir: "docs",
+  favicon: "/favicon.ico",
+  navigation: {
+    layout: "sidebar",
+    navbar: [{ title: "Home", href: "/" }],
+    sidebar: {
+      nav: "auto",
+      header: true,
+      footer: false,
+      headerSubtitle: "Documentation",
+    },
+  },
+  search: {
+    enabled: true,
+  },
+};
+
+export default config;
+```
+
+See the [Configuration](/configuration) guide for the supported options.
+
+## Customize the theme
+
+The generated default theme is under `src/themes/default`. It can be
+modified directly or replaced with a custom theme configured through
+`theme.path`.
+
+The generated `src/index.css` contains the Tailwind CSS v4 entrypoint and
+semantic design tokens. Customize those tokens to change the site's colors,
+typography, spacing, and other visual properties.
+
+## Develop the engine
+
+Clone the repository and install its dependencies:
+
+```bash
+git clone https://github.com/nikala-ui/folio.git
+cd folio
+bun install
+```
+
+Useful repository commands:
+
+```bash
+bun run typecheck    # Run the strict TypeScript check
+bun run test         # Run unit and integration tests
+bunx playwright install chromium # Install the local browser test runtime
+bun run test:browser # Run browser, SSR, and hydration smoke tests
+bun run test:generated # Test a clean generated consumer project
+bun run package:check  # Validate the publishable package artifact
+bun run bundle:check   # Report and validate production bundle sizes
+bun run build        # Build the engine and CLI into dist/
+bun run docs:build   # Build the self-hosted site into .docs-dist/
+bun run check        # Run the complete local quality contract
+bun run docs:dev     # Run the self-hosted docs site
+bun run docs:preview # Preview the self-hosted production site
+```
+
+Read [Contributing](/contributing) before opening a pull request.

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,5 @@
+export interface BuildCommandOptions {
+    outDir?: string;
+}
+export declare function runBuildCommand(dir: string | undefined, options?: BuildCommandOptions): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/cli/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,GAAE,mBAAwB,iBAyB/F"}

package/dist/cli/commands/build.js

@@ -0,0 +1,28 @@
+// packages/docs/src/cli/commands/build.ts
+import pc from "picocolors";
+import { buildDocs } from "../../server/index.js";
+import { FOLIO_VERSION } from "../../version.js";
+export async function runBuildCommand(dir, options = {}) {
+    const outDir = options.outDir || "dist";
+    console.log();
+    console.log(pc.bold(pc.cyan("  Folio ")) + pc.dim(`v${FOLIO_VERSION}`));
+    console.log(pc.dim(`  Building documentation bundle from ${pc.bold(dir || "configured contentDir")} to ${pc.bold(outDir)}...`));
+    console.log();
+    const startTime = Date.now();
+    try {
+        await buildDocs({
+            docsDir: dir,
+            outDir,
+        });
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+        console.log();
+        console.log(`  ${pc.green("✓")} ${pc.bold("Build complete")} in ${pc.cyan(elapsed + "s")}`);
+        console.log(`  ${pc.green("➜")} Output directory: ${pc.cyan(outDir)}`);
+        console.log();
+    }
+    catch (err) {
+        console.error(pc.red(`  ✗ Build failed: ${err.message}`));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/cli/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMjD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAuB,EAAE,OAAO,GAAwB,EAAE;IAC9F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;IAExC,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC;IACxE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,wCAAwC,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,uBAAuB,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChI,OAAO,CAAC,GAAG,EAAE,CAAC;IAEd,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC;YACd,OAAO,EAAE,GAAG;YACZ,MAAM;SACP,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7D,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5F,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,qBAAqB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,7 @@
+export interface DevCommandOptions {
+    port?: string;
+    host?: string;
+    open?: boolean;
+}
+export declare function runDevCommand(dir: string | undefined, options?: DevCommandOptions): Promise<void>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/cli/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,GAAE,iBAAsB,iBA8B3F"}

package/dist/cli/commands/dev.js

@@ -0,0 +1,33 @@
+// packages/docs/src/cli/commands/dev.ts
+import pc from "picocolors";
+import { createDocsServer } from "../../server/index.js";
+import { FOLIO_VERSION } from "../../version.js";
+export async function runDevCommand(dir, options = {}) {
+    const port = options.port ? parseInt(options.port, 10) : 1862;
+    const host = options.host || "localhost";
+    const open = options.open ?? false;
+    console.log();
+    console.log(pc.bold(pc.cyan("  Folio ")) + pc.dim(`v${FOLIO_VERSION}`));
+    console.log(pc.dim("  Honoring Niko Pirosmani (Nikala) — Elegant docs for SolidJS"));
+    console.log();
+    try {
+        const server = await createDocsServer({
+            docsDir: dir,
+            port,
+            host,
+            open,
+        });
+        await server.listen();
+        const address = server.httpServer?.address();
+        const actualPort = typeof address === "object" && address ? address.port : port;
+        console.log(`  ${pc.green("➜")}  ${pc.bold("Local:")}   ${pc.cyan(`http://${host}:${actualPort}/`)}`);
+        console.log(`  ${pc.green("➜")}  ${pc.bold("Content:")} ${pc.dim(dir || "configured contentDir")}`);
+        console.log(`  ${pc.green("➜")}  ${pc.bold("Press")}   ${pc.yellow("h + enter")} to show help`);
+        console.log();
+    }
+    catch (err) {
+        console.error(pc.red(`  ✗ Failed to start docs server: ${err.message}`));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/commands/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQjD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAuB,EAAE,OAAO,GAAsB,EAAE;IAC1F,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC;IAEnC,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC;IACxE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,+DAA+D,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,EAAE,CAAC;IAEd,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;YACpC,OAAO,EAAE,GAAG;YACZ,IAAI;YACJ,IAAI;YACJ,IAAI;SACL,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;QAC7C,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAEhF,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC,CAAC;QACtG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,uBAAuB,CAAC,EAAE,CAAC,CAAC;QACpG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QAChG,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,oCAAoC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,2 @@
+export declare function runInitCommand(targetDir?: string): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAgUA,wBAAsB,cAAc,CAAC,SAAS,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCnE"}