@sullux/markdown-docs 1.0.3 → 1.0.5

package/README.md

@@ -1,104 +1,37 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Markdown Docs" width="160" height="160" />
+</p>
+
 # @sullux/markdown-docs
 
 A zero-dependency, local-first static documentation website generator compiling GitBook-style Markdown documentation folders into fast, responsive, searchable HTML websites.
 
-Built on `@sullux/markdown-compiler` and `@sullux/markdown-html`, `@sullux/markdown-docs` operates as both a standalone CLI application and a Node.js library.
+📖 **Official Documentation:** [https://sullux.com/projects/markdown/markdown-docs/](https://sullux.com/projects/markdown/markdown-docs/)
 
-## Core Features
+## Overview
 
-* **GitBook `SUMMARY.md` Support:** Automatically parses `SUMMARY.md` navigation lists and `## Section` headers into sidebar navigation menus (with directory auto-discovery fallback if `SUMMARY.md` is omitted).
-* **Zero Dependencies:** Pure Vanilla JS implementation using Node.js built-ins.
-* **Declarative Site Configuration (`docs.yaml`):** Comprehensive YAML configuration file support for logos, themes, external links, favicons, and base URLs.
-* **Dual Light/Dark Branding:** Supports dual logos (`logo.light`, `logo.dark`) and dual color schemes with native OS system dark mode detection and client-side manual toggle persistence.
-* **Client-Side Search:** Auto-generates a lightweight JSON search index and embedded client-side search UI.
-* **Responsive 3-Column Layout:** Sticky header with top search bar, left navigation sidebar, center content stream, and right page outline (TOC) with responsive slide-in drawers for mobile.
-* **Rich Component Support:** Supports code syntax highlighting, callout boxes (`> [!NOTE]`, `{% hint %}`), GFM tables, and custom image dimensions.
-* **Static Asset Copying:** Automatically copies non-Markdown assets (images, SVGs, PDFs) directly to the output directory.
+Built on `@sullux/markdown-compiler` and `@sullux/markdown-html`, `@sullux/markdown-docs` compiles directories of Markdown files into production-ready static documentation sites with zero third-party dependencies. It operates both as a standalone CLI utility and as a Node.js library.
 
-## CLI Usage
+It features automatic `SUMMARY.md` navigation hierarchy parsing, embedded client-side search, a responsive 3-column layout with mobile navigation drawers, native dual light/dark themes with system preference tracking and toggle persistence, static asset bundling, and declarative `docs.yaml` site configuration.
 
-```bash
-# Generate site using default docs.yaml configuration in ./docs
-markdown-docs -i ./docs -o ./_site
+## Quick Start
 
-# Build with a custom base URL for CI/CD environments
-markdown-docs -i ./docs -o ./_site -b "/my-app-docs/"
-```
+### Installation
 
-### CLI Options
-
-| Flag | Long Flag | Description | Default |
-| :--- | :--- | :--- | :--- |
-| `-i` | `--input` | Path to input Markdown docs directory | Current working directory |
-| `-o` | `--output` | Path to output build directory | `<input>/_site` |
-| `-b` | `--base-url` | Base URL prefix for links and deployment | `""` |
-| `-t` | `--title` | Site title override (overrides `docs.yaml`) | `title` in `docs.yaml` |
-| `-c` | `--config` | Custom path to config file | `<input>/docs.yaml` |
-| `-h` | `--help` | Display CLI help menu | |
-
----
-
-## Site Configuration (`docs.yaml`)
-
-You can configure your documentation site by placing a `docs.yaml` (or `docs.yml` / `docs.json`) file in your input documentation directory.
-
-### Example `docs.yaml`
-
-```yaml
-# Site Title (Optional: omit or leave empty for logo-only headers)
-title: "BucketDB"
-
-# Output directory (Optional: can also be passed via CLI)
-output: "_site"
-
-# Base URL prefix (Optional: useful for GitHub Pages or subdirectory hosting)
-baseUrl: "/docs"
-
-# Brand Logo (Supports single path/SVG, or dual light/dark images)
-logo:
-  light: "assets/logo-light.svg"
-  dark: "assets/logo-dark.svg"
-
-# Favicon Asset Path or URL
-favicon: "assets/favicon.ico"
-
-# External Header Navigation Links
-links:
-  - title: "GitHub"
-    url: "https://github.com/sullux/coms"
-  - title: "API Spec"
-    url: "https://api.example.com"
-
-# Theme Color Overrides
-theme:
-  light:
-    bg: "#ffffff"
-    accent: "#2563eb"
-    codeBg: "#f8fafc"
-    codeText: "#0f172a"
-  dark:
-    bg: "#121316"
-    accent: "#3b82f6"
-    codeBg: "#0a0b0e"
-    codeText: "#f3f4f6"
+```bash
+yarn add @sullux/markdown-docs
+# or install globally
+yarn global add @sullux/markdown-docs
 ```
 
-### Configuration Options Reference
-
-| Property | Type | Description | Default |
-| :--- | :--- | :--- | :--- |
-| `title` | `string` | Product or site name displayed in header & `<title>` tag. Leave empty (`""`) or omit when using a logo image containing the product name. | `""` |
-| `output` | `string` | Relative or absolute path to output build directory. | `<input>/_site` |
-| `baseUrl` | `string` | Base URL path prefix for hosting in subdirectories. | `""` |
-| `logo` | `string \| object` | Asset path/SVG string, or `{ light: "...", dark: "..." }` object for automatic theme switching. | `""` |
-| `favicon` | `string` | Asset path or URL to icon file. | Default book emoji (`📚`) |
-| `links` | `array` | Header external links array `[{ title: "...", url: "..." }]`. | `[]` |
-| `theme.light` | `object` | Light theme color overrides (`bg`, `accent`, `codeBg`, `codeText`). | Built-in light colors |
-| `theme.dark` | `object` | Dark theme color overrides (`bg`, `accent`, `codeBg`, `codeText`). | Built-in dark colors |
+### Usage (CLI)
 
----
+```bash
+# Generate static HTML site from a docs directory
+markdown-docs -i ./docs -o ./_site -t "Project Documentation"
+```
 
-## Programmatic API Usage
+### Usage (Programmatic)
 
 ```javascript
 const { generateSite } = require('@sullux/markdown-docs')
@@ -112,8 +45,8 @@ const result = generateSite({
 console.log(`Generated ${result.pageCount} pages at ${result.output}`)
 ```
 
-## Running Unit Tests
+For complete guides, configuration options, and CLI references, see the [official documentation](https://sullux.com/projects/markdown/markdown-docs/).
 
-```bash
-yarn test
-```
+## Contributing & License
+
+Please see the [Monorepo README](../../README.md) for contribution guidelines, testing instructions, and license details.

package/lib/config.js

@@ -52,7 +52,10 @@ const normalizeConfig = (opts = {}) => {
   const input = path.resolve(opts.input || process.cwd())
   const fileConfig = loadFileConfig(input, opts.config)
 
-  const output = path.resolve(opts.output || fileConfig.output || path.join(input, '_site'))
+  const rawOutput = opts.output || fileConfig.output
+  const output = rawOutput
+    ? (path.isAbsolute(rawOutput) ? rawOutput : (opts.output ? path.resolve(rawOutput) : path.resolve(input, rawOutput)))
+    : path.join(input, '_site')
   const title = opts.title !== undefined ? opts.title : (fileConfig.title !== undefined ? fileConfig.title : '')
   const baseUrl = opts.baseUrl !== undefined ? opts.baseUrl : (fileConfig.baseUrl !== undefined ? fileConfig.baseUrl : '')
   const logo = fileConfig.logo || opts.logo || ''

package/lib/layout.js

@@ -101,7 +101,15 @@ const renderPageLayout = ({ title, siteTitle, navTree, toc, contentHtml, current
   <div class="app-container">
     <aside id="sidebar-drawer" class="app-sidebar"><div class="drawer-header"><span class="drawer-title">Navigation</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div><nav class="app-nav">${sidebarNav}</nav></aside>
     <main class="app-main"><article class="app-article">${contentHtml}</article></main>
-    <aside id="toc-drawer" class="app-toc"><div class="toc-container">${renderTocList(toc)}</div></aside>
+    <aside id="toc-drawer" class="app-toc">
+      <div class="drawer-header"><span class="drawer-title">Page Outline</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div>
+      <div class="toc-container">${renderTocList(toc)}</div>
+      <div class="theme-picker">
+        <button class="theme-opt" data-mode="light" onclick="setThemeMode('light')" title="Light">${SVGS.sun}</button>
+        <button class="theme-opt" data-mode="system" onclick="setThemeMode('system')" title="System">${SVGS.system}</button>
+        <button class="theme-opt" data-mode="dark" onclick="setThemeMode('dark')" title="Dark">${SVGS.moon}</button>
+      </div>
+    </aside>
   </div>
   <div id="drawer-backdrop" class="drawer-backdrop" onclick="closeAllDrawers()"></div>
   <script>${getSearchScript()}</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sullux/markdown-docs",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A zero-dependency, local-first static documentation site generator compiling GitBook-style Markdown docs.",
   "main": "./index.js",
   "bin": {