docula 1.6.0 → 1.8.0

package/dist/docula.d.ts

@@ -119,6 +119,8 @@ type DoculaConsoleArguments = {
     port: number | undefined;
     typescript: boolean;
     javascript: boolean;
+    overwrite: boolean;
+    downloadTarget: string;
 };
 
 type GithubData = {
@@ -363,6 +365,9 @@ declare class DoculaBuilder {
     buildRobotsPage(options: DoculaOptions): Promise<void>;
     buildSiteMapPage(data: DoculaData): Promise<void>;
     buildFeedPage(data: DoculaData): Promise<void>;
+    buildChangelogFeedJson(data: DoculaData): Promise<void>;
+    buildChangelogLatestFeedJson(data: DoculaData): Promise<void>;
+    private writeChangelogFeedJson;
     buildLlmsFiles(data: DoculaData): Promise<void>;
     private generateLlmsIndexContent;
     private generateLlmsFullContent;
@@ -500,6 +505,26 @@ declare class Docula {
      * @returns {void}
      */
     generateInit(sitePath: string, typescript?: boolean): void;
+    /**
+     * Copy the template's variables.css to the site directory.
+     * If the file already exists and overwrite is false, prints an error.
+     * @param {string} sitePath
+     * @param {string} templatePath
+     * @param {string} templateName
+     * @param {boolean} overwrite
+     * @returns {void}
+     */
+    downloadVariables(sitePath: string, templatePath: string, templateName: string, overwrite?: boolean): void;
+    /**
+     * Copy the full template directory to {sitePath}/templates/{outputName}/.
+     * If the directory already exists and overwrite is false, prints an error.
+     * @param {string} sitePath
+     * @param {string} templatePath
+     * @param {string} templateName
+     * @param {boolean} overwrite
+     * @returns {void}
+     */
+    downloadTemplate(sitePath: string, templatePath: string, templateName: string, overwrite?: boolean): void;
     /**
      * Get the version of the package
      * @returns {string}

package/dist/docula.js

@@ -581,6 +581,9 @@ var DoculaConsole = class {
     );
     console.log(`    ${green("help")}           Print this help`);
     console.log(`    ${green("version")}        Print the version`);
+    console.log(
+      `    ${green("download")}       Download template files to your site directory`
+    );
     console.log();
     console.log(bold(cyan("  Common Options:")));
     console.log(
@@ -619,6 +622,17 @@ var DoculaConsole = class {
     console.log(
       `    ${yellow("-b, --build")}            Build the site before serving`
     );
+    console.log();
+    console.log(bold(cyan("  Download Options:")));
+    console.log(
+      `    ${yellow("variables")}              Copy variables.css to your site directory`
+    );
+    console.log(
+      `    ${yellow("template")}               Copy the full template to site/templates/<name>/`
+    );
+    console.log(
+      `    ${yellow("--overwrite")}            Overwrite existing files if they already exist`
+    );
   }
   parseProcessArgv(argv) {
     const command = this.getCommand(argv);
@@ -676,6 +690,9 @@ var DoculaConsole = class {
         case "version": {
           return "version";
         }
+        case "download": {
+          return "download";
+        }
       }
     }
   }
@@ -690,7 +707,9 @@ var DoculaConsole = class {
       build: false,
       port: void 0,
       typescript: false,
-      javascript: false
+      javascript: false,
+      overwrite: false,
+      downloadTarget: ""
     };
     for (let i = 0; i < argv.length; i++) {
       const argument = argv[i];
@@ -752,6 +771,36 @@ var DoculaConsole = class {
           arguments_.javascript = true;
           break;
         }
+        case "--overwrite": {
+          arguments_.overwrite = true;
+          break;
+        }
+      }
+    }
+    const downloadFlagsWithValues = /* @__PURE__ */ new Set([
+      "-s",
+      "--site",
+      "-o",
+      "--output",
+      "-p",
+      "--port",
+      "-t",
+      "--templatePath",
+      "-T",
+      "--template"
+    ]);
+    const downloadIndex = argv.indexOf("download");
+    if (downloadIndex !== -1) {
+      for (let i = downloadIndex + 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (downloadFlagsWithValues.has(token)) {
+          i++;
+          continue;
+        }
+        if (!token.startsWith("-")) {
+          arguments_.downloadTarget = token;
+          break;
+        }
       }
     }
     return arguments_;
@@ -1184,6 +1233,10 @@ function resolveTemplatePath(templatePath, templateName) {
 }
 
 // src/builder.ts
+var writrOptions = {
+  throwOnEmitError: false,
+  throwOnEmptyListeners: false
+};
 var DoculaBuilder = class {
   _options = new DoculaOptions();
   _ecto;
@@ -1360,6 +1413,12 @@ var DoculaBuilder = class {
       await this.buildFeedPage(doculaData);
       this._console.fileBuilt("feed.xml");
     }
+    if (doculaData.hasChangelog && doculaData.templates?.changelogEntry) {
+      await this.buildChangelogFeedJson(doculaData);
+      this._console.fileBuilt("changelog.json");
+      await this.buildChangelogLatestFeedJson(doculaData);
+      this._console.fileBuilt("changelog-latest.json");
+    }
     if (doculaData.hasDocuments) {
       this._console.step("Building documentation pages...");
       await this.buildDocsPages(doculaData);
@@ -1580,6 +1639,12 @@ var DoculaBuilder = class {
     if (data.documents?.length) {
       urls.push({ url: `${data.siteUrl}${data.baseUrl}/feed.xml` });
     }
+    if (data.hasChangelog && data.templates?.changelogEntry) {
+      urls.push({ url: `${data.siteUrl}${data.baseUrl}/changelog.json` });
+      urls.push({
+        url: `${data.siteUrl}${data.baseUrl}/changelog-latest.json`
+      });
+    }
     if (data.openApiUrl && data.templates?.api) {
       urls.push({
         url: `${data.siteUrl}${data.apiUrl}`
@@ -1650,7 +1715,7 @@ var DoculaBuilder = class {
         data.siteUrl,
         `${data.baseUrl}${this.normalizePathForUrl(document.urlPath)}`
       );
-      const summary = document.description || this.summarizeMarkdown(new Writr(document.content).body);
+      const summary = document.description || this.summarizeMarkdown(new Writr(document.content, writrOptions).body);
       xml += "<item>";
       xml += `<title>${this.escapeXml(itemTitle)}</title>`;
       xml += `<link>${this.escapeXml(itemLink)}</link>`;
@@ -1663,6 +1728,73 @@ var DoculaBuilder = class {
     await fs3.promises.mkdir(data.output, { recursive: true });
     await fs3.promises.writeFile(feedPath, xml, "utf8");
   }
+  async buildChangelogFeedJson(data) {
+    const entries = data.changelogEntries;
+    if (!entries?.length) {
+      return;
+    }
+    await this.writeChangelogFeedJson(data, entries, "changelog.json");
+  }
+  async buildChangelogLatestFeedJson(data) {
+    const entries = data.changelogEntries;
+    if (!entries?.length) {
+      return;
+    }
+    const latestEntries = entries.slice(0, this.options.changelogPerPage);
+    await this.writeChangelogFeedJson(
+      data,
+      latestEntries,
+      "changelog-latest.json"
+    );
+  }
+  async writeChangelogFeedJson(data, entries, filename) {
+    const feedUrl = this.buildAbsoluteSiteUrl(
+      data.siteUrl,
+      `${data.baseUrl}/${filename}`
+    );
+    const homeUrl = this.buildAbsoluteSiteUrl(data.siteUrl, `${data.baseUrl}/`);
+    const items = entries.map((entry) => {
+      const itemUrl = this.buildAbsoluteSiteUrl(
+        data.siteUrl,
+        `${data.changelogUrl}/${entry.slug}/`
+      );
+      const item = {
+        id: entry.slug,
+        title: entry.title,
+        url: itemUrl,
+        date_published: entry.date,
+        date_modified: entry.lastModified,
+        summary: entry.preview
+      };
+      if (entry.generatedHtml) {
+        item.content_html = entry.generatedHtml;
+      }
+      if (entry.content) {
+        item.content_text = entry.content;
+      }
+      if (entry.tag) {
+        item.tags = [entry.tag];
+      }
+      if (entry.previewImage) {
+        item.image = entry.previewImage;
+      }
+      return item;
+    });
+    const feed = {
+      version: "https://jsonfeed.org/version/1.1",
+      title: data.siteTitle,
+      description: data.siteDescription,
+      home_page_url: homeUrl,
+      feed_url: feedUrl,
+      items
+    };
+    await fs3.promises.mkdir(data.output, { recursive: true });
+    await fs3.promises.writeFile(
+      `${data.output}/${filename}`,
+      JSON.stringify(feed, null, 2),
+      "utf8"
+    );
+  }
   async buildLlmsFiles(data) {
     if (!this.options.enableLlmsTxt) {
       return;
@@ -1768,7 +1900,10 @@ var DoculaBuilder = class {
           data.siteUrl,
           `${data.baseUrl}${this.normalizePathForUrl(document.urlPath)}`
         );
-        const markdownBody = new Writr(document.content).body.trim();
+        const markdownBody = new Writr(
+          document.content,
+          writrOptions
+        ).body.trim();
         lines.push("");
         lines.push(`### ${document.navTitle}`);
         lines.push(`URL: ${documentUrl}`);
@@ -2010,7 +2145,7 @@ var DoculaBuilder = class {
         `${data.sitePath}/README.md`,
         "utf8"
       );
-      htmlReadme = await new Writr(readmeContent).render();
+      htmlReadme = await new Writr(readmeContent, writrOptions).render();
     }
     return htmlReadme;
   }
@@ -2018,7 +2153,7 @@ var DoculaBuilder = class {
     const announcementPath = `${data.sitePath}/announcement.md`;
     if (fs3.existsSync(announcementPath)) {
       const announcementContent = fs3.readFileSync(announcementPath, "utf8");
-      return new Writr(announcementContent).render();
+      return new Writr(announcementContent, writrOptions).render();
     }
     return void 0;
   }
@@ -2074,12 +2209,16 @@ var DoculaBuilder = class {
     }
     if (apiSpec) {
       apiSpec.info.description = new Writr(
-        apiSpec.info.description
+        apiSpec.info.description,
+        writrOptions
       ).renderSync();
       for (const group of apiSpec.groups) {
-        group.description = new Writr(group.description).renderSync();
+        group.description = new Writr(
+          group.description,
+          writrOptions
+        ).renderSync();
         for (const op of group.operations) {
-          op.description = new Writr(op.description).renderSync();
+          op.description = new Writr(op.description, writrOptions).renderSync();
         }
       }
     }
@@ -2146,7 +2285,7 @@ var DoculaBuilder = class {
   }
   parseChangelogEntry(filePath) {
     const fileContent = fs3.readFileSync(filePath, "utf8");
-    const writr = new Writr(fileContent);
+    const writr = new Writr(fileContent, writrOptions);
     const matterData = writr.frontMatter;
     const markdownContent = writr.body;
     const fileName = path5.basename(filePath, path5.extname(filePath));
@@ -2178,7 +2317,9 @@ var DoculaBuilder = class {
       tagClass,
       slug,
       content: markdownContent,
-      generatedHtml: new Writr(markdownContent).renderSync({ mdx: isMdx }),
+      generatedHtml: new Writr(markdownContent, writrOptions).renderSync({
+        mdx: isMdx
+      }),
       preview: this.generateChangelogPreview(markdownContent, 500, isMdx),
       previewImage,
       urlPath: `/${this.options.changelogPath}/${slug}/index.html`,
@@ -2193,7 +2334,7 @@ var DoculaBuilder = class {
     cleaned = cleaned.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
     cleaned = cleaned.replace(/^\n+/, "").trim();
     if (cleaned.length <= minLength) {
-      return new Writr(cleaned).renderSync({ mdx });
+      return new Writr(cleaned, writrOptions).renderSync({ mdx });
     }
     const searchArea = cleaned.slice(0, maxLength);
     let splitIndex = -1;
@@ -2236,7 +2377,7 @@ var DoculaBuilder = class {
     }
     if (splitIndex > 0) {
       const truncated2 = cleaned.slice(0, splitIndex).trim();
-      return new Writr(truncated2).renderSync({ mdx });
+      return new Writr(truncated2, writrOptions).renderSync({ mdx });
     }
     let truncated = cleaned.slice(0, maxLength);
     const lastSpace = truncated.lastIndexOf(" ");
@@ -2244,7 +2385,7 @@ var DoculaBuilder = class {
       truncated = truncated.slice(0, lastSpace);
     }
     truncated += "...";
-    return new Writr(truncated).renderSync({ mdx });
+    return new Writr(truncated, writrOptions).renderSync({ mdx });
   }
   convertReleaseToChangelogEntry(release) {
     const tagName = release.tag_name ?? "";
@@ -2276,7 +2417,7 @@ var DoculaBuilder = class {
       tagClass,
       slug,
       content: body,
-      generatedHtml: new Writr(body).renderSync(),
+      generatedHtml: new Writr(body, writrOptions).renderSync(),
       preview: this.generateChangelogPreview(body),
       urlPath: `/${this.options.changelogPath}/${slug}/index.html`,
       lastModified: dateString
@@ -2497,7 +2638,7 @@ var DoculaBuilder = class {
   }
   parseDocumentData(documentPath) {
     const documentContent = fs3.readFileSync(documentPath, "utf8");
-    const writr = new Writr(documentContent);
+    const writr = new Writr(documentContent, writrOptions);
     const matterData = writr.frontMatter;
     let markdownContent = writr.body;
     markdownContent = markdownContent.replace(/^# .*\n/, "");
@@ -2537,7 +2678,7 @@ ${markdownContent.slice(firstH2)}`;
       keywords: matterData.keywords ?? [],
       content: documentContent,
       markdown: markdownContent,
-      generatedHtml: new Writr(markdownContent).renderSync({
+      generatedHtml: new Writr(markdownContent, writrOptions).renderSync({
         toc: true,
         mdx: isMdx
       }),
@@ -3262,6 +3403,34 @@ var Docula = class {
         await this.serve(this.options);
         break;
       }
+      case "download": {
+        switch (consoleProcess.args.downloadTarget) {
+          case "variables": {
+            this.downloadVariables(
+              this.options.sitePath,
+              this.options.templatePath,
+              this.options.template,
+              consoleProcess.args.overwrite
+            );
+            break;
+          }
+          case "template": {
+            this.downloadTemplate(
+              this.options.sitePath,
+              this.options.templatePath,
+              this.options.template,
+              consoleProcess.args.overwrite
+            );
+            break;
+          }
+          default: {
+            this._console.error(
+              "Please specify a download target: 'variables' or 'template'"
+            );
+          }
+        }
+        break;
+      }
       default: {
         await this.runBuild(consoleProcess.args.clean);
         break;
@@ -3314,6 +3483,56 @@ var Docula = class {
       `docula initialized. Please update the ${doculaConfigFile} file with your site information. In addition, you can replace the image and favicon.`
     );
   }
+  /**
+   * Copy the template's variables.css to the site directory.
+   * If the file already exists and overwrite is false, prints an error.
+   * @param {string} sitePath
+   * @param {string} templatePath
+   * @param {string} templateName
+   * @param {boolean} overwrite
+   * @returns {void}
+   */
+  downloadVariables(sitePath, templatePath, templateName, overwrite = false) {
+    const resolvedTemplatePath = resolveTemplatePath(
+      templatePath,
+      templateName
+    );
+    const source = path6.join(resolvedTemplatePath, "css", "variables.css");
+    const dest = path6.join(sitePath, "variables.css");
+    if (fs4.existsSync(dest) && !overwrite) {
+      this._console.error(
+        `variables.css already exists at ${dest}. Use --overwrite to replace it.`
+      );
+      return;
+    }
+    fs4.copyFileSync(source, dest);
+    this._console.success(`variables.css copied to ${dest}`);
+  }
+  /**
+   * Copy the full template directory to {sitePath}/templates/{outputName}/.
+   * If the directory already exists and overwrite is false, prints an error.
+   * @param {string} sitePath
+   * @param {string} templatePath
+   * @param {string} templateName
+   * @param {boolean} overwrite
+   * @returns {void}
+   */
+  downloadTemplate(sitePath, templatePath, templateName, overwrite = false) {
+    const resolvedTemplatePath = resolveTemplatePath(
+      templatePath,
+      templateName
+    );
+    const outputName = templatePath ? path6.basename(resolvedTemplatePath) : templateName;
+    const dest = path6.join(sitePath, "templates", outputName);
+    if (fs4.existsSync(dest) && !overwrite) {
+      this._console.error(
+        `Template already exists at ${dest}. Use --overwrite to replace it.`
+      );
+      return;
+    }
+    fs4.cpSync(resolvedTemplatePath, dest, { recursive: true, force: true });
+    this._console.success(`Template copied to ${dest}`);
+  }
   /**
    * Get the version of the package
    * @returns {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -40,31 +40,31 @@
     "docula": "./bin/docula.js"
   },
   "dependencies": {
-    "@cacheable/net": "^2.0.5",
+    "@cacheable/net": "^2.0.6",
     "colorette": "^2.0.20",
-    "ecto": "^4.8.2",
+    "ecto": "^4.8.3",
     "feed": "^5.2.0",
     "hashery": "^1.5.0",
     "jiti": "^2.6.1",
-    "serve-handler": "^6.1.6",
+    "serve-handler": "^6.1.7",
     "update-notifier": "^7.3.1",
-    "writr": "^5.0.3"
+    "writr": "^6.0.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.2",
+    "@biomejs/biome": "^2.4.7",
     "@playwright/test": "^1.58.2",
     "@types/express": "^5.0.6",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.5.0",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.0",
     "dotenv": "^17.3.1",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "files": [
     "dist",