docula 0.41.1 → 0.90.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![tests](https://github.com/jaredwray/docula/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/docula/actions/workflows/tests.yaml)
 [![GitHub license](https://img.shields.io/github/license/jaredwray/docula)](https://github.com/jaredwray/docula/blob/master/LICENSE)
-[![codecov](https://codecov.io/gh/jaredwray/docula/graph/badge.svg?token=RS0GPY4V4M)](https://codecov.io/gh/jaredwray/docula)
+[![codecov](https://codecov.io/gh/jaredwray/docula/branch/main/graph/badge.svg?token=RS0GPY4V4M)](https://codecov.io/gh/jaredwray/docula)
 [![npm](https://img.shields.io/npm/dm/docula)](https://npmjs.com/package/docula)
 [![npm](https://img.shields.io/npm/v/docula)](https://npmjs.com/package/docula)
 
@@ -12,10 +12,15 @@
 - [Features](#features)
 - [Open Source Examples](#open-source-examples)
 - [Getting Started](#getting-started)
+  - [Serve your site locally](#serve-your-site-locally)
 - [TypeScript Configuration](#typescript-configuration)
+- [Theme Mode](#theme-mode)
 - [Using Your own Template](#using-your-own-template)
 - [Building Multiple Pages](#building-multiple-pages)
+- [Including Assets in Markdown](#including-assets-in-markdown)
 - [Public Folder](#public-folder)
+- [API Reference](#api-reference)
+- [LLM Files](#llm-files)
 - [Announcements](#announcements)
 - [Changelog](#changelog)
 - [Alert, Info, Warn Styling](#alert-info-warn-styling)
@@ -32,6 +37,7 @@
 * Full TypeScript support with typed configuration and IDE autocompletion.
 * Support for single page with readme or multiple markdown pages in a docs folder.
 * Will generate a sitemap.xml and robots.txt for your site.
+* Automatically generates `llms.txt` and `llms-full.txt` for LLM-friendly indexing of docs, API reference, and changelog content.
 * Uses Github release notes to generate a changelog / releases page.
 * Uses Github to show contributors and link to their profiles.
 * Simple search is provided by default out of the box.
@@ -73,6 +79,38 @@ Simply replace the logo, favicon, and css file with your own. The readme is your
 
 This will build your site and place it in the `dist` folder. You can then host it anywhere you like.
 
+## Serve your site locally
+
+> npx docula serve
+
+This will build and serve your site locally at `http://localhost:3000`. You can specify a custom port with the `-p` or `--port` flag:
+
+> npx docula serve -p 8080
+
+### CLI Options for serve
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port` | Set the port number | `3000` |
+| `-s, --site` | Set the path where site files are located | `./site` |
+| `-o, --output` | Set the output directory | `./site/dist` |
+| `-w, --watch` | Watch for changes and rebuild | `false` |
+| `-c, --clean` | Clean the output directory before building | `false` |
+
+### Watch Mode
+
+Use the `--watch` flag to automatically rebuild your site when files change:
+
+> npx docula serve --watch
+
+When watch mode is enabled:
+1. An initial build runs at startup
+2. The dev server starts and serves your site
+3. File changes in `sitePath` (e.g., `./site`) are detected and trigger an automatic rebuild
+4. Changes in the output directory are ignored to prevent rebuild loops
+
+This is useful during development when you want to see changes reflected immediately without manually re-running the build.
+
 # TypeScript Configuration
 
 Docula supports TypeScript configuration files (`docula.config.ts`) in addition to JavaScript (`docula.config.mjs`). TypeScript configs provide type safety and better IDE support.
@@ -92,7 +130,7 @@ import type { DoculaOptions } from 'docula';
 
 export const options: Partial<DoculaOptions> = {
   templatePath: './template',
-  outputPath: './dist',
+  output: './dist',
   sitePath: './site',
   githubPath: 'your-username/your-repo',
   siteTitle: 'My Project',
@@ -130,15 +168,34 @@ When both config files exist, Docula loads them in this order (first found wins)
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `templatePath` | `string` | `'./template'` | Path to custom template directory |
-| `outputPath` | `string` | `'./dist'` | Output directory for built site |
+| `output` | `string` | `'./dist'` | Output directory for built site |
 | `sitePath` | `string` | `'./site'` | Directory containing site content |
 | `githubPath` | `string` | - | GitHub repository path (e.g., `'user/repo'`) |
 | `siteTitle` | `string` | `'docula'` | Website title |
 | `siteDescription` | `string` | - | Website description |
 | `siteUrl` | `string` | - | Website URL |
 | `port` | `number` | `3000` | Port for local development server |
-| `singlePage` | `boolean` | `true` | Single page or multi-page site |
+| `homePage` | `boolean` | `true` | When `false`, Docula uses the first docs page as `/index.html` instead of rendering `home.hbs` |
 | `sections` | `DoculaSection[]` | - | Documentation sections |
+| `openApiUrl` | `string` | - | OpenAPI spec URL for API documentation (auto-detected if `api/swagger.json` exists) |
+| `enableReleaseChangelog` | `boolean` | `true` | Convert GitHub releases to changelog entries |
+| `enableLlmsTxt` | `boolean` | `true` | Generate `llms.txt` and `llms-full.txt` in the build output |
+| `themeMode` | `'light'` \| `'dark'` | - | Override the default theme. By default the site follows the system preference. Set to `'light'` or `'dark'` to use that theme when no user preference is stored. |
+| `allowedAssets` | `string[]` | *(see [Including Assets in Markdown](#including-images-and-assets-in-markdown))* | File extensions to copy from `docs/` and `changelog/` to output |
+
+## Theme Mode
+
+By default, the site follows the user's system color scheme preference. The theme toggle cycles through three modes: **system** (follows OS preference), **light**, and **dark**. The user's choice is persisted in `localStorage`.
+
+To set the initial theme mode, use `themeMode`:
+
+```js
+export const options = {
+  themeMode: 'dark',
+};
+```
+
+When `themeMode` is set, new visitors see the specified theme instead of the system preference. Once a user clicks the theme toggle, their choice takes priority and is remembered across visits.
 
 # Using Your own Template
 
@@ -172,6 +229,78 @@ title: Getting Started
 order: 2
 ```
 
+If you want your docs to be the root home page (`/`) instead of rendering the template home page, set `homePage: false`:
+
+```js
+export const options = {
+  homePage: false,
+};
+```
+
+# Including Assets in Markdown
+
+Non-markdown files placed inside the `docs/` or `changelog/` directories are automatically copied to the build output, preserving their relative paths. This lets you keep images and other assets alongside the markdown that references them.
+
+For `docs/`, only assets that are actually referenced in a document's markdown content are copied. If a file exists in the `docs/` directory but is not referenced by any document, it will not be included in the build output. For `changelog/`, all assets are copied regardless of whether they are referenced.
+
+```
+site
+├───docs
+│   ├───getting-started.md
+│   ├───images
+│   │   ├───architecture.png
+│   │   └───screenshot.jpg
+│   └───assets
+│       └───example.pdf
+├───changelog
+│   ├───2025-01-15-initial-release.md
+│   └───images
+│       └───release-banner.png
+```
+
+After building, these files appear at the same relative paths under `dist/`:
+
+```
+dist
+├───docs
+│   ├───getting-started
+│   │   └───index.html
+│   ├───images
+│   │   ├───architecture.png
+│   │   └───screenshot.jpg
+│   └───assets
+│       └───example.pdf
+├───changelog
+│   ├───initial-release
+│   │   └───index.html
+│   └───images
+│       └───release-banner.png
+```
+
+Reference assets from your markdown using relative paths:
+
+```md
+![Architecture](images/architecture.png)
+[Download PDF](assets/example.pdf)
+```
+
+## Supported Extensions
+
+By default the following file extensions are copied:
+
+**Images:** `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico`
+**Documents:** `.pdf`, `.zip`, `.tar`, `.gz`
+**Media:** `.mp4`, `.webm`, `.ogg`, `.mp3`, `.wav`
+**Data:** `.json`, `.xml`, `.csv`, `.txt`
+
+Files with extensions not in this list are ignored. To customize the list, set `allowedAssets` in your config:
+
+```js
+export const options = {
+  allowedAssets: ['.png', '.jpg', '.gif', '.svg', '.pdf', '.custom'],
+};
+```
+
 # Public Folder
 
 If you have static assets like images, fonts, or other files that need to be copied directly to your built site, you can use a `public` folder. Any files placed in the `public` folder within your site directory will be automatically copied to the root of your `dist` output folder during the build process.
@@ -228,6 +357,101 @@ This is useful for:
 - Custom fonts
 - Any other static assets that need to be served from your site
 
+# API Reference
+
+Docula can generate an API Reference page from an OpenAPI (Swagger) specification. The spec is parsed at build time and rendered as a native, interactive API reference (inspired by [Scalar](https://github.com/scalar/scalar)) with grouped endpoints, method badges, schema tables, code examples, and search — all with no external dependencies. The page is available at `/api`.
+
+## Auto-Detection
+
+If your site directory contains an `api/swagger.json` file, Docula will automatically detect it and generate the API Reference page — no configuration needed:
+
+```
+site
+├───api
+│   └───swagger.json
+├───docs
+├───logo.svg
+├───favicon.ico
+└───docula.config.mjs
+```
+
+## Explicit Configuration
+
+You can also set the `openApiUrl` option in your config to point to any OpenAPI spec, either a local path or a remote URL:
+
+```js
+export const options = {
+  openApiUrl: '/api/swagger.json',
+  // or a remote URL:
+  // openApiUrl: 'https://petstore.swagger.io/v2/swagger.json',
+};
+```
+
+When `openApiUrl` is set explicitly, it takes priority over auto-detection.
+
+## Spec Requirements
+
+The file must be a valid OpenAPI 3.x or Swagger 2.0 JSON specification. A minimal example:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "My API",
+    "version": "1.0.0"
+  },
+  "paths": {}
+}
+```
+
+# LLM Files
+
+Docula generates two LLM-focused files in the output directory by default:
+
+- `/llms.txt` - a compact index of your docs, API reference, and changelog URLs.
+- `/llms-full.txt` - expanded content including markdown bodies for docs/changelog and local OpenAPI spec text.
+
+## What Gets Included
+
+`/llms.txt` includes:
+- Site title and description
+- A link to `/llms-full.txt`
+- Documentation links (absolute URLs)
+- API Reference link when API docs are generated
+- Changelog landing page and the latest 20 changelog entries
+
+`/llms-full.txt` includes:
+- Site title and description
+- Full markdown body for each docs page
+- Full markdown body for each changelog entry
+- Full local OpenAPI spec text when available (for example `site/api/swagger.json`)
+
+If `openApiUrl` points to a remote URL, `/llms-full.txt` includes only the URL reference instead of fetching content over the network.
+
+## Configuration
+
+To disable generation:
+
+```js
+export const options = {
+  enableLlmsTxt: false,
+};
+```
+
+## Custom Overrides
+
+You can override generated output by providing custom files in your site directory:
+
+- `site/llms.txt`
+- `site/llms-full.txt`
+
+If present, Docula copies these files to output as-is.
+
+## Notes
+
+- These files are generated in the output root (`dist/llms.txt` and `dist/llms-full.txt`).
+- They are not added to `sitemap.xml`.
+
 # Announcements
 
 You can display an announcement banner on your home page by creating an `announcement.md` file in your site directory. This is useful for highlighting important updates, new releases, or any time-sensitive information.

package/dist/docula.d.ts

@@ -1,22 +1,88 @@
+import fs from 'node:fs';
 import http from 'node:http';
 export { Writr } from 'writr';
 
-type DoculaSection = {
+type ApiSchemaProperty = {
     name: string;
-    order?: number;
+    type: string;
+    required: boolean;
+    description: string;
+    enumValues?: string[];
+};
+type ApiOperationParameter = {
+    name: string;
+    in: string;
+    required: boolean;
+    type: string;
+    description: string;
+};
+type ApiRequestBody = {
+    contentType: string;
+    schemaProperties: ApiSchemaProperty[];
+    example: string;
+};
+type ApiResponse = {
+    statusCode: string;
+    statusClass: string;
+    description: string;
+    contentType: string;
+    schemaProperties: ApiSchemaProperty[];
+    example: string;
+};
+type ApiCodeExamples = {
+    curl: string;
+    javascript: string;
+    python: string;
+};
+type ApiOperation = {
+    id: string;
+    method: string;
+    methodUpper: string;
     path: string;
-    children?: DoculaSection[];
+    summary: string;
+    description: string;
+    parameters: ApiOperationParameter[];
+    requestBody?: ApiRequestBody;
+    responses: ApiResponse[];
+    codeExamples: ApiCodeExamples;
+};
+type ApiGroup = {
+    name: string;
+    description: string;
+    id: string;
+    operations: ApiOperation[];
+};
+type ApiSpecData = {
+    info: {
+        title: string;
+        description: string;
+        version: string;
+    };
+    servers: Array<{
+        url: string;
+        description: string;
+    }>;
+    groups: ApiGroup[];
+};
+
+type GithubData = {
+    releases: Record<string, unknown>;
+    contributors: Record<string, unknown>;
 };
 
 declare class DoculaOptions {
     /**
-     * Path to the template directory
+     * Name of the built-in template to use (e.g., "modern", "classic")
+     */
+    template: string;
+    /**
+     * Path to the template directory. When set, overrides the `template` option.
      */
     templatePath: string;
     /**
      * Path to the output directory
      */
-    outputPath: string;
+    output: string;
     /**
      * Path to the site directory
      */
@@ -41,10 +107,6 @@ declare class DoculaOptions {
      * Port to run the server
      */
     port: number;
-    /**
-     * Single page website
-     */
-    singlePage: boolean;
     /**
      * Sections
      */
@@ -55,15 +117,164 @@ declare class DoculaOptions {
      * Supports both external URLs (https://...) and relative paths (/openapi.json)
      */
     openApiUrl?: string;
+    /**
+     * When true, GitHub releases are converted to changelog entries and merged
+     * with file-based changelog entries. Requires a changelog template to exist.
+     */
+    enableReleaseChangelog: boolean;
+    /**
+     * When false, the first document becomes the home page (index.html)
+     * and the home.hbs template is not rendered.
+     */
+    homePage: boolean;
+    /**
+     * When true, generates llms.txt and llms-full.txt files for the built site.
+     */
+    enableLlmsTxt: boolean;
+    /**
+     * Override the default theme toggle. By default the site follows the system
+     * preference. Set to "light" or "dark" to use that theme when no user
+     * preference is stored in localStorage.
+     */
+    themeMode?: "light" | "dark";
+    /**
+     * When true, automatically adds generated paths (e.g., .cache) to the
+     * site directory's .gitignore file if not already present.
+     */
+    autoUpdateIgnores: boolean;
+    /**
+     * File extensions to copy as assets from docs/ and changelog/ directories.
+     * Override in docula.config to customize.
+     */
+    allowedAssets: string[];
     constructor(options?: Record<string, unknown>);
     parseOptions(options: Record<string, any>): void;
 }
 
+type DoculaChangelogEntry = {
+    title: string;
+    date: string;
+    formattedDate: string;
+    tag?: string;
+    tagClass?: string;
+    slug: string;
+    content: string;
+    generatedHtml: string;
+    urlPath: string;
+};
+type DoculaData = {
+    siteUrl: string;
+    siteTitle: string;
+    siteDescription: string;
+    sitePath: string;
+    templatePath: string;
+    output: string;
+    githubPath?: string;
+    github?: GithubData;
+    templates?: DoculaTemplates;
+    hasDocuments?: boolean;
+    hasChangelog?: boolean;
+    sections?: DoculaSection[];
+    documents?: DoculaDocument[];
+    sidebarItems?: DoculaSection[];
+    announcement?: string;
+    openApiUrl?: string;
+    hasApi?: boolean;
+    apiSpec?: ApiSpecData;
+    changelogEntries?: DoculaChangelogEntry[];
+    homePage?: boolean;
+    themeMode?: string;
+};
+type DoculaTemplates = {
+    home: string;
+    docPage?: string;
+    api?: string;
+    changelog?: string;
+    changelogEntry?: string;
+};
+type DoculaSection = {
+    name: string;
+    order?: number;
+    path: string;
+    children?: DoculaSection[];
+};
+type DoculaDocument = {
+    title: string;
+    navTitle: string;
+    description: string;
+    order?: number;
+    section?: string;
+    keywords: string[];
+    content: string;
+    markdown: string;
+    generatedHtml: string;
+    documentPath: string;
+    urlPath: string;
+    isRoot: boolean;
+};
+declare class DoculaBuilder {
+    private readonly _options;
+    private readonly _ecto;
+    private readonly _console;
+    constructor(options?: DoculaOptions, engineOptions?: any);
+    get options(): DoculaOptions;
+    build(): Promise<void>;
+    validateOptions(options: DoculaOptions): void;
+    getGithubData(githubPath: string): Promise<GithubData>;
+    getTemplates(templatePath: string, hasDocuments: boolean, hasChangelog?: boolean): Promise<DoculaTemplates>;
+    getTemplateFile(path: string, name: string): Promise<string | undefined>;
+    buildRobotsPage(options: DoculaOptions): Promise<void>;
+    buildSiteMapPage(data: DoculaData): Promise<void>;
+    buildLlmsFiles(data: DoculaData): Promise<void>;
+    private generateLlmsIndexContent;
+    private generateLlmsFullContent;
+    private buildAbsoluteSiteUrl;
+    private normalizePathForUrl;
+    private isRemoteUrl;
+    private resolveOpenApiSpecUrl;
+    private resolveLocalOpenApiPath;
+    private getSafeSiteOverrideFileContent;
+    private getSafeLocalOpenApiSpec;
+    private isPathWithinBasePath;
+    private toPosixPath;
+    buildIndexPage(data: DoculaData): Promise<void>;
+    buildDocsHomePage(data: DoculaData): Promise<void>;
+    buildReadmeSection(data: DoculaData): Promise<string>;
+    buildAnnouncementSection(data: DoculaData): Promise<string | undefined>;
+    buildDocsPages(data: DoculaData): Promise<void>;
+    buildApiPage(data: DoculaData): Promise<void>;
+    getChangelogEntries(changelogPath: string): DoculaChangelogEntry[];
+    parseChangelogEntry(filePath: string): DoculaChangelogEntry;
+    convertReleaseToChangelogEntry(release: Record<string, any>): DoculaChangelogEntry;
+    getReleasesAsChangelogEntries(releases: any[]): DoculaChangelogEntry[];
+    buildChangelogPage(data: DoculaData): Promise<void>;
+    buildChangelogEntryPages(data: DoculaData): Promise<void>;
+    generateSidebarItems(data: DoculaData): DoculaSection[];
+    getDocuments(sitePath: string, doculaData: DoculaData): DoculaDocument[];
+    getDocumentInDirectory(sitePath: string): DoculaDocument[];
+    getSections(sitePath: string, doculaOptions: DoculaOptions): DoculaSection[];
+    mergeSectionWithOptions(section: DoculaSection, options: DoculaOptions): DoculaSection;
+    parseDocumentData(documentPath: string): DoculaDocument;
+    private hasTableOfContents;
+    private directoryContainsMarkdown;
+    private mergeTemplateOverrides;
+    private ensureCacheInGitignore;
+    private isCacheFresh;
+    private listFilesRecursive;
+    private copyDirectory;
+    private copyPublicFolder;
+    private copyPublicDirectory;
+    private copyDocumentSiblingAssets;
+    private listContentAssets;
+    private copyContentAssets;
+}
+
 declare class Docula {
     private _options;
     private readonly _console;
     private _configFileModule;
     private _server;
+    private _watcher;
     /**
      * Initialize the Docula class
      * @param {DoculaOptions} options
@@ -86,11 +297,23 @@ declare class Docula {
      * @returns {http.Server | undefined}
      */
     get server(): http.Server | undefined;
+    /**
+     * The file watcher used in watch mode
+     * @returns {fs.FSWatcher | undefined}
+     */
+    get watcher(): fs.FSWatcher | undefined;
     /**
      * The config file module. This is the module that is loaded from the docula.config.ts or docula.config.mjs file
      * @returns {any}
      */
     get configFileModule(): any;
+    /**
+     * Remove the .cache directory inside the site path.
+     * Resolves the path and verifies it stays within sitePath to prevent
+     * path-traversal attacks.
+     * @param {string} sitePath
+     */
+    private cleanCache;
     /**
      * Check for updates
      * @returns {void}
@@ -102,12 +325,6 @@ declare class Docula {
      * @returns {Promise<void>}
      */
     execute(process: NodeJS.Process): Promise<void>;
-    /**
-     * Checks if the site is a single page website
-     * @param {string} sitePath
-     * @returns {boolean}
-     */
-    isSinglePageWebsite(sitePath: string): boolean;
     /**
      * Generate the init files
      * @param {string} sitePath
@@ -127,6 +344,13 @@ declare class Docula {
      * @returns {Promise<void>}
      */
     loadConfigFile(sitePath: string): Promise<void>;
+    /**
+     * Watch the site path for file changes and rebuild on change
+     * @param {DoculaOptions} options
+     * @param {DoculaBuilder} builder
+     * @returns {fs.FSWatcher}
+     */
+    watch(options: DoculaOptions, builder: DoculaBuilder): fs.FSWatcher;
     /**
      * Serve the site based on the options (port and output path)
      * @param {DoculaOptions} options
@@ -135,4 +359,4 @@ declare class Docula {
     serve(options: DoculaOptions): Promise<http.Server>;
 }
 
-export { Docula as default };
+export { DoculaOptions, Docula as default };