docula 0.50.0 → 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,9 +12,12 @@
 - [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)
@@ -76,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.
@@ -95,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',
@@ -133,19 +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
 
@@ -187,6 +237,70 @@ export const options = {
 };
 ```
 
+# 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.
@@ -245,7 +359,7 @@ This is useful for:
 
 # API Reference
 
-Docula can generate an API Reference page from an OpenAPI (Swagger) specification. The page is rendered using [Docutopia](https://www.npmjs.com/package/@docutopia/react) and is available at `/api`.
+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
 

package/dist/docula.d.ts

@@ -1,11 +1,73 @@
+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 {
@@ -20,7 +82,7 @@ declare class DoculaOptions {
     /**
      * Path to the output directory
      */
-    outputPath: string;
+    output: string;
     /**
      * Path to the site directory
      */
@@ -45,10 +107,6 @@ declare class DoculaOptions {
      * Port to run the server
      */
     port: number;
-    /**
-     * Single page website
-     */
-    singlePage: boolean;
     /**
      * Sections
      */
@@ -73,15 +131,150 @@ declare class DoculaOptions {
      * 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
@@ -104,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}
@@ -120,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
@@ -145,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
@@ -153,4 +359,4 @@ declare class Docula {
     serve(options: DoculaOptions): Promise<http.Server>;
 }
 
-export { Docula as default };
+export { DoculaOptions, Docula as default };