Beautiful Website for Your Projects

Features

• No configuration required. Just setup the folder structure with a logo, favicon, and css file.
• Builds a static website that can be hosted anywhere.
• Built-in, fully client-side search (⌘K / Ctrl K) with a keyboard-navigable modal and deep links to matching headings — no external service required.
• Support for single page with readme or multiple markdown pages in a docs folder.
• Full TypeScript support with typed configuration and IDE autocompletion.
• For more complex projects easily add a docula.config.ts (TypeScript) or docula.config.mjs (JavaScript) file to customize the build process with lifecycle hooks and DoculaConsole logging.
• Will generate a sitemap.xml, robots.txt, and feed.xml for your site.
• Automatically generates llms.txt and llms-full.txt for LLM-friendly indexing of docs, API reference, and changelog content.
• OpenAPI / Swagger support for auto-generating an interactive API reference page.
• Uses Github release notes and file-based changelog entries to generate a changelog with individual pages, pagination, and preview text.
• Uses Github to show contributors and link to their profiles.
• Light, dark, and system theme modes with a built-in toggle.
• Easy styling customization via variables.css with no template editing required.
• Watch mode with auto-rebuild for local development.

Table of Contents

• Getting Started
• Configuration
• CLI
• Templates
• Partial Templates
• Multiple Pages
• Assets
• Styling
• Custom Scripts
• API Reference
• LLM Files
• Announcements
• Changelog
• GitHub Integration
• GitHub Token
• Helper Utilities
• Header Links
• Caching
• Cookie Auth
• Robots & Sitemap
• Standalone Binary
• Open Source Examples
• Code of Conduct and Contributing
• Security
• License - MIT

Standalone Binary

You can build Docula as a standalone binary that runs without Node.js installed. This uses Node.js Single Executable Applications (SEA) to embed the runtime and all dependencies into a single executable.

Building the Binary

Requires Node.js >= 25.7.0 to build (the resulting binary does not need Node.js to run). The build uses tsdown's exe option, which wraps Node.js's Single Executable Applications feature added in Node 25.7.

pnpm install
pnpm build:binary

This produces a platform-specific binary at dist/docula (or dist/docula.exe on Windows).

What the Build Does

1. Embeds all built-in templates (modern, classic) into the bundle as base64
2. Bundles all source code and dependencies into a single CJS file via tsdown
3. Uses tsdown's built-in exe option to create a Node.js SEA binary — blob generation, injection, and (on macOS hosts) ad-hoc code signing are handled automatically

Testing the Binary

After building, run the binary harness. It checks version, help, a JSON-config site build, that TypeScript configs are rejected, download variables, and init:

pnpm test:binary

Or point it at a specific binary:

pnpm test:binary -- ./dist/docula
DOCULA_BINARY=./dist/docula.exe pnpm test:binary

You can also exercise the binary directly:

# Show help
./dist/docula help

# Show version
./dist/docula version

# Initialize a new project
./dist/docula init -s ./my-site

# Build a site
./dist/docula build -s ./my-site -o ./my-site/dist

Cross-Platform Binaries

The CI workflow (.github/workflows/build-binaries.yaml) builds each platform natively on its own runner. Native builds avoid the cross-compile signing pitfall on Apple Silicon, where unsigned Mach-O binaries are killed on launch.

| Platform | Runner | Artifact | |---|---|---| | Linux x64 | ubuntu-latest | docula-linux-x64 | | macOS ARM64 | macos-latest | docula-macos-arm64 | | Windows x64 | windows-latest | docula-windows-x64.exe |

Binaries are uploaded as build artifacts on every run. Published GitHub Releases are immutable (assets cannot be added after publishing), so the workflow attaches the binaries while the release is still a draft:

1. Merge the version bump to main. The workflow builds the binaries, creates a draft release v<version> for that commit if none exists (with auto-generated notes to replace), and attaches all three binaries to it.
2. Once the run is green, edit the draft's notes and publish it from the Releases page. Publishing creates the tag and triggers the release (npm) and deploy-site workflows.

Run the workflow by hand (Actions → build-binaries → Run workflow on main) to rebuild and re-attach the binaries for the current version; a run on any other branch only produces artifacts. Pushing a version tag re-checks that its release carries every binary. A release published without them cannot be fixed in place — delete the release and its tag, then run the workflow again.

Open Source Examples

See Docula in action with these open source projects that use it for their documentation:

• Cacheable.org - High-performance caching library for Node.js with layered caching support (Source)
• Keyv.org - Simple key-value storage with support for multiple backends (Source)
• Docula.org - Docula's own documentation site, built with Docula (Source)

Code of Conduct and Contributing

Code of Conduct and Contributing guidelines.

Security

We take the security of Docula seriously and have multiple layers of protection in place:

• Aikido Security: Continuous scanning of our codebase, dependencies, and infrastructure for vulnerabilities. Review our public audit report by clicking the badge above.
• Pull Request Scans: Every pull request against main is automatically scanned for security issues before merging.
• CodeQL Analysis: GitHub CodeQL static analysis runs on every push and pull request targeting main.
• npm Package Provenance: Releases are published with npm provenance for cryptographically verifiable links to source and build.

For full details, see SECURITY.md or our Security Guidelines.

License

MIT © Jared Wray