Beautiful Website for Your Projects

Table of Contents

• Features
• Open Source Examples
• Getting Started
  • Install docula via init
  • Add your content
  • Build your site
• TypeScript Configuration
  • Initializing with TypeScript
  • Using Lifecycle Hooks with TypeScript
  • Config File Priority
  • Available Options
• Using Your own Template
• Building Multiple Pages
• Public Folder
  • Usage
• Announcements
  • Usage
  • Styling
  • Removing the Announcement
• Alert, Info, Warn Styling
• Using a Github Token
• Helpers
• Working with Markdown using Writr
  • Creating and Loading Markdown
  • Getting and Setting Front Matter
  • Accessing Markdown Content
  • Rendering Markdown to HTML
• Code of Conduct and Contributing
• License

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.
• 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.
• 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.
• 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.

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)

These examples showcase different approaches to using Docula, from simple single-page sites to more complex documentation with multiple pages and custom configurations.

Getting Started

Install docula via init

npx docula init

This will create a folder called site with the following structure:

site
  ├───site.css
  ├───logo.png
  ├───favicon.ico
  ├───README.md
  ├───docula.config.mjs
  

Note: for typescript do 'docula init --typescript'

Add your content

Simply replace the logo, favicon, and css file with your own. The readme is your root project readme and you just need to at build time move it over to the site folder. If you have it at the root of the project and this is a folder inside just delete the README.md file in the site folder and docula will copy it over for you automatically.

Build your site

npx docula

This will build your site and place it in the dist folder. You can then host it anywhere you like.

TypeScript 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.

Initializing with TypeScript

To create a new project with a TypeScript config file:

npx docula init --typescript
  

This creates a docula.config.ts file with full type support:

import type { DoculaOptions } from 'docula';
  
  export const options: Partial<DoculaOptions> = {
    templatePath: './template',
    outputPath: './dist',
    sitePath: './site',
    githubPath: 'your-username/your-repo',
    siteTitle: 'My Project',
    siteDescription: 'Project description',
    siteUrl: 'https://your-site.com',
  };
  

Using Lifecycle Hooks with TypeScript

You can add typed lifecycle hooks to your config:

import type { DoculaOptions } from 'docula';
  
  export const options: Partial<DoculaOptions> = {
    siteTitle: 'My Project',
    // ... other options
  };
  
  export const onPrepare = async (config: DoculaOptions): Promise<void> => {
    // Runs before the build process
    console.log(`Building ${config.siteTitle}...`);
  };
  

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

Option	Type	Default	Description
templatePath	string	'./template'	Path to custom template directory
outputPath	string	'./dist'	Output directory for built site
sitePath	string	'./site'	Directory containing site content
githubPath	string	-	GitHub repository path (e.g., 'user/repo')
siteTitle	string	'docula'	Website title
siteDescription	string	-	Website description
siteUrl	string	-	Website URL
port	number	3000	Port for local development server
singlePage	boolean	true	Single page or multi-page site
sections	DoculaSection[]	-	Documentation sections

Using Your own Template

If you want to use your own template you can do so by adding a docula.config.ts file to the root of your project. This file will be used to configure the build process.

or at the command line:

npx docula --template path/to/template

Building Multiple Pages

If you want to build multiple pages you can easily do that by adding in a docs folder to the root of the site folder. Inside of that folder you can add as many pages as you like. Each page will be a markdown file and it will generate a table of contents for you. Here is an example of what it looks like:

site
  ├───site.css
  ├───logo.png
  ├───favicon.ico
  ├───docula.config.mjs
  ├───docs
  │   ├───getting-started.md
  │   ├───contributing.md
  │   ├───license.md
  │   ├───code-of-conduct.md
  

The readme.md file will be the root page and the rest will be added to the table of contents. If you want to control the title or order of the pages you can do so by setting the title and order properties in the front matter of the markdown file. Here is an example:

title: Getting Started
  order: 2
  

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.

Usage

Create a public folder inside your site directory:

site
  ├───public
  │   ├───images
  │   │   ├───screenshot.png
  │   │   └───banner.jpg
  │   ├───fonts
  │   │   └───custom-font.woff2
  │   └───downloads
  │       └───example.pdf
  ├───docs
  ├───logo.svg
  ├───favicon.ico
  └───docula.config.mjs
  

When you run the build command, all contents of the public folder will be copied to the dist folder:

dist
  ├───images
  │   ├───screenshot.png
  │   └───banner.jpg
  ├───fonts
  │   └───custom-font.woff2
  ├───downloads
  │   └───example.pdf
  ├───index.html
  └───...
  

The build output will show each file being copied:

Public folder found, copying contents to dist...
    Copied: images/screenshot.png
    Copied: images/banner.jpg
    Copied: fonts/custom-font.woff2
    Copied: downloads/example.pdf
  Build completed in 1234ms
  

This is useful for:

• Images referenced in your documentation
• Downloadable files (PDFs, zip archives, etc.)
• Custom fonts
• Any other static assets that need to be served from your site

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.

Usage

Create an announcement.md file in your site folder:

