docula 0.31.2 → 0.41.0

package/README.md

@@ -12,8 +12,13 @@
 - [Features](#features)
 - [Open Source Examples](#open-source-examples)
 - [Getting Started](#getting-started)
+- [TypeScript Configuration](#typescript-configuration)
 - [Using Your own Template](#using-your-own-template)
 - [Building Multiple Pages](#building-multiple-pages)
+- [Public Folder](#public-folder)
+- [Announcements](#announcements)
+- [Changelog](#changelog)
+- [Alert, Info, Warn Styling](#alert-info-warn-styling)
 - [Using a Github Token](#using-a-github-token)
 - [Helpers](#helpers)
 - [Working with Markdown using Writr](#working-with-markdown-using-writr)
@@ -21,9 +26,10 @@
 - [License - MIT](#license)
 
 # Features
-* No configuration requrired. Just setup the folder structure with a logo, favicon, and css file.
+* 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.mjs` file to customize the build process. With PRE and POST methods.
+* 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.
@@ -67,6 +73,73 @@ Simply replace the logo, favicon, and css file with your own. The readme is your
 
 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:
+
+```bash
+npx docula init --typescript
+```
+
+This creates a `docula.config.ts` file with full type support:
+
+```typescript
+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:
+
+```typescript
+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.
@@ -99,6 +172,234 @@ 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:
+
+```md
+**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`:
+
+```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.
+
+# Changelog
+
+Docula can generate a changelog section for your site from markdown files. This is useful for documenting release notes, updates, and changes to your project in a structured, browsable format.
+
+## Setup
+
+Create a `changelog` folder inside your site directory and add markdown (`.md` or `.mdx`) files for each entry:
+
+```
+site
+├───changelog
+│   ├───2025-01-15-initial-release.md
+│   ├───2025-02-01-new-features.md
+│   └───2025-03-10-bug-fixes.md
+├───logo.svg
+├───favicon.ico
+└───docula.config.mjs
+```
+
+## Entry Format
+
+Each changelog entry is a markdown file with front matter:
+
+```md
+---
+title: "Initial Release"
+date: 2025-01-15
+tag: "Release"
+---
+
+We're excited to announce the initial release! Here's what's included:
+
+- Feature A
+- Feature B
+- Bug fix C
+```
+
+### Front Matter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | No | Display title for the entry. Defaults to the filename if not provided. |
+| `date` | Yes | Date of the entry (`YYYY-MM-DD`). Used for sorting (newest first). |
+| `tag` | No | A label displayed as a badge (e.g., `Release`, `Bug Fix`, `Feature`). Gets a CSS class based on its value for styling. |
+
+## File Naming
+
+Files can optionally be prefixed with a date in `YYYY-MM-DD-` format. The date prefix is stripped to create the URL slug:
+
+- `2025-01-15-initial-release.md` → `/changelog/initial-release/`
+- `new-features.md` → `/changelog/new-features/`
+
+## Generated Pages
+
+When changelog entries are found, Docula generates:
+
+- **Changelog listing page** at `/changelog/` — shows all entries sorted by date (newest first) with titles, dates, tags, and content
+- **Individual entry pages** at `/changelog/{slug}/` — a dedicated page for each entry with a back link to the listing
+
+Changelog URLs are also automatically added to the generated `sitemap.xml`.
+
+## Styling
+
+Tags receive a CSS class based on their value (e.g., a tag of `"Bug Fix"` gets the class `changelog-tag-bug-fix`). You can style tags and other changelog elements by overriding these classes in your `variables.css`:
+
+```css
+.changelog-entry {
+  border-bottom: 1px solid var(--border);
+  padding: 1.5rem 0;
+}
+
+.changelog-tag {
+  font-size: 0.75rem;
+  padding: 0.2rem 0.5rem;
+  border-radius: 4px;
+}
+
+.changelog-tag-release {
+  background-color: #d4edda;
+  color: #155724;
+}
+
+.changelog-tag-bug-fix {
+  background-color: #f8d7da;
+  color: #721c24;
+}
+```
+
+# Alert, Info, Warn Styling
+
+Docula uses Writr's GitHub-flavored Markdown plugins, including GitHub-style blockquote alerts. Use the alert syntax directly in Markdown:
+
+```md
+> [!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:
+
+```css
+.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "0.31.2",
+  "version": "0.41.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -29,6 +29,8 @@
     "website:serve": "rimraf ./site/README.md && node bin/docula.mjs serve -s ./site -o ./site/dist",
     "website:build:mega": "rimraf ./test/fixtures/mega-page-site/dist && node bin/docula.mjs build -s ./test/fixtures/mega-page-site",
     "website:serve:mega": "rimraf ./test/fixtures/mega-page-site/dist && node bin/docula.mjs serve -s ./test/fixtures/mega-page-site",
+    "website:build:changelog": "rimraf ./test/fixtures/changelog-site/dist && node bin/docula.mjs build -s ./test/fixtures/changelog-site",
+    "website:serve:changelog": "rimraf ./test/fixtures/changelog-site/dist && node bin/docula.mjs serve -s ./test/fixtures/changelog-site",
     "prepare": "pnpm build"
   },
   "keywords": [
@@ -51,30 +53,30 @@
     "docula": "./bin/docula.mjs"
   },
   "dependencies": {
-    "@cacheable/net": "^2.0.4",
-    "cheerio": "^1.1.2",
-    "ecto": "^4.7.1",
-    "feed": "^5.1.0",
+    "@cacheable/net": "^2.0.5",
+    "ecto": "^4.8.2",
+    "feed": "^5.2.0",
     "he": "^1.2.0",
+    "jiti": "^2.6.1",
     "serve-handler": "^6.1.6",
     "update-notifier": "^7.3.1",
-    "writr": "^5.0.1"
+    "writr": "^5.0.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.9",
+    "@biomejs/biome": "^2.4.2",
     "@types/express": "^5.0.6",
     "@types/he": "^1.2.3",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.2.3",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.0.16",
-    "dotenv": "^17.2.3",
-    "rimraf": "^6.1.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "dotenv": "^17.3.1",
+    "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "files": [
     "dist",

package/template/api.hbs

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  {{> header }}
+  <title>API Documentation - {{ siteTitle }}</title>
+  <meta name="description" content="API Documentation for {{ siteTitle }}" />
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docutopia/react/dist/browser/docutopia.css" />
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+
+<body>
+  <div id="docs" style="height: 100vh;"></div>
+
+  <script src="https://cdn.jsdelivr.net/npm/@docutopia/react/dist/browser/docutopia.js"></script>
+  <script>
+    Docutopia.render('docs', {
+      specUrl: '{{ specUrl }}',
+    });
+  </script>
+</body>
+
+</html>

package/template/changelog-entry.hbs

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  {{> header }}
+  <title>{{siteTitle}} - {{title}}</title>
+</head>
+
+<body>
+  {{> singlepage/hero }}
+  <a href="https://github.com/{{ githubPath }}" class="github-corner" aria-label="View source on GitHub"><svg width="80"
+      height="80" viewBox="0 0 250 250" style="color:#fff; position: absolute; top: 0; border: 0; right: 0;"
+      aria-hidden="true">
+      <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
+      <path
+        d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2"
+        fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path>
+      <path
+        d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z"
+        fill="currentColor" class="octo-body"></path>
+    </svg></a>
+  <style>
+    .github-corner:hover .octo-arm {
+      animation: octocat-wave 560ms ease-in-out
+    }
+
+    @keyframes octocat-wave {
+
+      0%,
+      100% {
+        transform: rotate(0)
+      }
+
+      20%,
+      60% {
+        transform: rotate(-25deg)
+      }
+
+      40%,
+      80% {
+        transform: rotate(10deg)
+      }
+    }
+
+    @media (max-width:500px) {
+      .github-corner:hover .octo-arm {
+        animation: none
+      }
+
+      .github-corner .octo-arm {
+        animation: octocat-wave 560ms ease-in-out
+      }
+    }
+  </style>
+  <main class="versions-container">
+    <div class="versions-content">
+      <div class="changelog-entry-nav">
+        <a href="/changelog/">&larr; Back to Changelog</a>
+      </div>
+      <div class="changelog-entry changelog-entry-single">
+        <div class="changelog-entry-header">
+          <h1 class="changelog-entry-title">{{title}}</h1>
+          {{#if tag}}
+          <span class="changelog-tag changelog-tag-{{tagClass}}">{{tag}}</span>
+          {{/if}}
+        </div>
+        <span class="changelog-entry-date">{{formattedDate}}</span>
+        <div class="changelog-entry-body">
+          {{{generatedHtml}}}
+        </div>
+      </div>
+    </div>
+  </main>
+  {{> footer}}
+
+  {{> scripts }}
+</body>
+
+</html>

package/template/changelog.hbs

@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  {{> header }}
+  <title>{{siteTitle}} Changelog</title>
+</head>
+
+<body>
+  {{> singlepage/hero }}
+  <a href="https://github.com/{{ githubPath }}" class="github-corner" aria-label="View source on GitHub"><svg width="80"
+      height="80" viewBox="0 0 250 250" style="color:#fff; position: absolute; top: 0; border: 0; right: 0;"
+      aria-hidden="true">
+      <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
+      <path
+        d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2"
+        fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path>
+      <path
+        d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z"
+        fill="currentColor" class="octo-body"></path>
+    </svg></a>
+  <style>
+    .github-corner:hover .octo-arm {
+      animation: octocat-wave 560ms ease-in-out
+    }
+
+    @keyframes octocat-wave {
+
+      0%,
+      100% {
+        transform: rotate(0)
+      }
+
+      20%,
+      60% {
+        transform: rotate(-25deg)
+      }
+
+      40%,
+      80% {
+        transform: rotate(10deg)
+      }
+    }
+
+    @media (max-width:500px) {
+      .github-corner:hover .octo-arm {
+        animation: none
+      }
+
+      .github-corner .octo-arm {
+        animation: octocat-wave 560ms ease-in-out
+      }
+    }
+  </style>
+  <main class="versions-container">
+    <div class="versions-content">
+      <h2 class="home-title">Changelog</h2>
+      {{#if entries}}
+      {{#each entries as |entry|}}
+      <div class="changelog-entry">
+        <div class="changelog-entry-header">
+          <a class="changelog-entry-title" href="/changelog/{{entry.slug}}/">{{entry.title}}</a>
+          {{#if entry.tag}}
+          <span class="changelog-tag changelog-tag-{{entry.tagClass}}">{{entry.tag}}</span>
+          {{/if}}
+        </div>
+        <span class="changelog-entry-date">{{entry.formattedDate}}</span>
+        <div class="changelog-entry-body">
+          {{{entry.generatedHtml}}}
+        </div>
+      </div>
+      {{/each}}
+      {{/if}}
+    </div>
+  </main>
+  {{> footer}}
+
+  {{> scripts }}
+</body>
+
+</html>