docula 1.0.0 → 1.2.0

package/README.md

@@ -36,7 +36,7 @@
 * 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.
+* Will generate a sitemap.xml, robots.txt, and `feed.xml` for your site.
 * Automatically generates `llms.txt` and `llms-full.txt` for LLM-friendly indexing of docs, API reference, and changelog content.
 * Uses Github release notes to generate a changelog / releases page.
 * Uses Github to show contributors and link to their profiles.
@@ -558,6 +558,15 @@ When changelog entries are found, Docula generates:
 
 Changelog URLs are also automatically added to the generated `sitemap.xml`.
 
+## RSS Feed
+
+Docula automatically generates a docs-only RSS 2.0 feed at `/feed.xml` when your site has documentation pages.
+
+- The feed includes one item per generated doc page.
+- Each item uses the document title and canonical page URL.
+- Item descriptions prefer front matter descriptions and otherwise fall back to a short excerpt from the markdown body.
+- `/feed.xml` is added to `sitemap.xml` for discovery.
+
 ## 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`:

package/dist/docula.d.ts

@@ -52,6 +52,27 @@ type ApiGroup = {
     id: string;
     operations: ApiOperation[];
 };
+type ApiOAuth2Flow = {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+};
+type ApiSecurityScheme = {
+    key: string;
+    type: string;
+    scheme?: string;
+    bearerFormat?: string;
+    name?: string;
+    in?: string;
+    description: string;
+    flows?: {
+        authorizationCode?: ApiOAuth2Flow;
+        implicit?: ApiOAuth2Flow;
+        clientCredentials?: ApiOAuth2Flow;
+        password?: ApiOAuth2Flow;
+    };
+};
 type ApiSpecData = {
     info: {
         title: string;
@@ -63,6 +84,7 @@ type ApiSpecData = {
         description: string;
     }>;
     groups: ApiGroup[];
+    securitySchemes: ApiSecurityScheme[];
 };
 
 type GithubData = {
@@ -75,6 +97,11 @@ type DoculaCookieAuth = {
     cookieName?: string;
     logoutUrl?: string;
 };
+type DoculaHeaderLink = {
+    label: string;
+    url: string;
+    icon?: string;
+};
 type DoculaCacheOptions = {
     github: {
         ttl: number;
@@ -161,6 +188,11 @@ declare class DoculaOptions {
      * in the header based on whether a JWT cookie is present.
      */
     cookieAuth?: DoculaCookieAuth;
+    /**
+     * Additional links to display in the site header navigation.
+     * Each link requires a label and url.
+     */
+    headerLinks?: DoculaHeaderLink[];
     /**
      * File extensions to copy as assets from docs/ and changelog/ directories.
      * Override in docula.config to customize.
@@ -217,6 +249,13 @@ type DoculaData = {
         cookieName?: string;
         logoutUrl?: string;
     };
+    headerLinks?: Array<{
+        label: string;
+        url: string;
+        icon?: string;
+    }>;
+    enableLlmsTxt?: boolean;
+    hasFeed?: boolean;
 };
 type DoculaTemplates = {
     home: string;
@@ -258,11 +297,14 @@ declare class DoculaBuilder {
     getTemplateFile(path: string, name: string): Promise<string | undefined>;
     buildRobotsPage(options: DoculaOptions): Promise<void>;
     buildSiteMapPage(data: DoculaData): Promise<void>;
+    buildFeedPage(data: DoculaData): Promise<void>;
     buildLlmsFiles(data: DoculaData): Promise<void>;
     private generateLlmsIndexContent;
     private generateLlmsFullContent;
     private buildAbsoluteSiteUrl;
     private normalizePathForUrl;
+    private escapeXml;
+    private summarizeMarkdown;
     private isRemoteUrl;
     private resolveOpenApiSpecUrl;
     private resolveLocalOpenApiPath;
@@ -392,4 +434,4 @@ declare class Docula {
     serve(options: DoculaOptions): Promise<http.Server>;
 }
 
-export { type DoculaCacheOptions, type DoculaCookieAuth, DoculaOptions, Docula as default };
+export { type DoculaCacheOptions, type DoculaCookieAuth, type DoculaHeaderLink, DoculaOptions, Docula as default };

package/dist/docula.js

@@ -100,7 +100,43 @@ function parseOpenApiSpec(specJson) {
       operations
     });
   }
-  return { info, servers, groups };
+  const securitySchemes = [];
+  const schemesObj = spec.components?.securitySchemes;
+  if (schemesObj && typeof schemesObj === "object") {
+    for (const [key, value] of Object.entries(schemesObj)) {
+      const scheme = value;
+      const entry = {
+        key,
+        type: scheme.type ?? "",
+        scheme: scheme.scheme,
+        bearerFormat: scheme.bearerFormat,
+        name: scheme.name,
+        in: scheme.in,
+        description: scheme.description ?? ""
+      };
+      if (scheme.type === "oauth2" && scheme.flows) {
+        entry.flows = {};
+        for (const flowType of [
+          "authorizationCode",
+          "implicit",
+          "clientCredentials",
+          "password"
+        ]) {
+          const flow = scheme.flows[flowType];
+          if (flow) {
+            entry.flows[flowType] = {
+              authorizationUrl: flow.authorizationUrl,
+              tokenUrl: flow.tokenUrl,
+              refreshUrl: flow.refreshUrl,
+              scopes: flow.scopes ?? {}
+            };
+          }
+        }
+      }
+      securitySchemes.push(entry);
+    }
+  }
+  return { info, servers, groups, securitySchemes };
 }
 function getStatusClass(statusCode) {
   if (statusCode.startsWith("2")) {
@@ -200,7 +236,7 @@ function getSchemaType(schema) {
   if (schema.type === "array") {
     const items = schema.items;
     const itemType = items?.type ?? "any";
-    return `array<${itemType}>`;
+    return `array(${itemType})`;
   }
   if (schema.type) {
     if (schema.format) {
@@ -920,6 +956,11 @@ var DoculaOptions = class {
    * in the header based on whether a JWT cookie is present.
    */
   cookieAuth;
+  /**
+   * Additional links to display in the site header navigation.
+   * Each link requires a label and url.
+   */
+  headerLinks;
   /**
    * File extensions to copy as assets from docs/ and changelog/ directories.
    * Override in docula.config to customize.
@@ -1027,6 +1068,14 @@ var DoculaOptions = class {
     if (options.cookieAuth && typeof options.cookieAuth === "object" && typeof options.cookieAuth.loginUrl === "string") {
       this.cookieAuth = options.cookieAuth;
     }
+    if (options.headerLinks && Array.isArray(options.headerLinks)) {
+      const validLinks = options.headerLinks.filter(
+        (link) => typeof link === "object" && link !== null && typeof link.label === "string" && typeof link.url === "string"
+      );
+      if (validLinks.length > 0) {
+        this.headerLinks = validLinks;
+      }
+    }
   }
 };
 
@@ -1094,7 +1143,9 @@ var DoculaBuilder = class {
       openApiUrl: this.options.openApiUrl,
       homePage: this.options.homePage,
       themeMode: this.options.themeMode,
-      cookieAuth: this.options.cookieAuth
+      cookieAuth: this.options.cookieAuth,
+      headerLinks: this.options.headerLinks,
+      enableLlmsTxt: this.options.enableLlmsTxt
     };
     if (!doculaData.openApiUrl && fs3.existsSync(`${doculaData.sitePath}/api/swagger.json`)) {
       doculaData.openApiUrl = "/api/swagger.json";
@@ -1111,6 +1162,7 @@ var DoculaBuilder = class {
       this.options
     );
     doculaData.hasDocuments = doculaData.documents?.length > 0;
+    doculaData.hasFeed = doculaData.hasDocuments;
     const changelogPath = `${doculaData.sitePath}/changelog`;
     const fileChangelogEntries = this.getChangelogEntries(changelogPath);
     const hasChangelogTemplate = await this.getTemplateFile(resolvedTemplatePath, "changelog") !== void 0;
@@ -1162,6 +1214,10 @@ var DoculaBuilder = class {
     this._console.fileBuilt("sitemap.xml");
     await this.buildRobotsPage(this.options);
     this._console.fileBuilt("robots.txt");
+    if (doculaData.hasDocuments) {
+      await this.buildFeedPage(doculaData);
+      this._console.fileBuilt("feed.xml");
+    }
     if (doculaData.hasDocuments) {
       this._console.step("Building documentation pages...");
       await this.buildDocsPages(doculaData);
@@ -1325,6 +1381,9 @@ var DoculaBuilder = class {
   async buildSiteMapPage(data) {
     const sitemapPath = `${data.output}/sitemap.xml`;
     const urls = [{ url: data.siteUrl }];
+    if (data.documents?.length) {
+      urls.push({ url: `${data.siteUrl}/feed.xml` });
+    }
     if (data.openApiUrl && data.templates?.api) {
       urls.push({ url: `${data.siteUrl}/api` });
     }
@@ -1354,6 +1413,40 @@ var DoculaBuilder = class {
     await fs3.promises.mkdir(data.output, { recursive: true });
     await fs3.promises.writeFile(sitemapPath, xml, "utf8");
   }
+  async buildFeedPage(data) {
+    if (!data.documents?.length) {
+      return;
+    }
+    const feedPath = `${data.output}/feed.xml`;
+    const channelLink = this.buildAbsoluteSiteUrl(data.siteUrl, "/");
+    const feedUrl = this.buildAbsoluteSiteUrl(data.siteUrl, "/feed.xml");
+    let xml = '<?xml version="1.0" encoding="UTF-8"?>';
+    xml += '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">';
+    xml += "<channel>";
+    xml += `<title>${this.escapeXml(data.siteTitle)}</title>`;
+    xml += `<link>${this.escapeXml(channelLink)}</link>`;
+    xml += `<description>${this.escapeXml(data.siteDescription)}</description>`;
+    xml += `<lastBuildDate>${this.escapeXml((/* @__PURE__ */ new Date()).toUTCString())}</lastBuildDate>`;
+    xml += `<atom:link href="${this.escapeXml(feedUrl)}" rel="self" type="application/rss+xml" />`;
+    for (const document of data.documents) {
+      const itemTitle = document.navTitle || document.title || document.urlPath;
+      const itemLink = this.buildAbsoluteSiteUrl(
+        data.siteUrl,
+        this.normalizePathForUrl(document.urlPath)
+      );
+      const summary = document.description || this.summarizeMarkdown(new Writr(document.content).body);
+      xml += "<item>";
+      xml += `<title>${this.escapeXml(itemTitle)}</title>`;
+      xml += `<link>${this.escapeXml(itemLink)}</link>`;
+      xml += `<guid isPermaLink="true">${this.escapeXml(itemLink)}</guid>`;
+      xml += `<description>${this.escapeXml(summary)}</description>`;
+      xml += "</item>";
+    }
+    xml += "</channel>";
+    xml += "</rss>";
+    await fs3.promises.mkdir(data.output, { recursive: true });
+    await fs3.promises.writeFile(feedPath, xml, "utf8");
+  }
   async buildLlmsFiles(data) {
     if (!this.options.enableLlmsTxt) {
       return;
@@ -1531,6 +1624,16 @@ var DoculaBuilder = class {
     }
     return urlPath;
   }
+  escapeXml(value) {
+    return String(value ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+  }
+  summarizeMarkdown(markdown, maxLength = 240) {
+    const plainText = markdown.replace(/^#{1,6}\s+.*$/gm, " ").replace(/^\s*[-*+]\s+/gm, " ").replace(/^\s*---+\s*$/gm, " ").replace(/```[\s\S]*?```/g, " ").replace(/`([^`]+)`/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[*_~>#]+/g, " ").replace(/\s+/g, " ").trim();
+    if (plainText.length <= maxLength) {
+      return plainText;
+    }
+    return `${plainText.slice(0, maxLength).trimEnd()}...`;
+  }
   isRemoteUrl(url) {
     return /^https?:\/\//i.test(url);
   }
@@ -2649,6 +2752,7 @@ export {
 };
 /* v8 ignore next -- @preserve */
 /* v8 ignore next 3 -- @preserve */
+/* v8 ignore next 5 -- @preserve */
 /* v8 ignore next 2 -- @preserve */
 /* v8 ignore next 9 -- @preserve */
 /* v8 ignore next 4 -- @preserve */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",

package/templates/classic/css/multipage.css

@@ -127,6 +127,32 @@
   align-items: center;
 }
 
+.sidebar-links {
+  display: none;
+}
+
+@media screen and (min-width: 992px) {
+  .sidebar-links {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    padding: 1rem 0;
+    border-top: 1px solid var(--border);
+    margin-top: 1rem;
+  }
+
+  .sidebar-header-link {
+    color: var(--sidebar-text);
+    text-decoration: none;
+    font-size: 0.875rem;
+    padding: 0.25rem 0;
+  }
+
+  .sidebar-header-link:hover {
+    text-decoration: underline;
+  }
+}
+
 .header-logo {
   flex-shrink: 0;
   margin-right: 1.5rem;

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

@@ -5,6 +5,11 @@
         <a class="header-logo" href="/">
           <img src="/logo.svg" alt="logo" />
         </a>
+        {{#if headerLinks}}
+        {{#each headerLinks}}
+        <a class="header-link" href="{{this.url}}" target="_blank" rel="noopener noreferrer">{{#if this.icon}}{{{this.icon}}} {{/if}}{{this.label}}</a>
+        {{/each}}
+        {{/if}}
         <button id="open-sidebar" class="icon menu-btn">
           <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg>
           <span>Menu</span>

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

@@ -36,6 +36,13 @@
         {{/forEach}}
       </ul>
 
+      {{#if headerLinks}}
+      <div class="sidebar-links">
+        {{#each headerLinks}}
+        <a class="sidebar-header-link" href="{{this.url}}" target="_blank" rel="noopener noreferrer">{{#if this.icon}}{{{this.icon}}} {{/if}}{{this.label}}</a>
+        {{/each}}
+      </div>
+      {{/if}}
     </div>
   </section>
 

package/templates/modern/api.hbs

@@ -58,17 +58,21 @@
           {{/each}}
         </div>
         {{/if}}
+        {{#if 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">
               <option value="none">None</option>
-              <option value="apikey">API Key (x-api-key)</option>
-              <option value="bearer">Bearer Token</option>
+              {{#each 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>
           </div>
         </div>
+        {{/if}}
       </section>
 
       {{#each apiSpec.groups}}

package/templates/modern/css/api.css

@@ -351,6 +351,36 @@
   display: none;
 }
 
+.api-auth__cookie-status {
+  font-size: 0.8rem;
+  padding: 0.25rem 0.6rem;
+  border-radius: 6px;
+}
+
+.api-auth__cookie-status--hidden {
+  display: none;
+}
+
+.api-auth__cookie-status--ok {
+  color: #047857;
+  background: rgba(16, 185, 129, 0.15);
+}
+
+[data-theme="light"] .api-auth__cookie-status--ok {
+  color: #065f46;
+  background: rgba(16, 185, 129, 0.12);
+}
+
+.api-auth__cookie-status--warn {
+  color: #fbbf24;
+  background: rgba(251, 191, 36, 0.15);
+}
+
+[data-theme="light"] .api-auth__cookie-status--warn {
+  color: #92400e;
+  background: rgba(251, 191, 36, 0.12);
+}
+
 /* Tag Group */
 .api-group {
   margin-bottom: 40px;

package/templates/modern/css/styles.css

@@ -158,6 +158,17 @@ body {
   }
 }
 
+.cookie-auth-user:empty {
+  display: none;
+}
+
+.cookie-auth-user {
+  font-weight: 500;
+  max-width: 150px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 .cookie-auth-btn--fixed {
   position: fixed;
   bottom: 16px;
@@ -743,14 +754,30 @@ footer {
   color: var(--muted);
 }
 
-footer img {
-  margin-left: 0.5rem;
-  height: 1.5rem;
-  width: auto;
+
+.footer__link {
+  margin: 0 0.35rem;
+  color: var(--muted);
+  text-decoration: none;
+  display: inline-flex;
+  align-items: center;
+}
+
+.footer__link:hover {
+  color: var(--link);
+}
+
+.footer__icon {
+  width: 1rem;
+  height: 1rem;
+}
+
+.footer__bat {
+  width: 1.25rem;
+  height: 1.25rem;
 }
 
 @media (min-width: 992px) {
   footer { height: 4.75rem; }
-  footer img { height: 1.75rem; }
 }
 

package/templates/modern/home.hbs

@@ -44,7 +44,7 @@
   </main>
   {{/if}}
 
-  {{#if cookieAuth}}
+  {{#if cookieAuth.loginUrl}}
   <a href="{{cookieAuth.loginUrl}}" class="cookie-auth-btn cookie-auth-btn--fixed" id="cookie-auth-login">
     <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="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" x2="3" y1="12" y2="12"/></svg>
     <span>Log In</span>

package/templates/modern/includes/footer.hbs

@@ -1,6 +1,14 @@
 <footer>
-  Powered by
-  <a href="https://docula.org/" target="_blank" rel="noopener noreferrer">
-    <img src="https://docula.org/logo_horizontal.png" alt="docula logo" width="140" height="30" />
+  {{#if enableLlmsTxt}}
+  <a href="/llms.txt" class="footer__link">llms.txt</a>
+  {{/if}}
+  {{#if hasFeed}}
+  <a href="/feed.xml" class="footer__link" aria-label="RSS Feed">
+    <svg class="footer__icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><circle cx="6.18" cy="17.82" r="2.18"/><path d="M4 4.44v2.83c7.03 0 12.73 5.7 12.73 12.73h2.83c0-8.59-6.97-15.56-15.56-15.56zm0 5.66v2.83c3.9 0 7.07 3.17 7.07 7.07h2.83c0-5.47-4.43-9.9-9.9-9.9z"/></svg>
+  </a>
+  {{/if}}
+  {{#if enableLlmsTxt}}{{else}}{{#if hasFeed}}{{else}}Built using {{/if}}{{/if}}
+  <a href="https://docula.org/" target="_blank" rel="noopener noreferrer" class="footer__link" aria-label="Docula">
+    <svg class="footer__bat" xmlns="http://www.w3.org/2000/svg" viewBox="70 110 360 205" fill="currentColor"><path d="M420,173c-16.76-18-72.78-36.65-131.59-30.58A160.15,160.15,0,0,0,269,120.55c-3.78,4.52-11.15,9.45-19,9.45s-15.23-4.93-19-9.45a160.15,160.15,0,0,0-19.4,21.83C152.78,136.31,96.76,154.94,80,173c48.86,5.86,79.5,34.09,79.5,72.06,52.37,0,77,28,90.5,59.94C263.54,273,288.13,245,340.5,245,340.5,207,371.14,178.8,420,173Z"/><circle cx="239.19" cy="145.36" r="3.32" fill="#fff"/><circle cx="260.81" cy="145.36" r="3.32" fill="#fff"/></svg>
   </a>
 </footer>

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

@@ -26,12 +26,25 @@
           <span>Changelog</span>
         </a>
         {{/if}}
+        {{#if headerLinks}}
+        {{#each headerLinks}}
+        <a class="header-bottom__item" href="{{this.url}}" target="_blank" rel="noopener noreferrer">
+          {{#if this.icon}}
+          {{{this.icon}}}
+          {{else}}
+          <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="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></svg>
+          {{/if}}
+          <span>{{this.label}}</span>
+        </a>
+        {{/each}}
+        {{/if}}
       </nav>
-      {{#if cookieAuth}}
+      {{#if cookieAuth.loginUrl}}
       <a href="{{cookieAuth.loginUrl}}" class="cookie-auth-btn" id="cookie-auth-login">
         <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="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" x2="3" y1="12" y2="12"/></svg>
         <span>Log In</span>
       </a>
+      <span class="cookie-auth-user" id="cookie-auth-user" style="display:none"></span>
       <button class="cookie-auth-btn" id="cookie-auth-logout" style="display:none">
         <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="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4"/><polyline points="16 17 21 12 16 7"/><line x1="21" x2="9" y1="12" y2="12"/></svg>
         <span>Log Out</span>
@@ -61,11 +74,24 @@
       <span>Changelog</span>
     </a>
     {{/if}}
-    {{#if cookieAuth}}
+    {{#if headerLinks}}
+    {{#each headerLinks}}
+    <a class="mobile-nav__item" href="{{this.url}}" target="_blank" rel="noopener noreferrer">
+      {{#if this.icon}}
+      {{{this.icon}}}
+      {{else}}
+      <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="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></svg>
+      {{/if}}
+      <span>{{this.label}}</span>
+    </a>
+    {{/each}}
+    {{/if}}
+    {{#if cookieAuth.loginUrl}}
     <a class="mobile-nav__item" href="{{cookieAuth.loginUrl}}" id="cookie-auth-login-mobile">
       <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="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" x2="3" y1="12" y2="12"/></svg>
       <span>Log In</span>
     </a>
+    <span class="cookie-auth-user" id="cookie-auth-user-mobile" style="display:none"></span>
     <button class="mobile-nav__item cookie-auth-btn--mobile" id="cookie-auth-logout-mobile" style="display:none">
       <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="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4"/><polyline points="16 17 21 12 16 7"/><line x1="21" x2="9" y1="12" y2="12"/></svg>
       <span>Log Out</span>

package/templates/modern/includes/header.hbs

@@ -6,7 +6,8 @@
 <link rel="icon" href="/favicon.ico">
 <script>
   (function(){
-    var mode = localStorage.getItem('theme') || {{#if themeMode}}'{{themeMode}}'{{else}}'system'{{/if}};
+    window.__doculaThemeKey = 'docula:theme:' + ({{#if siteUrl}}'{{siteUrl}}'{{else}}location.origin{{/if}}).replace(/^https?:\/\//, '');
+    var mode = localStorage.getItem(window.__doculaThemeKey) || {{#if themeMode}}'{{themeMode}}'{{else}}'system'{{/if}};
     var resolved = mode === 'system'
       ? (window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark')
       : mode;

package/templates/modern/includes/scripts.hbs

@@ -9,8 +9,9 @@
 </script>
 <script>
   (function() {
+    var themeKey = window.__doculaThemeKey;
     function getMode() {
-      return localStorage.getItem('theme') || {{#if themeMode}}'{{themeMode}}'{{else}}'system'{{/if}};
+      return localStorage.getItem(themeKey) || {{#if themeMode}}'{{themeMode}}'{{else}}'system'{{/if}};
     }
 
     function resolveTheme(mode) {
@@ -75,7 +76,7 @@
       if (els.toggle) {
         els.toggle.addEventListener('click', function() {
           currentMode = nextMode(currentMode);
-          localStorage.setItem('theme', currentMode);
+          localStorage.setItem(themeKey, currentMode);
           applyTheme(currentMode);
         });
       }
@@ -105,20 +106,38 @@
         return false;
       }
     }
-    function hasCookie() {
-      return document.cookie.split(';').some(function(c) {
+    function getCookieValue() {
+      var match = document.cookie.split(';').find(function(c) {
         return c.trim().startsWith(cookieName + '=');
       });
+      return match ? match.trim().substring(cookieName.length + 1) : null;
+    }
+    function getDisplayName(token) {
+      try {
+        var payload = token.split('.')[1];
+        if (!payload) return null;
+        var json = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
+        var claims = JSON.parse(json);
+        return claims.name || claims.preferred_username || claims.email || null;
+      } catch (e) {
+        return null;
+      }
     }
     function updateAuthUI() {
-      var loggedIn = hasCookie();
+      var token = getCookieValue();
+      var loggedIn = !!token;
+      var displayName = loggedIn ? getDisplayName(token) : null;
       var els = [
-        { login: document.getElementById('cookie-auth-login'), logout: document.getElementById('cookie-auth-logout') },
-        { login: document.getElementById('cookie-auth-login-mobile'), logout: document.getElementById('cookie-auth-logout-mobile') }
+        { login: document.getElementById('cookie-auth-login'), logout: document.getElementById('cookie-auth-logout'), user: document.getElementById('cookie-auth-user') },
+        { login: document.getElementById('cookie-auth-login-mobile'), logout: document.getElementById('cookie-auth-logout-mobile'), user: document.getElementById('cookie-auth-user-mobile') }
       ];
       els.forEach(function(pair) {
         if (pair.login) pair.login.style.display = loggedIn ? 'none' : '';
         if (pair.logout) pair.logout.style.display = loggedIn ? '' : 'none';
+        if (pair.user) {
+          pair.user.textContent = displayName || '';
+          pair.user.style.display = (loggedIn && displayName) ? '' : 'none';
+        }
       });
     }
     document.addEventListener('DOMContentLoaded', function() {

package/templates/modern/js/api.js

@@ -104,19 +104,52 @@ document.addEventListener('DOMContentLoaded', function() {
     group.classList.add('api-sidebar__group--collapsed');
   });
 
-  // Auth type selector: show/hide value input
+  // 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');
   if (authTypeSelect && authValueInput) {
-    authTypeSelect.addEventListener('change', function() {
-      if (this.value === 'none') {
+    function getSelectedSchemeData() {
+      var option = authTypeSelect.options[authTypeSelect.selectedIndex];
+      return {
+        key: option.value,
+        type: option.getAttribute('data-scheme-type'),
+        scheme: option.getAttribute('data-scheme-scheme'),
+        name: option.getAttribute('data-scheme-name'),
+        inLocation: option.getAttribute('data-scheme-in')
+      };
+    }
+    function updateAuthUI() {
+      var data = getSelectedSchemeData();
+      if (data.key === 'none') {
+        authValueInput.classList.add('api-auth__value--hidden');
+        authValueInput.value = '';
+        if (cookieStatusEl) cookieStatusEl.classList.add('api-auth__cookie-status--hidden');
+      } else if (data.type === 'apiKey' && data.inLocation === 'cookie') {
         authValueInput.classList.add('api-auth__value--hidden');
         authValueInput.value = '';
+        if (cookieStatusEl) {
+          cookieStatusEl.classList.remove('api-auth__cookie-status--hidden');
+          var configEl = document.getElementById('cookie-auth-config');
+          var cookieName = configEl ? configEl.getAttribute('data-cookie-name') : (data.name || 'token');
+          var hasCookie = document.cookie.split(';').some(function(c) { return c.trim().startsWith(cookieName + '='); });
+          cookieStatusEl.textContent = hasCookie ? 'Logged in' : 'Not logged in — use Login button above';
+          cookieStatusEl.className = 'api-auth__cookie-status' + (hasCookie ? ' api-auth__cookie-status--ok' : ' api-auth__cookie-status--warn');
+        }
       } else {
         authValueInput.classList.remove('api-auth__value--hidden');
-        authValueInput.placeholder = this.value === 'apikey' ? 'Enter API key...' : 'Enter token...';
+        if (data.type === 'apiKey') {
+          authValueInput.placeholder = 'Enter API key...';
+        } else if (data.scheme === 'bearer') {
+          authValueInput.placeholder = 'Enter bearer token...';
+        } else {
+          authValueInput.placeholder = 'Enter value...';
+        }
+        if (cookieStatusEl) cookieStatusEl.classList.add('api-auth__cookie-status--hidden');
       }
-    });
+    }
+    authTypeSelect.addEventListener('change', updateAuthUI);
+    updateAuthUI();
   }
 
   // Helper: expand an operation and its corresponding sidebar group
@@ -226,15 +259,28 @@ document.addEventListener('DOMContentLoaded', function() {
         if (value) headers[name] = value;
       });
 
-      // Inject global auth header
+      // Inject global auth header from selected security scheme
       var authType = document.getElementById('api-auth-type');
       var authValue = document.getElementById('api-auth-value');
-      if (authType && authValue && authValue.value.trim()) {
-        var authVal = authValue.value.trim();
-        if (authType.value === 'apikey') {
-          headers['x-api-key'] = authVal;
-        } else if (authType.value === 'bearer') {
-          headers['Authorization'] = 'Bearer ' + authVal;
+      var useCookieAuth = false;
+      if (authType && authType.value !== 'none') {
+        var authOption = authType.options[authType.selectedIndex];
+        var schemeType = authOption.getAttribute('data-scheme-type');
+        var schemeName = authOption.getAttribute('data-scheme-name');
+        var schemeIn = authOption.getAttribute('data-scheme-in');
+        var schemeScheme = authOption.getAttribute('data-scheme-scheme');
+        if (schemeType === 'apiKey' && schemeIn === 'cookie') {
+          useCookieAuth = true;
+        } else if (authValue && authValue.value.trim()) {
+          var authVal = authValue.value.trim();
+          if (schemeType === 'apiKey' && schemeIn === 'header' && schemeName) {
+            headers[schemeName] = authVal;
+          } else if (schemeType === 'http' && schemeScheme === 'bearer') {
+            headers['Authorization'] = 'Bearer ' + authVal;
+          } else if (schemeType === 'apiKey' && schemeIn === 'query' && schemeName) {
+            queryParts.push(encodeURIComponent(schemeName) + '=' + encodeURIComponent(authVal));
+            queryString = '?' + queryParts.join('&');
+          }
         }
       }
 
@@ -247,6 +293,9 @@ document.addEventListener('DOMContentLoaded', function() {
 
       var url = baseUrl + path + queryString;
       var fetchOptions = { method: method, headers: headers };
+      if (useCookieAuth) {
+        fetchOptions.credentials = 'include';
+      }
       if (body && method !== 'GET' && method !== 'HEAD') {
         fetchOptions.body = body;
       }