site
  ├───announcement.md
  ├───docs
  ├───logo.svg
  ├───favicon.ico
  └───docula.config.mjs
  

Add your announcement content using markdown:

**New Release:** Version 2.0 is now available! Check out the [release notes](/releases) for details.
  

The announcement will automatically appear on the home page above the "Documentation" button, styled as an alert box with a colored left border.

Styling

The announcement uses your theme's CSS variables and displays with:

• A subtle background using --sidebar-background
• A prominent left border using --color-secondary
• Links styled with --color-primary

You can customize the appearance by overriding the .announcement class in your variables.css:

.announcement {
    background-color: #fff3cd;
    border-left-color: #ffc107;
  }
  

Removing the Announcement

Simply delete the announcement.md file when you no longer need the announcement. The home page will automatically return to its normal layout.

Alert, Info, Warn Styling

Docula uses Writr's GitHub-flavored Markdown plugins, including GitHub-style blockquote alerts. Use the alert syntax directly in Markdown:

> [!NOTE]
  > Info: Remember to configure your GitHub token for private repos.
  
  > [!WARNING]
  > Warn: This action cannot be undone.
  
  > [!CAUTION]
  > Alert: Rotate your secrets immediately.
  

These render with the remark-github-blockquote-alert classes (like .markdown-alert and .markdown-alert-note). If you want GitHub-like styling, copy the plugin's CSS into your site/variables.css or template stylesheet (for example, from remark-github-blockquote-alert/alert.css), or add your own overrides:

.markdown-alert {
    border-left: 4px solid var(--border);
    border-radius: 8px;
    margin: 1rem 0;
    padding: 0.75rem 1rem;
    background: var(--background);
  }
  
  .markdown-alert-note {
    border-left-color: #4c8ef7;
  }
  
  .markdown-alert-warning {
    border-left-color: #f2b90c;
  }
  
  .markdown-alert-caution {
    border-left-color: #e5534b;
  }
  

Using a Github Token

If you want to use the Github token to access the Github API you can do so by setting the GITHUB_TOKEN environment variable. This is useful if you want to access private repositories or if you want to access the Github API without hitting the rate limit. This is optional and you can still use docula without it but could hit rate limits and will not be able to access private repositories.

Helpers

Docula provides powerful helper utilities through its integration with Writr. For all markdown operations including reading files, manipulating content, managing frontmatter, and rendering, you should use the Writr class that's exported from Docula.

Instead of custom helper functions, use Writr for:

• Loading and saving markdown files
• Getting and setting frontmatter (metadata)
• Rendering markdown to HTML
• Working with markdown content programmatically

See the Working with Markdown using Writr section below for comprehensive examples and usage patterns.

Working with Markdown using Writr

Docula exports Writr for powerful markdown operations including loading files, rendering, and managing frontmatter. Writr provides a simple API for working with markdown content.

Creating and Loading Markdown

import { Writr } from 'docula';
  
  // Create a new instance with markdown content
  const writr = new Writr('# Hello World\n\nThis is my content');
  
  // Or load from a file
  const writr = new Writr();
  await writr.loadFromFile('./README.md');
  
  // Synchronous version
  writr.loadFromFileSync('./README.md');
  

Getting and Setting Front Matter

Front matter is metadata at the top of markdown files in YAML format. Writr makes it easy to read and modify:

import { Writr } from 'docula';
  
  const writr = new Writr();
  await writr.loadFromFile('./docs/guide.md');
  
  // Get the entire front matter object
  const frontMatter = writr.frontMatter;
  console.log(frontMatter.title); // 'My Guide'
  
  // Get a specific front matter value
  const title = writr.getFrontMatterValue('title');
  const order = writr.getFrontMatterValue('order');
  
  // Set front matter
  writr.frontMatter = {
    title: 'Updated Guide',
    order: 1,
    author: 'John Doe'
  };
  
  // Save the changes back to the file
  await writr.saveToFile('./docs/guide.md');
  

Accessing Markdown Content

// Get the full content (front matter + markdown)
  const fullContent = writr.content;
  
  // Get just the markdown body (without front matter)
  const markdown = writr.body;
  // or use the alias
  const markdown = writr.markdown;
  
  // Get the raw front matter string (including delimiters)
  const rawFrontMatter = writr.frontMatterRaw;
  
  // Set new content
  writr.content = '---\ntitle: New Title\n---\n# New Content';
  

Rendering Markdown to HTML

// Render to HTML
  const html = await writr.render();
  
  // Synchronous rendering
  const html = writr.renderSync();
  
  // Render with options
  const html = await writr.render({
    emoji: true,        // Enable emoji support (default: true)
    toc: true,          // Generate table of contents (default: true)
    highlight: true,    // Code syntax highlighting (default: true)
    gfm: true,          // GitHub Flavored Markdown (default: true)
    math: true,         // Math support (default: true)
    mdx: true           // MDX support (default: true)
  });
  
  // Render directly to a file
  await writr.renderToFile('./output.html');
  

Code of Conduct and Contributing

Code of Conduct and Contributing guidelines.

License

MIT © Jared Wray