docula 0.41.0 → 0.50.0

package/README.md

@@ -16,6 +16,8 @@
 - [Using Your own Template](#using-your-own-template)
 - [Building Multiple Pages](#building-multiple-pages)
 - [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 +34,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.
@@ -138,7 +141,11 @@ When both config files exist, Docula loads them in this order (first found wins)
 | `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 |
 
 # Using Your own Template
 
@@ -172,6 +179,14 @@ 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,
+};
+```
+
 # 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 +243,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 page is rendered using [Docutopia](https://www.npmjs.com/package/@docutopia/react) and 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

@@ -0,0 +1,156 @@
+import http from 'node:http';
+export { Writr } from 'writr';
+
+type DoculaSection = {
+    name: string;
+    order?: number;
+    path: string;
+    children?: DoculaSection[];
+};
+
+declare class DoculaOptions {
+    /**
+     * 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;
+    /**
+     * Path to the site directory
+     */
+    sitePath: string;
+    /**
+     * Path to the github repository
+     */
+    githubPath: string;
+    /**
+     * Site title
+     */
+    siteTitle: string;
+    /**
+     * Site description
+     */
+    siteDescription: string;
+    /**
+     * Site URL
+     */
+    siteUrl: string;
+    /**
+     * Port to run the server
+     */
+    port: number;
+    /**
+     * Single page website
+     */
+    singlePage: boolean;
+    /**
+     * Sections
+     */
+    sections?: DoculaSection[];
+    /**
+     * OpenAPI specification URL for API documentation.
+     * When provided, creates a dedicated /api page
+     * 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;
+    constructor(options?: Record<string, unknown>);
+    parseOptions(options: Record<string, any>): void;
+}
+
+declare class Docula {
+    private _options;
+    private readonly _console;
+    private _configFileModule;
+    private _server;
+    /**
+     * Initialize the Docula class
+     * @param {DoculaOptions} options
+     * @returns {void}
+     * @constructor
+     */
+    constructor(options?: DoculaOptions);
+    /**
+     * Get the options
+     * @returns {DoculaOptions}
+     */
+    get options(): DoculaOptions;
+    /**
+     * Set the options
+     * @param {DoculaOptions} value
+     */
+    set options(value: DoculaOptions);
+    /**
+     * The http server used to serve the site
+     * @returns {http.Server | undefined}
+     */
+    get server(): http.Server | 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;
+    /**
+     * Check for updates
+     * @returns {void}
+     */
+    checkForUpdates(): void;
+    /**
+     * Is the execution process that runs the docula command
+     * @param {NodeJS.Process} process
+     * @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
+     * @param {boolean} typescript - If true, generates docula.config.ts instead of docula.config.mjs
+     * @returns {void}
+     */
+    generateInit(sitePath: string, typescript?: boolean): void;
+    /**
+     * Get the version of the package
+     * @returns {string}
+     */
+    getVersion(): string;
+    /**
+     * Load the config file. Supports both .mjs and .ts config files.
+     * Priority: docula.config.ts > docula.config.mjs
+     * @param {string} sitePath
+     * @returns {Promise<void>}
+     */
+    loadConfigFile(sitePath: string): Promise<void>;
+    /**
+     * Serve the site based on the options (port and output path)
+     * @param {DoculaOptions} options
+     * @returns {Promise<void>}
+     */
+    serve(options: DoculaOptions): Promise<http.Server>;
+}
+
+export { Docula as default };