docula 1.10.1 → 1.11.1

package/dist/docula.d.ts

@@ -129,6 +129,12 @@ type ApiSpecData = {
     securitySchemes: ApiSecurityScheme[];
 };
 
+type DoculaOpenApiSpecEntry = {
+    name: string;
+    url: string;
+    order?: number;
+    apiSpec?: ApiSpecData;
+};
 type DoculaChangelogEntry = {
     title: string;
     date: string;
@@ -160,9 +166,9 @@ type DoculaData = {
     documents?: DoculaDocument[];
     sidebarItems?: DoculaSection[];
     announcement?: string;
-    openApiUrl?: string;
     hasApi?: boolean;
     apiSpec?: ApiSpecData;
+    openApiSpecs?: DoculaOpenApiSpecEntry[];
     changelogEntries?: DoculaChangelogEntry[];
     hasReadme?: boolean;
     themeMode?: string;
@@ -236,6 +242,11 @@ type DoculaHeaderLink = {
     url: string;
     icon?: string;
 };
+type DoculaOpenApiSpec = {
+    name: string;
+    url: string;
+    order?: number;
+};
 type DoculaOpenGraph = {
     title?: string;
     description?: string;
@@ -297,11 +308,11 @@ declare class DoculaOptions {
      */
     sections?: DoculaSection[];
     /**
-     * OpenAPI specification URL for API documentation.
-     * When provided, creates a dedicated /api page
-     * Supports both external URLs (https://...) and relative paths (/openapi.json)
+     * OpenAPI specification for API documentation.
+     * Pass a string URL for a single spec, or an array of DoculaOpenApiSpec for multiple specs.
+     * When provided, creates a dedicated /api page.
      */
-    openApiUrl?: string;
+    openApiUrl?: string | DoculaOpenApiSpec[];
     /**
      * When true, GitHub releases are converted to changelog entries and merged
      * with file-based changelog entries. Requires a changelog template to exist.
@@ -442,6 +453,7 @@ declare class DoculaBuilder {
     buildDocsPages(data: DoculaData): Promise<void>;
     renderApiContent(data: DoculaData): Promise<string>;
     buildApiPage(data: DoculaData): Promise<void>;
+    buildAllApiPages(data: DoculaData): Promise<void>;
     buildApiHomePage(data: DoculaData): Promise<void>;
     getChangelogEntries(changelogPath: string, cachedEntries?: Map<string, DoculaChangelogEntry>, previousHashes?: Record<string, string>, currentHashes?: Record<string, string>): DoculaChangelogEntry[];
     parseChangelogEntry(filePath: string): DoculaChangelogEntry;
@@ -575,4 +587,4 @@ declare class Docula {
     serve(options: DoculaOptions): Promise<http.Server>;
 }
 
-export { type DoculaAIOptions, type DoculaCacheOptions, type DoculaChangelogEntry, DoculaConsole, type DoculaCookieAuth, type DoculaHeaderLink, DoculaOptions, Docula as default };
+export { type DoculaAIOptions, type DoculaCacheOptions, type DoculaChangelogEntry, DoculaConsole, type DoculaCookieAuth, type DoculaHeaderLink, type DoculaOpenApiSpec, DoculaOptions, Docula as default };

package/dist/docula.js

@@ -222,7 +222,7 @@ function parseOpenApiSpec(specJson) {
       if (!operation) {
         continue;
       }
-      const tags = Array.isArray(operation.tags) && operation.tags.length > 0 ? operation.tags : ["Default"];
+      const tags = Array.isArray(operation.tags) && operation.tags.length > 0 ? operation.tags : [""];
       const parameters = extractParameters(operation, pathItem, spec);
       const requestBody = extractRequestBody(operation, spec);
       const responses = extractResponses(operation, spec);
@@ -832,7 +832,7 @@ async function buildSiteMapPage(data, options) {
       url: `${data.siteUrl}${data.baseUrl}/changelog-latest.json`
     });
   }
-  if (data.openApiUrl && data.templates?.api) {
+  if (data.hasApi || data.openApiSpecs?.[0] && data.templates?.api) {
     urls.push({
       url: `${data.siteUrl}${data.apiUrl}`
     });
@@ -926,26 +926,16 @@ var writrOptions3 = {
   throwOnEmptyListeners: false
 };
 function resolveOpenApiSpecUrl(data) {
-  if (!data.openApiUrl) {
+  const specUrl = data.openApiSpecs?.[0]?.url;
+  if (!specUrl) {
     return void 0;
   }
-  if (isRemoteUrl(data.openApiUrl)) {
-    return data.openApiUrl;
+  if (isRemoteUrl(specUrl)) {
+    return specUrl;
   }
-  const normalizedPath = data.openApiUrl.startsWith("/") ? data.openApiUrl : `/${data.openApiUrl}`;
+  const normalizedPath = specUrl.startsWith("/") ? specUrl : `/${specUrl}`;
   return buildAbsoluteSiteUrl(data.siteUrl, normalizedPath);
 }
-function resolveLocalOpenApiPath(data) {
-  if (!data.openApiUrl || isRemoteUrl(data.openApiUrl)) {
-    return void 0;
-  }
-  const openApiPathWithoutQuery = data.openApiUrl.split(/[?#]/)[0];
-  if (!openApiPathWithoutQuery) {
-    return void 0;
-  }
-  const normalizedPath = openApiPathWithoutQuery.startsWith("/") ? openApiPathWithoutQuery.slice(1) : openApiPathWithoutQuery;
-  return path3.join(data.sitePath, normalizedPath);
-}
 async function getSafeSiteOverrideFileContent(sitePath, fileName) {
   const resolvedSitePath = path3.resolve(sitePath);
   const candidatePath = path3.resolve(sitePath, fileName);
@@ -975,45 +965,152 @@ async function getSafeSiteOverrideFileContent(sitePath, fileName) {
   return fs3.promises.readFile(realCandidatePath, "utf8");
 }
 async function getSafeLocalOpenApiSpec(data) {
-  const localOpenApiPath = resolveLocalOpenApiPath(data);
-  if (!localOpenApiPath) {
+  const specUrl = data.openApiSpecs?.[0]?.url;
+  if (!specUrl) {
+    return void 0;
+  }
+  return getSafeLocalOpenApiSpecForSpec(data, specUrl);
+}
+function resolveLocalOpenApiPathForSpec(data, specUrl) {
+  if (isRemoteUrl(specUrl)) {
+    return void 0;
+  }
+  const urlWithoutQuery = specUrl.split(/[?#]/)[0];
+  if (!urlWithoutQuery) {
+    return void 0;
+  }
+  const normalizedPath = urlWithoutQuery.startsWith("/") ? urlWithoutQuery.slice(1) : urlWithoutQuery;
+  return path3.join(data.sitePath, normalizedPath);
+}
+async function getSafeLocalOpenApiSpecForSpec(data, specUrl) {
+  const localPath = resolveLocalOpenApiPathForSpec(data, specUrl);
+  if (!localPath) {
     return void 0;
   }
   const resolvedSitePath = path3.resolve(data.sitePath);
-  const resolvedLocalOpenApiPath = path3.resolve(localOpenApiPath);
-  if (!isPathWithinBasePath(resolvedLocalOpenApiPath, resolvedSitePath)) {
+  const resolvedLocalPath = path3.resolve(localPath);
+  if (!isPathWithinBasePath(resolvedLocalPath, resolvedSitePath)) {
     return void 0;
   }
-  let localOpenApiStats;
+  let localStats;
   try {
-    localOpenApiStats = await fs3.promises.lstat(resolvedLocalOpenApiPath);
+    localStats = await fs3.promises.lstat(resolvedLocalPath);
   } catch {
     return void 0;
   }
-  if (!localOpenApiStats.isFile() || localOpenApiStats.isSymbolicLink()) {
+  if (!localStats.isFile() || localStats.isSymbolicLink()) {
     return void 0;
   }
   let realSitePath;
-  let realLocalOpenApiPath;
+  let realLocalPath;
   try {
     realSitePath = await fs3.promises.realpath(resolvedSitePath);
-    realLocalOpenApiPath = await fs3.promises.realpath(resolvedLocalOpenApiPath);
+    realLocalPath = await fs3.promises.realpath(resolvedLocalPath);
   } catch {
     return void 0;
   }
-  if (!isPathWithinBasePath(realLocalOpenApiPath, realSitePath)) {
+  if (!isPathWithinBasePath(realLocalPath, realSitePath)) {
     return void 0;
   }
-  const localOpenApiContent = (await fs3.promises.readFile(realLocalOpenApiPath, "utf8")).trim();
-  return {
-    sourcePath: realLocalOpenApiPath,
-    content: localOpenApiContent
-  };
+  const content = (await fs3.promises.readFile(realLocalPath, "utf8")).trim();
+  return { sourcePath: realLocalPath, content };
+}
+function resolveSpecUrl(data, specUrl) {
+  if (isRemoteUrl(specUrl)) {
+    return specUrl;
+  }
+  const normalizedPath = specUrl.startsWith("/") ? specUrl : `/${specUrl}`;
+  return buildAbsoluteSiteUrl(data.siteUrl, normalizedPath);
+}
+async function parseAndRenderSpec(data, specUrl) {
+  let apiSpec;
+  const localSpec = await getSafeLocalOpenApiSpecForSpec(data, specUrl);
+  if (localSpec) {
+    apiSpec = parseOpenApiSpec(localSpec.content);
+  } else if (isRemoteUrl(specUrl)) {
+    try {
+      const response = await fetch(specUrl);
+      const specContent = await response.text();
+      apiSpec = parseOpenApiSpec(specContent);
+    } catch {
+    }
+  }
+  if (apiSpec) {
+    apiSpec.info.description = new Writr3(
+      apiSpec.info.description,
+      writrOptions3
+    ).renderSync();
+    for (const group of apiSpec.groups) {
+      group.description = new Writr3(
+        group.description,
+        writrOptions3
+      ).renderSync();
+      for (const op of group.operations) {
+        op.description = new Writr3(op.description, writrOptions3).renderSync();
+      }
+    }
+  }
+  return apiSpec;
+}
+async function copySpecSourceFile(data, specUrl, outputDir) {
+  const safeSpec = await getSafeLocalOpenApiSpecForSpec(data, specUrl);
+  if (safeSpec) {
+    await fs3.promises.mkdir(outputDir, { recursive: true });
+    await fs3.promises.copyFile(
+      safeSpec.sourcePath,
+      `${outputDir}/swagger.json`
+    );
+  }
+}
+async function renderCombinedApiContent(ecto, data) {
+  if (!data.templates?.api) {
+    throw new Error("No API template found");
+  }
+  const specs = data.openApiSpecs ?? [];
+  const apiSpecs = [];
+  for (const spec of specs) {
+    const urlDir = spec.url.replace(/[?#].*$/, "").replace(/\/[^/]+$/, "");
+    const specOutputDir = `${data.output}/${urlDir}`;
+    await copySpecSourceFile(data, spec.url, specOutputDir);
+    const apiSpec = await parseAndRenderSpec(data, spec.url);
+    apiSpecs.push({
+      specName: spec.name,
+      apiSpec,
+      specUrl: resolveSpecUrl(data, spec.url)
+    });
+  }
+  const apiTemplate = `${data.templatePath}/${data.templates.api}`;
+  return ecto.renderFromFile(
+    apiTemplate,
+    {
+      ...data,
+      apiSpecs,
+      // Backward compat: set single apiSpec for single-spec sites
+      apiSpec: apiSpecs[0]?.apiSpec,
+      specUrl: apiSpecs[0]?.specUrl,
+      ...resolveOpenGraphData(data, `/${data.apiPath}/`),
+      jsonLd: resolveJsonLd("api", data, `/${data.apiPath}/`)
+    },
+    data.templatePath
+  );
+}
+async function buildAllApiPages(ecto, data) {
+  if (!data.openApiSpecs || data.openApiSpecs.length === 0 || !data.templates?.api) {
+    return;
+  }
+  const outputDir = `${data.output}/${data.apiPath}`;
+  await fs3.promises.mkdir(outputDir, { recursive: true });
+  const content = await renderCombinedApiContent(ecto, data);
+  await fs3.promises.writeFile(`${outputDir}/index.html`, content, "utf8");
 }
 async function renderApiContent(ecto, data) {
-  if (!data.openApiUrl || !data.templates?.api) {
+  const firstSpecUrl = data.openApiSpecs?.[0]?.url;
+  if (!firstSpecUrl || !data.templates?.api) {
     throw new Error("No API template or openApiUrl found");
   }
+  if (data.openApiSpecs && data.openApiSpecs.length > 0) {
+    return renderCombinedApiContent(ecto, data);
+  }
   const swaggerSource = `${data.sitePath}/api/swagger.json`;
   const apiOutputPath = `${data.output}/${data.apiPath}`;
   await fs3.promises.mkdir(apiOutputPath, { recursive: true });
@@ -1024,9 +1121,9 @@ async function renderApiContent(ecto, data) {
   const localSpec = await getSafeLocalOpenApiSpec(data);
   if (localSpec) {
     apiSpec = parseOpenApiSpec(localSpec.content);
-  } else if (data.openApiUrl && isRemoteUrl(data.openApiUrl)) {
+  } else if (firstSpecUrl && isRemoteUrl(firstSpecUrl)) {
     try {
-      const response = await fetch(data.openApiUrl);
+      const response = await fetch(firstSpecUrl);
       const specContent = await response.text();
       apiSpec = parseOpenApiSpec(specContent);
     } catch {
@@ -1052,8 +1149,9 @@ async function renderApiContent(ecto, data) {
     apiTemplate,
     {
       ...data,
-      specUrl: data.openApiUrl,
+      specUrl: firstSpecUrl,
       apiSpec,
+      apiSpecs: [{ specName: "API Reference", apiSpec, specUrl: firstSpecUrl }],
       ...resolveOpenGraphData(data, `/${data.apiPath}/`),
       jsonLd: resolveJsonLd("api", data, `/${data.apiPath}/`)
     },
@@ -1061,12 +1159,13 @@ async function renderApiContent(ecto, data) {
   );
 }
 async function buildApiPage(ecto, data) {
-  if (!data.openApiUrl || !data.templates?.api) {
+  if (!data.openApiSpecs?.[0]?.url || !data.templates?.api) {
     return;
   }
-  const apiPath = `${data.output}/${data.apiPath}/index.html`;
+  const apiDir = `${data.output}/${data.apiPath}`;
+  await fs3.promises.mkdir(apiDir, { recursive: true });
   const apiContent = await renderApiContent(ecto, data);
-  await fs3.promises.writeFile(apiPath, apiContent, "utf8");
+  await fs3.promises.writeFile(`${apiDir}/index.html`, apiContent, "utf8");
 }
 async function buildApiHomePage(ecto, data) {
   const indexPath = `${data.output}/index.html`;
@@ -2282,7 +2381,13 @@ function generateLlmsIndexContent(data) {
   }
   lines.push("");
   lines.push("## API Reference");
-  if (data.hasApi) {
+  if (data.openApiSpecs && data.openApiSpecs.length > 1) {
+    for (const spec of data.openApiSpecs) {
+      lines.push(
+        `- [${spec.name}](${buildAbsoluteSiteUrl(data.siteUrl, data.apiUrl)})`
+      );
+    }
+  } else if (data.hasApi) {
     lines.push(
       `- [API Documentation](${buildAbsoluteSiteUrl(data.siteUrl, data.apiUrl)})`
     );
@@ -2344,8 +2449,22 @@ async function generateLlmsFullContent(data) {
   }
   lines.push("");
   lines.push("## API Reference");
-  if (data.hasApi) {
-    lines.push(`URL: ${buildAbsoluteSiteUrl(data.siteUrl, data.apiUrl)}`);
+  lines.push(`URL: ${buildAbsoluteSiteUrl(data.siteUrl, data.apiUrl)}`);
+  if (data.openApiSpecs && data.openApiSpecs.length > 1) {
+    for (const spec of data.openApiSpecs) {
+      lines.push("");
+      lines.push(`### ${spec.name}`);
+      lines.push("");
+      const localSpec = await getSafeLocalOpenApiSpecForSpec(data, spec.url);
+      if (localSpec) {
+        lines.push(`OpenAPI Spec Source: ${toPosixPath(localSpec.sourcePath)}`);
+        lines.push("");
+        lines.push(localSpec.content || "_No content_");
+      } else {
+        lines.push(`OpenAPI Spec URL: ${resolveSpecUrl(data, spec.url)}`);
+      }
+    }
+  } else if (data.hasApi) {
     lines.push("");
     const localOpenApiSpec = await getSafeLocalOpenApiSpec(data);
     if (localOpenApiSpec) {
@@ -2933,9 +3052,9 @@ var DoculaOptions = class {
    */
   sections;
   /**
-   * OpenAPI specification URL for API documentation.
-   * When provided, creates a dedicated /api page
-   * Supports both external URLs (https://...) and relative paths (/openapi.json)
+   * OpenAPI specification for API documentation.
+   * Pass a string URL for a single spec, or an array of DoculaOpenApiSpec for multiple specs.
+   * When provided, creates a dedicated /api page.
    */
   openApiUrl;
   /**
@@ -3104,7 +3223,20 @@ var DoculaOptions = class {
       this.port = options.port;
     }
     if (options.openApiUrl) {
-      this.openApiUrl = options.openApiUrl;
+      if (typeof options.openApiUrl === "string") {
+        this.openApiUrl = options.openApiUrl;
+      } else if (Array.isArray(options.openApiUrl)) {
+        const validSpecs = options.openApiUrl.filter(
+          (spec) => typeof spec === "object" && spec !== null && typeof spec.name === "string" && typeof spec.url === "string"
+        );
+        if (validSpecs.length > 0) {
+          this.openApiUrl = validSpecs.map((spec) => ({
+            name: spec.name,
+            url: spec.url,
+            ...typeof spec.order === "number" && { order: spec.order }
+          }));
+        }
+      }
     }
     if (options.enableReleaseChangelog !== void 0 && typeof options.enableReleaseChangelog === "boolean") {
       this.enableReleaseChangelog = options.enableReleaseChangelog;
@@ -3285,7 +3417,6 @@ var DoculaBuilder = class {
       output: this.options.output,
       githubPath: this.options.githubPath,
       sections: this.options.sections,
-      openApiUrl: this.options.openApiUrl,
       hasReadme: fs11.existsSync(`${this.options.sitePath}/README.md`),
       themeMode: this.options.themeMode,
       cookieAuth: this.options.cookieAuth,
@@ -3309,12 +3440,63 @@ var DoculaBuilder = class {
     if (doculaData.hasReadme) {
       currentAssetHashes["README.md"] = hashFile(this._hash, readmePath);
     }
-    if (!doculaData.openApiUrl && fs11.existsSync(`${doculaData.sitePath}/api/swagger.json`)) {
-      doculaData.openApiUrl = buildUrlPath(
-        this.options.baseUrl,
-        this.options.apiPath,
-        "swagger.json"
-      );
+    if (Array.isArray(this.options.openApiUrl)) {
+      doculaData.openApiSpecs = this.options.openApiUrl.map((spec) => ({
+        name: spec.name,
+        url: isRemoteUrl(spec.url) ? spec.url : buildUrlPath(this.options.apiPath, spec.url),
+        ...typeof spec.order === "number" && { order: spec.order }
+      }));
+    } else if (typeof this.options.openApiUrl === "string") {
+      doculaData.openApiSpecs = [
+        { name: "API Reference", url: this.options.openApiUrl }
+      ];
+    } else {
+      const detectedSpecs = [];
+      if (fs11.existsSync(`${doculaData.sitePath}/api/swagger.json`)) {
+        const rootUrl = buildUrlPath(
+          this.options.baseUrl,
+          this.options.apiPath,
+          "swagger.json"
+        );
+        detectedSpecs.push({
+          name: "API Reference",
+          url: rootUrl
+        });
+      }
+      const apiDir = `${doculaData.sitePath}/api`;
+      if (fs11.existsSync(apiDir)) {
+        try {
+          const entries = await fs11.promises.readdir(apiDir, {
+            withFileTypes: true
+          });
+          for (const entry of entries) {
+            if (entry.isDirectory() && fs11.existsSync(`${apiDir}/${entry.name}/swagger.json`)) {
+              const specUrl = buildUrlPath(
+                this.options.baseUrl,
+                this.options.apiPath,
+                entry.name,
+                "swagger.json"
+              );
+              const displayName = entry.name.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+              detectedSpecs.push({
+                name: displayName,
+                url: specUrl
+              });
+            }
+          }
+        } catch {
+        }
+      }
+      if (detectedSpecs.length > 0) {
+        doculaData.openApiSpecs = detectedSpecs;
+      }
+    }
+    if (doculaData.openApiSpecs && doculaData.openApiSpecs.length > 1) {
+      doculaData.openApiSpecs.sort((a, b) => {
+        const aOrder = a.order ?? Number.MAX_SAFE_INTEGER;
+        const bOrder = b.order ?? Number.MAX_SAFE_INTEGER;
+        return aOrder - bOrder;
+      });
     }
     if (this.options.githubPath) {
       doculaData.github = await this.getGithubData(this.options.githubPath);
@@ -3404,7 +3586,7 @@ var DoculaBuilder = class {
       doculaData.hasChangelog
     );
     doculaData.hasApi = Boolean(
-      doculaData.openApiUrl && doculaData.templates?.api
+      doculaData.openApiSpecs && doculaData.openApiSpecs.length > 0 && doculaData.templates?.api
     );
     doculaData.lastModified = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     this._console.step("Building pages...");
@@ -3445,7 +3627,7 @@ var DoculaBuilder = class {
     }
     if (doculaData.hasApi) {
       this._console.step("Building API page...");
-      await this.buildApiPage(doculaData);
+      await this.buildAllApiPages(doculaData);
       this._console.fileBuilt(`${this.options.apiPath}/index.html`);
     }
     if (doculaData.hasChangelog) {
@@ -3547,6 +3729,27 @@ var DoculaBuilder = class {
         swaggerPath
       );
     }
+    const apiDirPath = `${siteRelativePath}/api`;
+    if (fs11.existsSync(apiDirPath)) {
+      try {
+        const apiEntries = await fs11.promises.readdir(apiDirPath, {
+          withFileTypes: true
+        });
+        for (const entry of apiEntries) {
+          if (entry.isDirectory()) {
+            const subSwaggerPath = `${apiDirPath}/${entry.name}/swagger.json`;
+            if (fs11.existsSync(subSwaggerPath)) {
+              const hashKey = `api/${entry.name}/swagger.json`;
+              currentAssetHashes[hashKey] = hashFile(
+                this._hash,
+                subSwaggerPath
+              );
+            }
+          }
+        }
+      } catch {
+      }
+    }
     copyPublicFolder(
       this._console,
       this._hash,
@@ -3631,19 +3834,6 @@ ${readmeContent}`;
     }
     await fs11.promises.mkdir(this._options.sitePath, { recursive: true });
     await fs11.promises.writeFile(siteReadmePath, readmeContent, "utf8");
-    const availableAssets = listContentAssets(this._options, cwdDir);
-    for (const assetRelPath of availableAssets) {
-      if (readmeContent.includes(assetRelPath)) {
-        const source = path12.join(cwdDir, assetRelPath);
-        const stat = await fs11.promises.lstat(source);
-        if (stat.isSymbolicLink()) {
-          continue;
-        }
-        const target = path12.join(this._options.sitePath, assetRelPath);
-        await fs11.promises.mkdir(path12.dirname(target), { recursive: true });
-        await fs11.promises.copyFile(source, target);
-      }
-    }
   }
   async getGithubData(githubPath) {
     const paths = githubPath.split("/");
@@ -3849,6 +4039,9 @@ ${readmeContent}`;
   async buildApiPage(data) {
     return buildApiPage(this._ecto, data);
   }
+  async buildAllApiPages(data) {
+    return buildAllApiPages(this._ecto, data);
+  }
   async buildApiHomePage(data) {
     return buildApiHomePage(this._ecto, data);
   }
@@ -4380,6 +4573,7 @@ export {
 /* v8 ignore start -- @preserve */
 /* v8 ignore next -- @preserve */
 /* v8 ignore next 3 -- @preserve */
+/* v8 ignore next 6 -- @preserve */
 /* v8 ignore next 9 -- @preserve */
 /* v8 ignore next 4 -- @preserve */
 /* v8 ignore next 5 -- @preserve */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -87,7 +87,8 @@
     "generate-init-file": "tsx scripts/generate-init-file.ts",
     "website:build": "node bin/docula.js build -s ./site -o ./site/dist",
     "website:serve": "pnpm build && node bin/docula.js dev -s ./site -p 3333",
-    "website:mega": "node bin/docula.js serve -s ./test/fixtures/mega-page-site --watch --clean",
+    "website:mapi": "pnpm build && node bin/docula.js dev -s ./test/fixtures/multi-api-site -p 3333",
+    "website:mega": "node bin/docula.js dev -s ./test/fixtures/mega-page-site",
     "website:mega:custom": "node bin/docula.js serve -s ./test/fixtures/mega-custom-template --watch",
     "website:singlepage": "node bin/docula.js dev -s ./test/fixtures/single-page-site --clean",
     "website:nohome": "node bin/docula.js serve -s ./test/fixtures/mega-page-site-no-home-page --watch --clean",

package/templates/classic/api.hbs

@@ -29,7 +29,7 @@
   </style>
   {{/if}}
 
-  {{#if apiSpec}}
+  {{#if apiSpecs}}
   <div class="api-mobile-toggle">
     <button id="api-sidebar-toggle">
       <span>API Navigation</span>
@@ -41,12 +41,17 @@
     <aside class="api-sidebar" id="api-sidebar">
       <input type="text" class="api-search" id="api-search" placeholder="Search endpoints..." />
 
-      {{#each apiSpec.groups}}
+      {{#each apiSpecs}}
+      {{#if this.apiSpec}}
+      <div class="api-sidebar__spec-heading">{{this.specName}}</div>
+      {{#each this.apiSpec.groups}}
       <div class="api-sidebar__group" data-group="{{this.id}}">
+        {{#if this.name}}
         <button class="api-sidebar__group-toggle">
           <span>{{this.name}}</span>
           <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>
         </button>
+        {{/if}}
         <div class="api-sidebar__group-items">
           {{#each this.operations}}
           <a href="#{{this.id}}" class="api-sidebar__item" data-method="{{this.method}}" data-path="{{this.path}}">
@@ -57,21 +62,25 @@
         </div>
       </div>
       {{/each}}
+      {{/if}}
+      {{/each}}
     </aside>
 
     <main class="api-content">
+      {{#each apiSpecs}}
+      {{#if this.apiSpec}}
       <section class="api-info">
-        <h1 class="api-info__title">{{apiSpec.info.title}}</h1>
-        {{#if apiSpec.info.version}}
-        <span class="api-info__version">v{{apiSpec.info.version}}</span>
+        <h1 class="api-info__title">{{this.apiSpec.info.title}}</h1>
+        {{#if this.apiSpec.info.version}}
+        <span class="api-info__version">v{{this.apiSpec.info.version}}</span>
         {{/if}}
-        {{#if apiSpec.info.description}}
-        <div class="api-info__description">{{{apiSpec.info.description}}}</div>
+        {{#if this.apiSpec.info.description}}
+        <div class="api-info__description">{{{this.apiSpec.info.description}}}</div>
         {{/if}}
-        {{#if apiSpec.servers}}
+        {{#if this.apiSpec.servers}}
         <div class="api-info__servers">
           <div class="api-info__server-label">Server</div>
-          {{#each apiSpec.servers}}
+          {{#each this.apiSpec.servers}}
           <code class="api-info__server-url">{{this.url}}</code>
           {{/each}}
         </div>
@@ -79,24 +88,26 @@
         <div class="api-auth">
           <div class="api-auth__label">Authorization</div>
           <div class="api-auth__controls">
-            <select class="api-auth__type" id="api-auth-type">
+            <select class="api-auth__type" id="api-auth-type-{{@index}}">
               <option value="none">None</option>
               <option value="apikey">API Key (x-api-key)</option>
               <option value="bearer">Bearer Token</option>
             </select>
-            <input type="password" class="api-auth__value api-auth__value--hidden" id="api-auth-value" placeholder="Enter value..." />
+            <input type="password" class="api-auth__value api-auth__value--hidden" id="api-auth-value-{{@index}}" placeholder="Enter value..." />
           </div>
         </div>
       </section>
 
-      {{#each apiSpec.groups}}
+      {{#each this.apiSpec.groups}}
       <div class="api-group" id="group-{{this.id}}">
+        {{#if this.name}}
         <div class="api-group__header">
           <h2 class="api-group__title">{{this.name}}</h2>
           {{#if this.description}}
           <div class="api-group__description">{{{this.description}}}</div>
           {{/if}}
         </div>
+        {{/if}}
 
         {{#each this.operations}}
         <div class="api-operation api-operation--collapsed" id="{{this.id}}">
@@ -202,6 +213,8 @@
         {{/each}}
       </div>
       {{/each}}
+      {{/if}}
+      {{/each}}
     </main>
   </div>
   {{/if}}

package/templates/classic/css/api.css

@@ -1,5 +1,19 @@
 /* API Reference - Classic Template */
 
+.api-sidebar__spec-heading {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text-primary, #333);
+  padding: 10px 10px 4px;
+  margin-top: 8px;
+  border-top: 1px solid var(--border-color, #e0e0e0);
+}
+
+.api-sidebar__spec-heading:first-child {
+  margin-top: 0;
+  border-top: none;
+}
+
 .api-reference {
   display: flex;
   max-width: 90%;

package/templates/classic/includes/multipage/api-reference.hbs

@@ -1 +1 @@
-<a href="/api" class="home-docs-button">API Reference</a>
+<a href="{{apiUrl}}" class="home-docs-button">API Reference</a>

package/templates/classic/includes/multipage/header.hbs

@@ -2,7 +2,7 @@
   <div class="header-content">
     <nav class="nav">
       <div class="header-menu hide-d">
-        <a class="header-logo" href="/">
+        <a class="header-logo" href="{{#if homeUrl}}{{homeUrl}}{{else}}/{{/if}}">
           <img src="/logo.svg" alt="logo" />
         </a>
         {{#if headerLinks}}

package/templates/classic/includes/multipage/sidebar.hbs

@@ -1,6 +1,6 @@
 <aside class="sidebar hidden" id="sidebar">
   <div class="sidebar-logo">
-    <a class="header-link" href="/">
+    <a class="header-link" href="{{#if homeUrl}}{{homeUrl}}{{else}}/{{/if}}">
       <img src="/logo.svg" alt="logo"/>
     </a>
   </div>

package/templates/modern/api.hbs

@@ -12,7 +12,7 @@
 <body>
   {{> header-bar }}
 
-  {{#if apiSpec}}
+  {{#if apiSpecs}}
   <div class="api-mobile-toggle">
     <button id="api-sidebar-toggle">
       <span>API Navigation</span>
@@ -24,12 +24,17 @@
     <aside class="api-sidebar" id="api-sidebar">
       <input type="text" class="api-search" id="api-search" placeholder="Search endpoints..." />
 
-      {{#each apiSpec.groups}}
+      {{#each apiSpecs}}
+      {{#if this.apiSpec}}
+      <div class="api-sidebar__spec-heading">{{this.specName}}</div>
+      {{#each this.apiSpec.groups}}
       <div class="api-sidebar__group" data-group="{{this.id}}">
+        {{#if this.name}}
         <button class="api-sidebar__group-toggle">
           <span>{{this.name}}</span>
           <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>
         </button>
+        {{/if}}
         <div class="api-sidebar__group-items">
           {{#each this.operations}}
           <a href="#{{this.id}}" class="api-sidebar__item" data-method="{{this.method}}" data-path="{{this.path}}">
@@ -40,87 +45,56 @@
         </div>
       </div>
       {{/each}}
+      {{/if}}
+      {{/each}}
     </aside>
 
     <main class="api-content">
+      {{#each apiSpecs}}
+      {{#if this.apiSpec}}
       <section class="api-info">
-        <h1 class="api-info__title">{{apiSpec.info.title}}</h1>
-        {{#if apiSpec.info.version}}
-        <span class="api-info__version">v{{apiSpec.info.version}}</span>
+        <h1 class="api-info__title">{{this.apiSpec.info.title}}</h1>
+        {{#if this.apiSpec.info.version}}
+        <span class="api-info__version">v{{this.apiSpec.info.version}}</span>
         {{/if}}
-        {{#if apiSpec.info.description}}
-        <div class="api-info__description">{{{apiSpec.info.description}}}</div>
+        {{#if this.apiSpec.info.description}}
+        <div class="api-info__description">{{{this.apiSpec.info.description}}}</div>
         {{/if}}
-        {{#if apiSpec.servers}}
+        {{#if this.apiSpec.servers}}
         <div class="api-info__servers">
           <div class="api-info__server-label">Server</div>
-          {{#each apiSpec.servers}}
+          {{#each this.apiSpec.servers}}
           <code class="api-info__server-url">{{this.url}}</code>
           {{/each}}
         </div>
         {{/if}}
-        {{#if apiSpec.securitySchemes.length}}
+        {{#if this.apiSpec.securitySchemes.length}}
         <div class="api-auth">
           <div class="api-auth__label">Authorization</div>
           <div class="api-auth__controls">
-            <select class="api-auth__type" id="api-auth-type">
+            <select class="api-auth__type" id="api-auth-type-{{@index}}">
               <option value="none">None</option>
-              {{#each apiSpec.securitySchemes}}
+              {{#each this.apiSpec.securitySchemes}}
               <option value="{{this.key}}" data-scheme-type="{{this.type}}" data-scheme-scheme="{{this.scheme}}" data-scheme-name="{{this.name}}" data-scheme-in="{{this.in}}">{{this.description}}</option>
               {{/each}}
             </select>
-            <input type="password" class="api-auth__value api-auth__value--hidden" id="api-auth-value" placeholder="Enter value..." />
-            <span class="api-auth__cookie-status api-auth__cookie-status--hidden" id="api-auth-cookie-status"></span>
-            <script>
-              (function() {
-                var authTypeSelect = document.getElementById('api-auth-type');
-                if (!authTypeSelect) return;
-
-                // Restore selection from localStorage
-                var savedAuthType = localStorage.getItem('docula-api-auth-type');
-                if (savedAuthType) {
-                  for (var i = 0; i < authTypeSelect.options.length; i++) {
-                    if (authTypeSelect.options[i].value === savedAuthType) {
-                      authTypeSelect.selectedIndex = i;
-                      break;
-                    }
-                  }
-                }
-
-                // Update UI based on selection
-                var selectedOption = authTypeSelect.options[authTypeSelect.selectedIndex];
-                var authValueInput = document.getElementById('api-auth-value');
-                var cookieStatusBadge = document.getElementById('api-auth-cookie-status');
-
-                if (selectedOption.value === 'none') return;
-
-                var isCookieAuth = selectedOption.getAttribute('data-scheme-type') === 'apiKey'
-                  && selectedOption.getAttribute('data-scheme-in') === 'cookie';
-
-                if (isCookieAuth) {
-                  if (cookieStatusBadge) {
-                    var auth = window.__doculaAuth || { loggedIn: false };
-                    cookieStatusBadge.textContent = auth.loggedIn ? 'Logged in' : 'Not logged in — use Login button above';
-                    cookieStatusBadge.className = 'api-auth__cookie-status' + (auth.loggedIn ? ' api-auth__cookie-status--ok' : ' api-auth__cookie-status--warn');
-                  }
-                } else {
-                  if (authValueInput) authValueInput.classList.remove('api-auth__value--hidden');
-                }
-              })();
-            </script>
+            <input type="password" class="api-auth__value api-auth__value--hidden" id="api-auth-value-{{@index}}" placeholder="Enter value..." />
+            <span class="api-auth__cookie-status api-auth__cookie-status--hidden" id="api-auth-cookie-status-{{@index}}"></span>
           </div>
         </div>
         {{/if}}
       </section>
 
-      {{#each apiSpec.groups}}
+      {{#each this.apiSpec.groups}}
       <div class="api-group" id="group-{{this.id}}">
+        {{#if this.name}}
         <div class="api-group__header">
           <h2 class="api-group__title">{{this.name}}</h2>
           {{#if this.description}}
           <div class="api-group__description">{{{this.description}}}</div>
           {{/if}}
         </div>
+        {{/if}}
 
         {{#each this.operations}}
         <div class="api-operation api-operation--collapsed" id="{{this.id}}">
@@ -244,6 +218,8 @@
         {{/each}}
       </div>
       {{/each}}
+      {{/if}}
+      {{/each}}
     </main>
   </div>
   {{/if}}

package/templates/modern/css/api.css

@@ -50,6 +50,20 @@
   color: var(--muted-fg);
 }
 
+.api-sidebar__spec-heading {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--fg);
+  padding: 10px 10px 4px;
+  margin-top: 8px;
+  border-top: 1px solid var(--border);
+}
+
+.api-sidebar__spec-heading:first-child {
+  margin-top: 0;
+  border-top: none;
+}
+
 .api-sidebar__group {
   margin-bottom: 4px;
 }

package/templates/modern/includes/header-bar.hbs

@@ -4,24 +4,18 @@
       <button class="mobile-menu-toggle" id="mobile-menu-toggle" aria-label="Toggle navigation menu">
         <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" x2="20" y1="12" y2="12"/><line x1="4" x2="20" y1="6" y2="6"/><line x1="4" x2="20" y1="18" y2="18"/></svg>
       </button>
-      <a href="{{baseUrl}}/" class="logo-link">
+      <a href="{{#if homeUrl}}{{homeUrl}}{{else}}{{baseUrl}}/{{/if}}" class="logo-link">
         <img alt="{{siteTitle}}" class="logo__img" src="{{baseUrl}}/logo.svg">
         <span class="logo__text">{{siteTitle}}</span>
       </a>
       <nav class="header-bottom__nav">
-        {{#if homeUrl}}
-        <a class="header-bottom__item header-bottom__item--home" href="{{homeUrl}}">
-          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m12 19-7-7 7-7"/><path d="M19 12H5"/></svg>
-          <span>Back to Home</span>
-        </a>
-        {{/if}}
         {{#if hasDocuments}}
         <a class="header-bottom__item" href="{{docsUrl}}/" id="nav-docs">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 7v14"/><path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
           <span>Documentation</span>
         </a>
         {{/if}}
-        {{#if openApiUrl}}
+        {{#if hasApi}}
         <a class="header-bottom__item" href="{{apiUrl}}" id="nav-api">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/></svg>
           <span>API Reference</span>
@@ -74,19 +68,13 @@
 </header>
 <aside class="mobile-sidebar" id="mobile-sidebar">
   <nav class="mobile-nav">
-    {{#if homeUrl}}
-    <a class="mobile-nav__item" href="{{homeUrl}}">
-      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m12 19-7-7 7-7"/><path d="M19 12H5"/></svg>
-      <span>Back to Home</span>
-    </a>
-    {{/if}}
     {{#if hasDocuments}}
     <a class="mobile-nav__item" href="{{docsUrl}}/">
       <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 7v14"/><path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
       <span>Documentation</span>
     </a>
     {{/if}}
-    {{#if openApiUrl}}
+    {{#if hasApi}}
     <a class="mobile-nav__item" href="{{apiUrl}}">
       <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/></svg>
       <span>API Reference</span>

package/templates/modern/js/api.js

@@ -99,15 +99,18 @@ document.addEventListener('DOMContentLoaded', function() {
     });
   }
 
-  // Collapse all sidebar groups by default
+  // Collapse sidebar groups that have a toggle button (named groups only)
   document.querySelectorAll('.api-sidebar__group').forEach(function(group) {
-    group.classList.add('api-sidebar__group--collapsed');
+    if (group.querySelector('.api-sidebar__group-toggle')) {
+      group.classList.add('api-sidebar__group--collapsed');
+    }
   });
 
   // Auth type selector: show/hide value input based on OpenAPI securitySchemes
-  var authTypeSelect = document.getElementById('api-auth-type');
-  var authValueInput = document.getElementById('api-auth-value');
-  var cookieStatusEl = document.getElementById('api-auth-cookie-status');
+  // IDs are indexed for multi-spec (e.g. api-auth-type-0), so find by class
+  var authTypeSelect = document.querySelector('.api-auth__type');
+  var authValueInput = document.querySelector('.api-auth__value');
+  var cookieStatusEl = document.querySelector('.api-auth__cookie-status');
   if (authTypeSelect && authValueInput) {
     function getSelectedSchemeData() {
       var option = authTypeSelect.options[authTypeSelect.selectedIndex];
@@ -271,8 +274,8 @@ document.addEventListener('DOMContentLoaded', function() {
       });
 
       // Inject global auth header from selected security scheme
-      var authType = document.getElementById('api-auth-type');
-      var authValue = document.getElementById('api-auth-value');
+      var authType = document.querySelector('.api-auth__type');
+      var authValue = document.querySelector('.api-auth__value');
       var useCookieAuth = false;
       if (authType && authType.value !== 'none') {
         var authOption = authType.options[authType.selectedIndex];