docula 0.41.1 → 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

@@ -10,7 +10,11 @@ type DoculaSection = {
 
 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;
     /**
@@ -55,6 +59,20 @@ 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;
     constructor(options?: Record<string, unknown>);
     parseOptions(options: Record<string, any>): void;
 }