Docula

Partial Templates

Learn how to override individual template files in Docula without replacing the entire template, allowing selective customization of components like footers, headers, and sidebars.

Docula lets you override individual template files from a built-in template without replacing the entire template. This is useful when you want to customize specific parts of a template (such as the footer, sidebar, or header) while keeping the rest of the default template intact.

Table of Contents

How It Works

Place your override files in a templates/{templateName}/ directory inside your site folder. The directory structure mirrors the built-in template. Any file you include will replace its corresponding file in the built-in template during the build.

For example, if you are using the modern template and want to customize the footer:

site/
  templates/
    modern/
      includes/
        footer.hbs    # overrides the built-in modern/includes/footer.hbs
  docs/
    index.md
  docula.config.ts

Overridable Files

You can override any file in the built-in template, including:

Top-level templates:

  • home.hbs — Landing page
  • docs.hbs — Documentation page
  • api.hbs — API reference page
  • changelog.hbs — Changelog listing page
  • changelog-entry.hbs — Individual changelog entry page

Includes (partials):

  • includes/header.hbs — Page header/meta tags
  • includes/header-bar.hbs — Sticky header navigation bar
  • includes/footer.hbs — Page footer
  • includes/sidebar.hbs — Navigation sidebar
  • includes/doc.hbs — Document content wrapper
  • includes/hero.hbs — Hero section
  • includes/home.hbs — Home page content
  • includes/scripts.hbs — Page scripts
  • includes/theme-toggle.hbs — Light/dark theme toggle

Assets:

  • css/ — Stylesheet files
  • js/ — JavaScript files

The available includes vary by template. Check the templates/ directory in the Docula repository for the complete list of files in each template.

  1. Create the override directory structure:
mkdir -p site/templates/modern/includes
  1. Create your custom footer at site/templates/modern/includes/footer.hbs:
  1. Build your site as usual:
npx docula build

During the build, Docula will log which files are being overridden:

▶ Applying template overrides...
ℹ Template override: includes/footer.hbs

Notes

  • Built-in templates only — Partial overrides work with the template option (e.g., modern, classic). If you use templatePath to provide a fully custom template, overrides are not applied since you already control the entire template.
  • Cache directory — Docula merges overrides into a .cache/templates/{templateName}/ directory inside your site folder. This directory is automatically managed and only rebuilt when override files change. Use --clean to remove it along with the output directory.
  • Automatic .gitignore — When the .cache directory is first created, Docula automatically adds .cache to your site folder's .gitignore (creating the file if needed). Set autoUpdateIgnores: false in your config to disable this behavior.
  • Any file can be overridden — The override directory structure mirrors the built-in template exactly. Any file you place in the override directory replaces the corresponding file from the built-in template.
Edit this page