docula 0.40.0 → 0.41.0

package/README.md

@@ -17,6 +17,7 @@
 - [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)
@@ -272,6 +273,94 @@ You can customize the appearance by overriding the `.announcement` class in your
 
 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "0.40.0",
+  "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,31 +53,30 @@
     "docula": "./bin/docula.mjs"
   },
   "dependencies": {
-    "@cacheable/net": "^2.0.4",
-    "cheerio": "^1.1.2",
-    "ecto": "^4.7.1",
+    "@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>

package/template/css/base.css

@@ -193,6 +193,140 @@ hr {
   text-decoration: underline;
 }
 
+/* Changelog */
+.changelog-entry {
+  overflow: hidden;
+  width: 100%;
+  line-break: anywhere;
+  margin-top: 2rem;
+  padding-bottom: 2rem;
+  border-bottom: 1px solid var(--border);
+  color: var(--color-text);
+}
+
+.changelog-entry:last-child {
+  border-bottom: none;
+}
+
+.changelog-entry-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.changelog-entry-title {
+  font-size: 1.375rem;
+  color: var(--color-primary);
+  font-weight: 700;
+  transition: color .3s;
+}
+
+a.changelog-entry-title:hover {
+  color: var(--color-secondary-dark);
+}
+
+h1.changelog-entry-title {
+  font-size: 1.875rem;
+  margin: 0;
+}
+
+.changelog-entry-date {
+  font-size: 0.75rem;
+  display: block;
+  margin-bottom: 1rem;
+}
+
+.changelog-tag {
+  display: inline-block;
+  padding: 0.2rem 0.6rem;
+  border-radius: 1rem;
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
+.changelog-tag-added {
+  background-color: rgba(140, 220, 0, 0.15);
+  color: #4a7a00;
+}
+
+.changelog-tag-improved {
+  background-color: rgba(59, 130, 246, 0.15);
+  color: #1d4ed8;
+}
+
+.changelog-tag-fixed {
+  background-color: rgba(245, 158, 11, 0.15);
+  color: #b45309;
+}
+
+.changelog-tag-removed {
+  background-color: rgba(239, 68, 68, 0.15);
+  color: #b91c1c;
+}
+
+.changelog-tag-deprecated {
+  background-color: rgba(156, 163, 175, 0.15);
+  color: #4b5563;
+}
+
+.changelog-tag-security {
+  background-color: rgba(168, 85, 247, 0.15);
+  color: #6d28d9;
+}
+
+.changelog-entry-body p {
+  margin: 0.5rem 0;
+}
+
+.changelog-entry-body pre {
+  margin-bottom: 2rem;
+}
+
+.changelog-entry-body h1 {
+  font-size: 1.375rem;
+  margin-bottom: 1rem;
+}
+
+.changelog-entry-body h2 {
+  font-size: 1.125rem;
+  margin-top: 1.75rem;
+  margin-bottom: 1rem;
+}
+
+.changelog-entry-body ul {
+  padding-left: 1rem;
+}
+
+.changelog-entry-body ul > li {
+  margin-bottom: 0.75rem;
+}
+
+.changelog-entry-body ul > li a {
+  text-decoration: underline;
+}
+
+.changelog-entry-nav {
+  margin-bottom: 1.5rem;
+}
+
+.changelog-entry-nav a {
+  color: var(--color-primary);
+  font-size: 0.875rem;
+  transition: color .3s;
+}
+
+.changelog-entry-nav a:hover {
+  color: var(--color-secondary-dark);
+}
+
+.changelog-entry-single {
+  border-bottom: none;
+}
+
 .github-corner {
   fill: var(--color-primary) !important;
 }
@@ -378,6 +512,9 @@ footer img {
   .release {
     margin-bottom: 4rem;
   }
+  .changelog-entry {
+    margin-bottom: 2rem;
+  }
   .versions-container {
     margin-bottom: 4.5rem;
   }
@@ -417,6 +554,9 @@ footer img {
   .content h1 {
     font-size: 1.9rem;
   }
+  h1.changelog-entry-title {
+    font-size: 2.25rem;
+  }
   .content > ul, .content > ol {
     padding-left: 2rem;
   }

package/template/css/multipage.css

@@ -241,10 +241,6 @@ details > summary {
   margin-right: 2rem
 }
 
-.main-toc {
-  padding-bottom: 1.5rem;
-}
-
 .toc {
   font-size: 0.875rem;
 }
@@ -287,18 +283,6 @@ details > summary {
   text-decoration: none;
 }
 
-.main-toc ul > li > a::after {
-  position: absolute;
-  right: 0;
-  content: '';
-  display: inline-block;
-  width: 0.25rem;
-  height: 0.25rem;
-  border-right: 1px solid var(--color-primary);
-  border-bottom: 1px solid var(--color-primary);
-  transform: rotate(-45deg);
-}
-
 .fixed-toc {
   display: none;
   position: fixed;

package/template/includes/multipage/doc.hbs

@@ -2,16 +2,22 @@
   <div class="main-content">
     <article class="content">
       <h1>{{title}}</h1>
-      <div class="toc main-toc">
-{{tableOfContents}}
-      </div>
 {{generatedHtml}}
     </article>
     <div class="fixed-toc-container">
       <div class="toc fixed-toc" id="fixed-toc">
-        {{tableOfContents}}
       </div>
     </div>
     </div>
 
-</div>
+</div>
+<script>
+  const tocHeading = document.getElementById('table-of-contents');
+  if (tocHeading) {
+    const tocList = tocHeading.nextElementSibling;
+    const fixedToc = document.getElementById('fixed-toc');
+    if (tocList && tocList.tagName === 'UL' && fixedToc) {
+      fixedToc.innerHTML = tocList.outerHTML;
+    }
+  }
+</script>

package/dist/docula.d.ts

@@ -1,132 +0,0 @@
-import http from 'node:http';
-export { Writr } from 'writr';
-
-type DoculaSection = {
-    name: string;
-    order?: number;
-    path: string;
-    children?: DoculaSection[];
-};
-
-declare class DoculaOptions {
-    /**
-     * Path to the template directory
-     */
-    templatePath: string;
-    /**
-     * Path to the output directory
-     */
-    outputPath: string;
-    /**
-     * Path to the site directory
-     */
-    sitePath: string;
-    /**
-     * Path to the github repository
-     */
-    githubPath: string;
-    /**
-     * Site title
-     */
-    siteTitle: string;
-    /**
-     * Site description
-     */
-    siteDescription: string;
-    /**
-     * Site URL
-     */
-    siteUrl: string;
-    /**
-     * Port to run the server
-     */
-    port: number;
-    /**
-     * Single page website
-     */
-    singlePage: boolean;
-    /**
-     * Sections
-     */
-    sections?: DoculaSection[];
-    constructor(options?: Record<string, unknown>);
-    parseOptions(options: Record<string, any>): void;
-}
-
-declare class Docula {
-    private _options;
-    private readonly _console;
-    private _configFileModule;
-    private _server;
-    /**
-     * Initialize the Docula class
-     * @param {DoculaOptions} options
-     * @returns {void}
-     * @constructor
-     */
-    constructor(options?: DoculaOptions);
-    /**
-     * Get the options
-     * @returns {DoculaOptions}
-     */
-    get options(): DoculaOptions;
-    /**
-     * Set the options
-     * @param {DoculaOptions} value
-     */
-    set options(value: DoculaOptions);
-    /**
-     * The http server used to serve the site
-     * @returns {http.Server | undefined}
-     */
-    get server(): http.Server | undefined;
-    /**
-     * The config file module. This is the module that is loaded from the docula.config.ts or docula.config.mjs file
-     * @returns {any}
-     */
-    get configFileModule(): any;
-    /**
-     * Check for updates
-     * @returns {void}
-     */
-    checkForUpdates(): void;
-    /**
-     * Is the execution process that runs the docula command
-     * @param {NodeJS.Process} process
-     * @returns {Promise<void>}
-     */
-    execute(process: NodeJS.Process): Promise<void>;
-    /**
-     * Checks if the site is a single page website
-     * @param {string} sitePath
-     * @returns {boolean}
-     */
-    isSinglePageWebsite(sitePath: string): boolean;
-    /**
-     * Generate the init files
-     * @param {string} sitePath
-     * @param {boolean} typescript - If true, generates docula.config.ts instead of docula.config.mjs
-     * @returns {void}
-     */
-    generateInit(sitePath: string, typescript?: boolean): void;
-    /**
-     * Get the version of the package
-     * @returns {string}
-     */
-    getVersion(): string;
-    /**
-     * Load the config file. Supports both .mjs and .ts config files.
-     * Priority: docula.config.ts > docula.config.mjs
-     * @param {string} sitePath
-     * @returns {Promise<void>}
-     */
-    loadConfigFile(sitePath: string): Promise<void>;
-    /**
-     * Serve the site based on the options (port and output path)
-     * @param {DoculaOptions} options
-     * @returns {Promise<void>}
-     */
-    serve(options: DoculaOptions): Promise<http.Server>;
-}
-
-export { Docula as default };