docula 1.2.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.2.0",
+  "version": "1.6.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -44,6 +44,7 @@
     "colorette": "^2.0.20",
     "ecto": "^4.8.2",
     "feed": "^5.2.0",
+    "hashery": "^1.5.0",
     "jiti": "^2.6.1",
     "serve-handler": "^6.1.6",
     "update-notifier": "^7.3.1",
@@ -78,10 +79,13 @@
     "test": "pnpm lint && vitest run --coverage",
     "test:ci": "pnpm lint:ci && vitest run --coverage",
     "test:e2e": "pnpm build && playwright test",
+    "docula:help": "pnpm build && node bin/docula.js help",
     "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 serve -s ./site -o ./site/dist -w -p 3333",
+    "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: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",
     "website:changelog": "node bin/docula.js serve -s ./test/fixtures/changelog-site --watch --clean"
   }

package/templates/classic/changelog.hbs

@@ -67,11 +67,32 @@
           {{/if}}
         </div>
         <span class="changelog-entry-date">{{entry.formattedDate}}</span>
-        <div class="changelog-entry-body">
-          {{{entry.generatedHtml}}}
+        {{#if entry.previewImage}}
+        <div class="changelog-entry-image">
+          <img src="{{entry.previewImage}}" alt="{{entry.title}}" />
         </div>
+        {{/if}}
+        <div class="changelog-entry-preview">
+          {{{entry.preview}}}
+        </div>
+        <span class="changelog-read-more">Read more &rarr;</span>
       </div>
       {{/each}}
+      {{#if hasPagination}}
+      <nav class="changelog-pagination">
+        {{#if hasPrevPage}}
+        <a class="changelog-pagination-link" href="{{prevPageUrl}}">&larr; Newer</a>
+        {{else}}
+        <span class="changelog-pagination-link changelog-pagination-disabled">&larr; Newer</span>
+        {{/if}}
+        <span class="changelog-pagination-info">Page {{currentPage}} of {{totalPages}}</span>
+        {{#if hasNextPage}}
+        <a class="changelog-pagination-link" href="{{nextPageUrl}}">Older &rarr;</a>
+        {{else}}
+        <span class="changelog-pagination-link changelog-pagination-disabled">Older &rarr;</span>
+        {{/if}}
+      </nav>
+      {{/if}}
       {{/if}}
     </div>
   </main>

package/templates/classic/css/base.css

@@ -224,6 +224,7 @@ hr {
 
 /* Changelog */
 .changelog-entry {
+  position: relative;
   overflow: hidden;
   width: 100%;
   line-break: anywhere;
@@ -366,6 +367,80 @@ h1.changelog-entry-title {
   border-bottom: none;
 }
 
+.changelog-entry-title::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+}
+
+.changelog-entry:hover {
+  cursor: pointer;
+}
+
+.changelog-entry-image {
+  margin-top: 0.75rem;
+}
+
+.changelog-entry-image img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.5rem;
+}
+
+.changelog-entry-preview {
+  margin-top: 0.75rem;
+  font-size: 0.9375rem;
+  line-height: 1.6;
+  overflow-wrap: break-word;
+  color: var(--color-secondary-dark);
+}
+
+.changelog-read-more {
+  display: inline-block;
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: var(--color-primary);
+}
+
+.changelog-entry:hover .changelog-read-more {
+  text-decoration: underline;
+}
+
+.changelog-pagination {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 1rem;
+  padding: 1.5rem 0;
+  margin-top: 0.75rem;
+  border-top: 1px solid var(--color-border);
+}
+
+.changelog-pagination-link {
+  font-size: 0.875rem;
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+.changelog-pagination-link:hover {
+  text-decoration: underline;
+}
+
+.changelog-pagination-disabled {
+  color: var(--color-secondary-dark);
+  cursor: default;
+}
+
+.changelog-pagination-disabled:hover {
+  text-decoration: none;
+}
+
+.changelog-pagination-info {
+  font-size: 0.875rem;
+  color: var(--color-secondary-dark);
+}
+
 .github-corner {
   fill: var(--color-primary) !important;
 }

package/templates/classic/css/variables.css

@@ -0,0 +1,30 @@
+:root {
+  --font-family: "Open Sans", sans-serif;
+
+  --color-primary: #322d3c;
+  --color-secondary: #8cdc00;
+  --color-secondary-dark: #8cdc00;
+  --color-text: #322d3c;
+
+  --background: #ffffff;
+  --home-background: #ffffff;
+  --header-background: #ffffff;
+
+  --sidebar-background: #ffffff;
+  --sidebar-text: #322d3c;
+  --sidebar-text-active: #7d7887;
+
+  --border: rgba(238, 238, 245, 1);
+
+  --background-search-highlight: var(--color-secondary-dark);
+  --color-search-highlight: #ffffff;
+  --search-input-background: var(--header-background);
+
+  --code: rgba(238, 238, 245, 1);
+
+  --pagefind-ui-text: var(--color-text) !important;
+  --pagefind-ui-font: var(--font-family) !important;
+  --pagefind-ui-background: var(--background) !important;
+  --pagefind-ui-border: var(--border) !important;
+  --pagefind-ui-scale: 0.9 !important;
+}

package/templates/classic/home.hbs

@@ -56,11 +56,18 @@
   {{#if content}}
   {{> singlepage/hero }}
   {{> singlepage/content }}
+  {{#if hasApi}}
+  <div class="home-actions">
+    {{> multipage/api-reference }}
+  </div>
+  {{/if}}
   {{else}}
   <main class="home">
     {{> multipage/hero }}
     <div class="home-actions">
+      {{#if hasDocuments}}
       {{> multipage/documentation }}
+      {{/if}}
       {{#if hasApi}}
       {{> multipage/api-reference }}
       {{/if}}

package/templates/modern/api.hbs

@@ -3,7 +3,7 @@
 
 <head>
   {{> header }}
-  <link rel="stylesheet" href="/css/api.css">
+  <link rel="stylesheet" href="{{baseUrl}}/css/api.css">
   <title>API Reference - {{ siteTitle }}</title>
   <meta name="description" content="API Reference for {{ siteTitle }}" />
 </head>
@@ -70,6 +70,43 @@
             </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>
           </div>
         </div>
         {{/if}}
@@ -213,7 +250,7 @@
   {{> footer }}
   {{> scripts }}
 
-  <script src="/js/api.js"></script>
+  <script src="{{baseUrl}}/js/api.js"></script>
 </body>
 
 </html>

package/templates/modern/changelog-entry.hbs

@@ -12,7 +12,7 @@
     <main class="versions-container">
       <div class="versions-content">
         <div class="changelog-entry-nav">
-          <a href="/changelog/">&larr; Back to Changelog</a>
+          <a href="{{changelogUrl}}/">&larr; Back to Changelog</a>
         </div>
         <div class="changelog-entry changelog-entry-single">
           <div class="changelog-entry-header">

package/templates/modern/changelog.hbs

@@ -16,17 +16,38 @@
         {{#each entries as |entry|}}
         <div class="changelog-entry">
           <div class="changelog-entry-header">
-            <a class="changelog-entry-title" href="/changelog/{{entry.slug}}/">{{entry.title}}</a>
+            <a class="changelog-entry-title" href="{{changelogUrl}}/{{entry.slug}}/">{{entry.title}}</a>
             {{#if entry.tag}}
             <span class="changelog-tag changelog-tag-{{entry.tagClass}}">{{entry.tag}}</span>
             {{/if}}
           </div>
           <span class="changelog-entry-date">{{entry.formattedDate}}</span>
-          <div class="changelog-entry-body">
-            {{{entry.generatedHtml}}}
+          {{#if entry.previewImage}}
+          <div class="changelog-entry-image">
+            <img src="{{entry.previewImage}}" alt="{{entry.title}}" />
           </div>
+          {{/if}}
+          <div class="changelog-entry-preview">
+            {{{entry.preview}}}
+          </div>
+          <span class="changelog-read-more">Read more &rarr;</span>
         </div>
         {{/each}}
+        {{#if hasPagination}}
+        <nav class="changelog-pagination">
+          {{#if hasPrevPage}}
+          <a class="changelog-pagination-link" href="{{prevPageUrl}}">&larr; Newer</a>
+          {{else}}
+          <span class="changelog-pagination-link changelog-pagination-disabled">&larr; Newer</span>
+          {{/if}}
+          <span class="changelog-pagination-info">Page {{currentPage}} of {{totalPages}}</span>
+          {{#if hasNextPage}}
+          <a class="changelog-pagination-link" href="{{nextPageUrl}}">Older &rarr;</a>
+          {{else}}
+          <span class="changelog-pagination-link changelog-pagination-disabled">Older &rarr;</span>
+          {{/if}}
+        </nav>
+        {{/if}}
         {{/if}}
       </div>
     </main>

package/templates/modern/css/styles.css

@@ -1,36 +1,3 @@
-:root {
-  --bg: #121212;
-  --fg: #ffffff;
-  --border: rgba(255, 255, 255, 0.1);
-  --border-strong: rgba(255, 255, 255, 0.2);
-  --border-hover: rgba(255, 255, 255, 0.4);
-  --surface: #262626;
-  --surface-hover: rgba(255, 255, 255, 0.1);
-  --muted: #c5cdd3;
-  --muted-fg: rgba(255, 255, 255, 0.65);
-  --code-bg: rgba(255, 255, 255, 0.075);
-  --pre-bg: rgba(255, 255, 255, 0.05);
-  --link: #6ea8fe;
-  --scrollbar: rgba(255, 255, 255, 0.2);
-  --header-height: 81px;
-}
-
-[data-theme="light"] {
-  --bg: #ffffff;
-  --fg: #1a1a1a;
-  --border: rgba(0, 0, 0, 0.1);
-  --border-strong: rgba(0, 0, 0, 0.15);
-  --border-hover: rgba(0, 0, 0, 0.3);
-  --surface: #f0f0f0;
-  --surface-hover: rgba(0, 0, 0, 0.06);
-  --muted: #6b7280;
-  --muted-fg: rgba(0, 0, 0, 0.5);
-  --code-bg: rgba(0, 0, 0, 0.05);
-  --pre-bg: rgba(0, 0, 0, 0.03);
-  --link: #0969da;
-  --scrollbar: rgba(0, 0, 0, 0.2);
-}
-
 html {
   scroll-behavior: smooth;
   overflow-x: clip;
@@ -107,7 +74,6 @@ body {
 }
 
 .theme-button {
-  margin-left: auto;
   border: 1px solid transparent;
   border-radius: 4px;
   padding: 0px 5px;
@@ -120,6 +86,13 @@ body {
   }
 }
 
+.header-actions {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
 .theme-button--fixed {
   position: fixed;
   bottom: 16px;
@@ -137,6 +110,22 @@ body {
   display: none;
 }
 
+.cookie-auth {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+#cookie-auth-logout,
+#cookie-auth-logout-mobile,
+.cookie-auth-user { display: none; }
+
+.docula-auth-logged-in #cookie-auth-login,
+.docula-auth-logged-in #cookie-auth-login-mobile { display: none; }
+.docula-auth-logged-in #cookie-auth-logout,
+.docula-auth-logged-in #cookie-auth-logout-mobile { display: flex; }
+.docula-auth-logged-in .cookie-auth-user { display: inline; }
+
 .cookie-auth-btn {
   border: 1px solid var(--border);
   border-radius: 4px;
@@ -159,7 +148,7 @@ body {
 }
 
 .cookie-auth-user:empty {
-  display: none;
+  display: none !important;
 }
 
 .cookie-auth-user {
@@ -269,7 +258,6 @@ body {
   min-width: 288px;
   display: flex;
   flex-direction: column;
-  gap: 12px;
   position: sticky;
   top: var(--header-height);
   max-height: calc(100vh - var(--header-height));
@@ -277,6 +265,18 @@ body {
   align-self: flex-start;
 }
 
+.nav-sidebar__section {
+  margin-top: 1px;
+}
+
+.nav-sidebar__section:has(.nav-sidebar__title) {
+  margin-top: 12px;
+}
+
+.nav-sidebar__section:first-child {
+  margin-top: 0;
+}
+
 .nav-sidebar__title {
   font-size: 12px;
   font-weight: 600;
@@ -684,6 +684,7 @@ body {
 }
 
 .changelog-entry {
+  position: relative;
   border-bottom: 1px solid var(--border);
   padding: 20px 0;
 }
@@ -744,6 +745,88 @@ body {
   color: #92400e;
 }
 
+.changelog-entry-title::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+}
+
+.changelog-entry:hover {
+  cursor: pointer;
+}
+
+.changelog-entry-single .changelog-entry-title::after {
+  display: none;
+}
+
+.changelog-entry-single:hover {
+  cursor: default;
+}
+
+.changelog-entry-image {
+  margin-top: 12px;
+}
+
+.changelog-entry-image img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+
+.changelog-entry-preview {
+  margin-top: 12px;
+  font-size: 15px;
+  line-height: 1.6;
+  overflow-wrap: break-word;
+  color: var(--muted);
+}
+
+.changelog-read-more {
+  display: inline-block;
+  margin-top: 8px;
+  font-size: 14px;
+  color: var(--muted);
+}
+
+.changelog-entry:hover .changelog-read-more {
+  color: var(--fg);
+}
+
+.changelog-pagination {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 16px;
+  padding: 24px 0;
+  margin-top: 12px;
+  border-top: 1px solid var(--border);
+}
+
+.changelog-pagination-link {
+  font-size: 14px;
+  color: var(--muted);
+  text-decoration: none;
+}
+
+.changelog-pagination-link:hover {
+  color: var(--fg);
+}
+
+.changelog-pagination-disabled {
+  color: var(--muted);
+  cursor: default;
+}
+
+.changelog-pagination-disabled:hover {
+  text-decoration: none;
+}
+
+.changelog-pagination-info {
+  font-size: 14px;
+  color: var(--muted);
+}
+
 /* Footer */
 footer {
   height: 4rem;
@@ -777,6 +860,11 @@ footer {
   height: 1.25rem;
 }
 
+.footer__updated {
+  font-size: 13px;
+  color: var(--muted);
+}
+
 @media (min-width: 992px) {
   footer { height: 4.75rem; }
 }

package/templates/modern/css/variables.css

@@ -0,0 +1,32 @@
+:root {
+  --bg: #121212;
+  --fg: #ffffff;
+  --border: rgba(255, 255, 255, 0.1);
+  --border-strong: rgba(255, 255, 255, 0.2);
+  --border-hover: rgba(255, 255, 255, 0.4);
+  --surface: #262626;
+  --surface-hover: rgba(255, 255, 255, 0.1);
+  --muted: #c5cdd3;
+  --muted-fg: rgba(255, 255, 255, 0.65);
+  --code-bg: rgba(255, 255, 255, 0.075);
+  --pre-bg: rgba(255, 255, 255, 0.05);
+  --link: #6ea8fe;
+  --scrollbar: rgba(255, 255, 255, 0.2);
+  --header-height: 81px;
+}
+
+[data-theme="light"] {
+  --bg: #ffffff;
+  --fg: #1a1a1a;
+  --border: rgba(0, 0, 0, 0.1);
+  --border-strong: rgba(0, 0, 0, 0.15);
+  --border-hover: rgba(0, 0, 0, 0.3);
+  --surface: #f0f0f0;
+  --surface-hover: rgba(0, 0, 0, 0.06);
+  --muted: #6b7280;
+  --muted-fg: rgba(0, 0, 0, 0.5);
+  --code-bg: rgba(0, 0, 0, 0.05);
+  --pre-bg: rgba(0, 0, 0, 0.03);
+  --link: #0969da;
+  --scrollbar: rgba(0, 0, 0, 0.2);
+}

package/templates/modern/home.hbs

@@ -3,7 +3,7 @@
 
 <head>
   {{> header }}
-  <link rel="stylesheet" href="/css/home.css">
+  <link rel="stylesheet" href="{{baseUrl}}/css/home.css">
   <title>{{ siteTitle }}</title>
 </head>
 
@@ -24,18 +24,25 @@
 
   {{#if content}}
   <header class="home-hero">
-    <img src="/logo.svg" alt="logo" />
+    <img src="{{baseUrl}}/logo.svg" alt="logo" />
     {{#if announcement}}
     <div class="announcement">{{{announcement}}}</div>
     {{/if}}
   </header>
   <div class="home-content">{{{content}}}</div>
+  {{#if hasApi}}
+  <div class="home-actions">
+    {{> api-reference }}
+  </div>
+  {{/if}}
   {{> home }}
   {{else}}
   <main class="home">
     {{> hero }}
     <div class="home-actions">
+      {{#if hasDocuments}}
       {{> documentation }}
+      {{/if}}
       {{#if hasApi}}
       {{> api-reference }}
       {{/if}}
@@ -49,7 +56,7 @@
     <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>
-  <button class="cookie-auth-btn cookie-auth-btn--fixed" id="cookie-auth-logout" style="display:none">
+  <button class="cookie-auth-btn cookie-auth-btn--fixed" id="cookie-auth-logout">
     <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>
   </button>

package/templates/modern/includes/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/modern/includes/documentation.hbs

@@ -1 +1 @@
-<a href="/docs" class="home-docs-button">Documentation</a>
+<a href="{{docsUrl}}" class="home-docs-button">Documentation</a>

package/templates/modern/includes/footer.hbs

@@ -1,9 +1,9 @@
 <footer>
   {{#if enableLlmsTxt}}
-  <a href="/llms.txt" class="footer__link">llms.txt</a>
+  <a href="{{baseUrl}}/llms.txt" class="footer__link">llms.txt</a>
   {{/if}}
   {{#if hasFeed}}
-  <a href="/feed.xml" class="footer__link" aria-label="RSS Feed">
+  <a href="{{baseUrl}}/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}}
@@ -11,4 +11,7 @@
   <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>
+  {{#if lastModified}}
+  <span class="footer__updated">updated: {{lastModified}}</span>
+  {{/if}}
 </footer>