docula 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -17,7 +17,7 @@
   },
   "author": "Jared Wray <me@jaredwray.com>",
   "engines": {
-    "node": "^22.18.0 || >=24.0.0"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "license": "MIT",
   "keywords": [
@@ -40,32 +40,34 @@
     "docula": "./bin/docula.js"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.77",
-    "@ai-sdk/google": "^3.0.72",
-    "@ai-sdk/openai": "^3.0.63",
-    "@cacheable/net": "^2.0.7",
-    "ai": "^6.0.178",
+    "@ai-sdk/anthropic": "^3.0.83",
+    "@ai-sdk/google": "^3.0.81",
+    "@ai-sdk/openai": "^3.0.70",
+    "@cacheable/net": "^2.0.8",
+    "ai": "^6.0.202",
     "colorette": "^2.0.20",
-    "ecto": "^4.8.5",
-    "hashery": "^2.0.0",
+    "ecto": "^4.8.7",
+    "hashery": "^3.0.0",
+    "ipaddr.js": "2.4.0",
     "jiti": "^2.7.0",
     "serve-handler": "^6.1.7",
+    "undici": "8.4.1",
     "update-notifier": "^7.3.1",
     "writr": "^6.1.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
+    "@biomejs/biome": "^2.4.16",
     "@playwright/test": "^1.60.0",
-    "@types/node": "^24.12.4",
+    "@types/node": "^24.13.2",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@vitest/coverage-v8": "^4.1.8",
     "dotenv": "^17.4.2",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.22.0",
-    "tsx": "^4.21.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   },
   "files": [
     "dist",

package/templates/classic/includes/body-scripts.hbs

@@ -1,7 +1,7 @@
 {{#if googleTagManager}}
 {{#unless isGtag}}
 <!-- Google Tag Manager (noscript) -->
-<noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{googleTagManager}}"
+<noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{googleTagManager}}{{{googleTagManagerParams}}}"
 height="0" width="0" style="display:none !important;visibility:hidden !important"></iframe></noscript>
 <!-- End Google Tag Manager (noscript) -->
 {{/unless}}

package/templates/classic/includes/header.hbs

@@ -8,7 +8,7 @@
 <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
 new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
 j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
-'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+'https://www.googletagmanager.com/gtm.js?id='+i+dl+'{{{googleTagManagerParams}}}';f.parentNode.insertBefore(j,f);
 })(window,document,'script','dataLayer','{{googleTagManager}}');</script>
 <!-- End Google Tag Manager -->
 {{/if}}

package/templates/modern/css/styles.css

@@ -221,16 +221,27 @@ body {
 }
 
 .search-button {
-  border: none;
-  border-radius: 4px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
   padding: 0px 10px;
-  height: 30px;
-  width: 150px;
+  height: 32px;
+  width: 200px;
   display: flex;
   align-items: center;
-  gap: 6px;
+  gap: 8px;
   color: var(--muted-fg);
   background: var(--surface);
+  cursor: pointer;
+  transition: border-color 0.15s ease, color 0.15s ease;
+}
+
+.search-button:hover {
+  border-color: var(--border-hover);
+  color: var(--fg);
+}
+
+.search-button svg {
+  flex-shrink: 0;
 }
 
 .search-button__text {
@@ -241,9 +252,254 @@ body {
 }
 
 .search-button__shortcut {
-  font-size: 11px;
+  font-size: 12px;
   font-weight: 500;
-  opacity: 0.6;
+  padding: 1px 6px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  opacity: 0.7;
+}
+
+/* Search modal */
+body.search-open {
+  overflow: hidden;
+}
+
+.search-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 12vh 16px 16px;
+}
+
+.search-modal[hidden] {
+  display: none;
+}
+
+.search-modal__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(2px);
+}
+
+.search-modal__panel {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: min(680px, 100%);
+  max-height: 76vh;
+  background: var(--bg);
+  border: 1px solid var(--border-strong);
+  border-radius: 12px;
+  box-shadow: 0 16px 48px rgba(0, 0, 0, 0.5);
+  overflow: hidden;
+}
+
+.search-modal__panel:focus-within {
+  border-color: var(--link);
+}
+
+.search-modal__header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 14px 16px;
+  border-bottom: 1px solid var(--border);
+}
+
+.search-modal__icon {
+  color: var(--muted-fg);
+  flex-shrink: 0;
+}
+
+.search-modal__input {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  background: transparent;
+  color: var(--fg);
+  font-size: 16px;
+  font-family: inherit;
+  outline: none;
+}
+
+.search-modal__input::placeholder {
+  color: var(--muted-fg);
+}
+
+.search-modal__input::-webkit-search-cancel-button {
+  display: none;
+}
+
+.search-modal__clear {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--muted-fg);
+  cursor: pointer;
+  padding: 2px;
+  border-radius: 4px;
+}
+
+.search-modal__clear:hover {
+  color: var(--fg);
+  background: var(--surface-hover);
+}
+
+.search-modal__clear[hidden] {
+  display: none;
+}
+
+.search-modal__body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px;
+}
+
+.search-results {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.search-results[hidden] {
+  display: none;
+}
+
+.search-result__link {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  color: var(--fg);
+  text-decoration: none;
+}
+
+.search-result--active .search-result__link {
+  background: var(--surface-hover);
+  border-color: var(--border-strong);
+}
+
+.search-result__icon {
+  display: flex;
+  align-items: center;
+  color: var(--muted-fg);
+  margin-top: 2px;
+  flex-shrink: 0;
+}
+
+.search-result--active .search-result__icon {
+  color: var(--link);
+}
+
+.search-result__content {
+  min-width: 0;
+  flex: 1;
+}
+
+.search-result__breadcrumb {
+  font-size: 12px;
+  color: var(--muted-fg);
+  margin-bottom: 2px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.search-result__title {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.search-result__text {
+  font-size: 13px;
+  color: var(--muted-fg);
+  margin-top: 3px;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.search-result__mark {
+  background: transparent;
+  color: var(--link);
+  font-weight: 700;
+  padding: 0;
+}
+
+.search-modal__empty,
+.search-modal__initial {
+  padding: 28px 16px;
+  text-align: center;
+  color: var(--muted-fg);
+  font-size: 14px;
+}
+
+.search-modal__empty[hidden],
+.search-modal__initial[hidden] {
+  display: none;
+}
+
+.search-modal__footer {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  padding: 10px 16px;
+  border-top: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--muted-fg);
+}
+
+.search-modal__hint {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.search-modal__kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 4px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface);
+  font-size: 11px;
+  font-family: inherit;
+}
+
+@media (max-width: 720px) {
+  .search-button {
+    width: auto;
+  }
+
+  .search-button__text,
+  .search-button__shortcut {
+    display: none;
+  }
+
+  .search-modal {
+    padding: 8vh 10px 10px;
+  }
+
+  .search-modal__footer {
+    display: none;
+  }
 }
 
 .content {

package/templates/modern/includes/body-scripts.hbs

@@ -1,7 +1,7 @@
 {{#if googleTagManager}}
 {{#unless isGtag}}
 <!-- Google Tag Manager (noscript) -->
-<noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{googleTagManager}}"
+<noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{googleTagManager}}{{{googleTagManagerParams}}}"
 height="0" width="0" style="display:none !important;visibility:hidden !important"></iframe></noscript>
 <!-- End Google Tag Manager (noscript) -->
 {{/unless}}

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

@@ -40,6 +40,13 @@
         {{/if}}
       </nav>
       <div class="header-actions">
+        {{#if enableSearch}}
+        <button class="search-button" id="search-button" type="button" aria-label="Search" aria-keyshortcuts="Meta+K Control+K">
+          <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"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+          <span class="search-button__text">Search</span>
+          <span class="search-button__shortcut">⌘K</span>
+        </button>
+        {{/if}}
         {{#if cookieAuth.loginUrl}}
         <div class="cookie-auth">
           <a href="{{cookieAuth.loginUrl}}" class="cookie-auth-btn" id="cookie-auth-login">
@@ -119,3 +126,4 @@
   <div class="mobile-sidebar__docs" id="mobile-sidebar-docs"></div>
 </aside>
 <div class="sidebar-backdrop" id="sidebar-backdrop"></div>
+{{> search }}

package/templates/modern/includes/header.hbs

@@ -8,7 +8,7 @@
 <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
 new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
 j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
-'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+'https://www.googletagmanager.com/gtm.js?id='+i+dl+'{{{googleTagManagerParams}}}';f.parentNode.insertBefore(j,f);
 })(window,document,'script','dataLayer','{{googleTagManager}}');</script>
 <!-- End Google Tag Manager -->
 {{/if}}

package/templates/modern/includes/scripts.hbs

@@ -265,23 +265,34 @@
       });
     }
 
-    // Active header nav link highlighting
-    const navLinks = document.querySelectorAll('.header-bottom__item');
-    navLinks.forEach((link) => {
-      const href = link.getAttribute('href');
-      if (currentPath.startsWith(href)) {
-        link.classList.add('header-bottom__item--active');
-      }
-    });
-
-    // Active mobile nav link highlighting
-    const mobileNavLinks = document.querySelectorAll('.mobile-nav__item');
-    mobileNavLinks.forEach((link) => {
-      const href = link.getAttribute('href');
-      if (currentPath.startsWith(href)) {
-        link.classList.add('mobile-nav__item--active');
-      }
-    });
+    // Active nav link highlighting (header + mobile). Highlight only the
+    // single most-specific link: the one whose path is the longest prefix of
+    // the current path. A plain startsWith() check lights up every link whose
+    // path merely prefixes the current one, so when the site is embedded under
+    // a base path (e.g. served at /developer with docs at that root) the
+    // Documentation link — whose path is a prefix of every page — would stay
+    // highlighted everywhere. Trailing slashes are normalized so matches stop
+    // at a path boundary. We read the anchor's resolved origin/pathname so
+    // absolute, relative, and same-origin hrefs all work, while cross-origin
+    // links and non-anchor items (e.g. the mobile logout button) are skipped.
+    const withTrailingSlash = (p) => (p.endsWith('/') ? p : p + '/');
+    const here = withTrailingSlash(currentPath);
+    const markActiveNav = (selector, activeClass) => {
+      let bestLink = null;
+      let bestLength = -1;
+      document.querySelectorAll(selector).forEach((link) => {
+        // Only same-origin anchors can match the current pathname.
+        if (!link.href || link.origin !== window.location.origin) return;
+        const base = withTrailingSlash(link.pathname);
+        if (here.startsWith(base) && base.length > bestLength) {
+          bestLink = link;
+          bestLength = base.length;
+        }
+      });
+      if (bestLink) bestLink.classList.add(activeClass);
+    };
+    markActiveNav('.header-bottom__item', 'header-bottom__item--active');
+    markActiveNav('.mobile-nav__item', 'mobile-nav__item--active');
 
     // TOC extraction: move the inline TOC into the right sidebar and hide the original
     const tocHeading = document.getElementById('table-of-contents');

package/templates/modern/includes/search.hbs

@@ -0,0 +1,46 @@
+{{#if enableSearch}}
+<div class="search-modal" id="search-modal" hidden>
+  <div class="search-modal__backdrop" data-search-close></div>
+  <div class="search-modal__panel" role="dialog" aria-modal="true" aria-label="Search">
+    <div class="search-modal__header">
+      <svg class="search-modal__icon" 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"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+      <input
+        type="search"
+        id="search-input"
+        class="search-modal__input"
+        placeholder="Search"
+        autocomplete="off"
+        autocorrect="off"
+        autocapitalize="off"
+        spellcheck="false"
+        aria-label="Search"
+        aria-controls="search-results"
+        aria-activedescendant=""
+        role="combobox"
+        aria-expanded="true"
+      />
+      <button class="search-modal__clear" id="search-clear" type="button" aria-label="Clear search" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+      </button>
+    </div>
+    <div class="search-modal__body">
+      <ul class="search-results" id="search-results" role="listbox" aria-label="Search results"></ul>
+      <div class="search-modal__empty" id="search-empty" hidden>
+        No results for "<span class="search-modal__empty-query" id="search-empty-query"></span>"
+      </div>
+      <div class="search-modal__initial" id="search-initial">
+        Type to search the documentation.
+      </div>
+    </div>
+    <div class="search-modal__footer">
+      <span class="search-modal__hint"><kbd class="search-modal__kbd">↑</kbd><kbd class="search-modal__kbd">↓</kbd> to navigate</span>
+      <span class="search-modal__hint"><kbd class="search-modal__kbd">↵</kbd> to select</span>
+      <span class="search-modal__hint"><kbd class="search-modal__kbd">esc</kbd> to close</span>
+    </div>
+  </div>
+</div>
+<script>
+  window.__doculaSearch = { indexUrl: "{{baseUrl}}/search-index.json" };
+</script>
+<script src="{{baseUrl}}/js/search.js" defer></script>
+{{/if}}