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.

Table of Contents

• Initializing with TypeScript
• Using Lifecycle Hooks with TypeScript
• Manipulating Release Changelog Entries
• Cleaning Up the Auto README
• DoculaConsole Logger
• Config File Priority
• Available Options

Initializing with TypeScript

When you run npx docula init, docula automatically detects TypeScript projects by checking for a tsconfig.json in the current directory. If found, it generates a docula.config.ts file. Otherwise, it generates docula.config.mjs.

You can also explicitly choose:

npx docula init --typescript   # Force TypeScript config
npx docula init --javascript   # Force JavaScript config

The TypeScript config provides full type support:

import type { DoculaOptions } from 'docula';

export const options: Partial<DoculaOptions> = {
  templatePath: './template',
  output: './site/dist',
  sitePath: './site',
  githubPath: 'your-username/your-repo',
  siteTitle: 'My Project',
  siteDescription: 'Project description',
  siteUrl: 'https://your-site.com',
  themeMode: 'light', // or 'dark' — defaults to system preference if omitted
  googleTagManager: 'GTM-XXXXXX', // or 'G-XXXXXXXXXX' for GA4
  homeUrl: '/', // logo links to this URL instead of baseUrl
  baseUrl: '/docs', // host under a subpath
  autoReadme: true, // use project root README.md as the home page
  docsPath: '', // place docs at the output root
  apiPath: 'api',
  changelogPath: 'changelog',
};

Using Lifecycle Hooks with TypeScript

You can add typed lifecycle hooks to your config:

import type { DoculaConsole, DoculaOptions } from 'docula';

export const options: Partial<DoculaOptions> = {
  siteTitle: 'My Project',
  // ... other options
};

export const onPrepare = async (config: DoculaOptions, console: DoculaConsole): Promise<void> => {
  // Runs before the build process
  console.info(`Building ${config.siteTitle}...`);
};

Manipulating Release Changelog Entries

The onReleaseChangelog hook lets you modify, filter, or transform GitHub release entries before they are merged with file-based changelog entries and rendered. This is useful for cleaning up release notes, filtering out unwanted releases, or customizing tags.

import type { DoculaChangelogEntry, DoculaConsole, DoculaOptions } from 'docula';

export const options: Partial<DoculaOptions> = {
  githubPath: 'your-username/your-repo',
  enableReleaseChangelog: true,
};

export const onReleaseChangelog = (entries: DoculaChangelogEntry[], console: DoculaConsole): DoculaChangelogEntry[] => {
  console.info(`Processing ${entries.length} release entries...`);
  return entries
    // Filter out pre-releases
    .filter(entry => entry.tag !== 'Pre-release')
    // Customize titles
    .map(entry => ({
      ...entry,
      title: entry.title.replace(/^v/, 'Version '),
    }));
};

Each DoculaChangelogEntry has these fields you can read or modify:

The hook can be synchronous or async. If the hook throws an error, it is logged and the unmodified entries are used.

Cleaning Up the Auto README

When autoReadme is enabled and docula falls back to your project root README.md for the home page, the onAutoReadme hook lets you transform that markdown before it is rendered. This is useful for stripping a shields/badges banner, removing an "Install" section that doesn't belong on the home page, or rewriting relative links.

import type { DoculaConsole, DoculaOptions } from 'docula';

export const options: Partial<DoculaOptions> = {
  autoReadme: true,
};

export const onAutoReadme = (content: string, sourcePath: string, console: DoculaConsole): string => {
  console.info(`Cleaning up README at ${sourcePath}`);
  return content
    // Drop everything from "## Install" up to the next H2
    .replace(/^##\s+Install[\s\S]*?(?=^##\s)/m, '')
    // Rewrite relative links to absolute
    .replace(/\]\(\.\//g, '](https://github.com/your-username/your-repo/blob/main/');
};

The hook receives:

The hook can be synchronous or async and must return the new markdown. If the hook throws, the error is logged and the original content is used. The hook only runs when autoReadme is enabled and there is no README.md in the site directory.

DoculaConsole Logger

The onPrepare, onReleaseChangelog, and onAutoReadme hooks all receive a DoculaConsole instance as their last argument. This provides styled, consistent logging output:

Config File Priority

When both config files exist, Docula loads them in this order (first found wins):

1. docula.config.ts (TypeScript - takes priority)
2. docula.config.mjs (JavaScript)

Available Options