@docmd/ui 0.4.11 → 0.5.1

package/README.md

@@ -7,7 +7,7 @@ Contains:
 - **Assets:** Core CSS and JavaScript.
 - **Icons:** SVG icon sets.
 
-## The docmd Ecosystem
+## The `docmd` Ecosystem
 
 `docmd` is a modular system. Here are the official packages:
 
@@ -22,6 +22,7 @@ Contains:
 
 **Plugins**
 *   [**@docmd/plugin-search**](https://www.npmjs.com/package/@docmd/plugin-search) - Offline full-text search.
+*   [**@docmd/plugin-pwa**](https://www.npmjs.com/package/@docmd/plugin-pwa) - Progressive Web App support.
 *   [**@docmd/plugin-mermaid**](https://www.npmjs.com/package/@docmd/plugin-mermaid) - Diagrams and flowcharts.
 *   [**@docmd/plugin-seo**](https://www.npmjs.com/package/@docmd/plugin-seo) - Meta tags and Open Graph data.
 *   [**@docmd/plugin-sitemap**](https://www.npmjs.com/package/@docmd/plugin-sitemap) - Automatic sitemap generation.

package/assets/css/docmd-main.css

@@ -176,18 +176,19 @@ a:any-link {
 .sidebar {
     display: flex;
     flex-direction: column;
-    width: 260px;
+    width: var(--sidebar-width);
     background-color: var(--sidebar-bg);
     color: var(--sidebar-text);
-    padding: .5em .25em .5em .5em;
     border-right: 1px solid var(--border-color);
     height: 100vh;
     position: fixed;
+    padding: .5em .25em .5em .5em;
     top: 0;
     left: 0;
-    overflow-y: auto;
+    overflow: hidden;
     box-sizing: border-box;
-    flex-shrink: 0
+    flex-shrink: 0;
+    z-index: 100;
 }
 
 .sidebar h1 {
@@ -527,7 +528,7 @@ body.sidebar-collapsed .main-content-wrapper {
 }
 
 .sidebar-options-wrapper {
-    padding: .5rem 0;
+    padding: .25rem 0;
 }
 
 .sidebar-options-wrapper.mt-auto {
@@ -536,6 +537,118 @@ body.sidebar-collapsed .main-content-wrapper {
     border-top: 1px solid var(--border-color);
 }
 
+/* --- Version Dropdown (Flat UI) --- */
+.sidebar-version-wrapper {
+    padding: 0.25rem .5em;
+}
+
+.sidebar-bottom-group.mt-auto {
+    margin-top: auto;
+}
+
+.docmd-version-dropdown {
+    position: relative;
+    width: 100%;
+}
+
+.version-dropdown-toggle {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    width: 100%;
+    padding: 0.5rem 0.75rem;
+    background-color: var(--bg-color);
+    border: 1px solid var(--border-color);
+    border-radius: var(--ui-border-radius);
+    color: var(--text-heading);
+    font-size: 0.85rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.version-dropdown-toggle:hover {
+    border-color: var(--text-muted);
+}
+
+.version-dropdown-menu {
+    position: absolute;
+    top: calc(100% + 4px);
+    left: 0;
+    right: 0;
+    margin: 0;
+    padding: 0.25rem;
+    background-color: var(--bg-color);
+    border: 1px solid var(--border-color);
+    border-radius: var(--ui-border-radius);
+    box-shadow: var(--shadow-md);
+    list-style: none;
+    z-index: 100;
+    opacity: 0;
+    visibility: hidden;
+    transform: translateY(-5px);
+    transition: all 0.2s ease;
+}
+
+.docmd-version-dropdown.open .version-dropdown-menu {
+    opacity: 1;
+    visibility: visible;
+    transform: translateY(0);
+}
+
+.version-dropdown-item {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.4rem 0.5rem;
+    color: var(--text-color);
+    font-size: 0.85rem;
+    text-decoration: none;
+    border-radius: 4px;
+    transition: background-color 0.2s;
+}
+
+.version-dropdown-item:hover {
+    background-color: var(--sidebar-link-active-bg);
+    color: var(--text-heading);
+    text-decoration: none;
+}
+
+.version-dropdown-item.active {
+    font-weight: 600;
+    color: var(--link-color);
+    background-color: var(--sidebar-link-active-bg);
+}
+
+.version-check {
+    width: 1rem;
+    height: 1rem;
+}
+
+.version-chevron {
+    width: 1rem;
+    height: 1rem;
+    transition: transform 0.2s ease;
+}
+
+.docmd-version-dropdown.open .version-chevron {
+    transform: rotate(180deg);
+}
+
+.sidebar-bottom-group .version-dropdown-menu {
+    top: auto;
+    bottom: calc(100% + 4px);
+    transform: translateY(5px);
+}
+
+.sidebar-bottom-group .docmd-version-dropdown.open .version-dropdown-menu {
+    transform: translateY(0);
+}
+
+.sidebar-bottom-group .version-dropdown-toggle .version-chevron {
+    transform: rotate(180deg);
+}
+
 .card .card-title {
     border-bottom: 1px solid var(--border-color)
 }
@@ -645,6 +758,7 @@ html[data-theme=dark] .theme-toggle-button .icon-sun {
 .sidebar-nav {
     flex-grow: 1;
     overflow-y: auto;
+    overflow-x: hidden;
     min-height: 0;
     scrollbar-width: thin;
 }

package/assets/js/docmd-main.js

@@ -11,16 +11,16 @@
  * [docmd-source] - Please do not remove this header.
  * --------------------------------------------------------------------
  */
+
 /**
  * --------------------------------------------------------------------
  * docmd : Client-Side Application Logic (SPA Router & UI)
  * --------------------------------------------------------------------
  */
 
-(function() {
-  // =========================================================================
+(function () {
+
   // 1. EVENT DELEGATION
-  // =========================================================================
   document.addEventListener('click', (e) => {
     // Collapsible Navigation
     const navLabel = e.target.closest('.nav-label, .collapse-icon-wrapper');
@@ -32,7 +32,7 @@
         item.classList.toggle('expanded', !isExpanded);
         item.setAttribute('aria-expanded', !isExpanded);
       }
-      if (navLabel.classList.contains('collapse-icon-wrapper')) return; 
+      if (navLabel.classList.contains('collapse-icon-wrapper')) return;
     }
 
     // Toggles
@@ -54,14 +54,59 @@
       const navItems = Array.from(tabsContainer.querySelectorAll('.docmd-tabs-nav-item'));
       const tabPanes = Array.from(tabsContainer.querySelectorAll('.docmd-tab-pane'));
       const index = navItems.indexOf(tabItem);
-      
+
       navItems.forEach(item => item.classList.remove('active'));
       tabPanes.forEach(pane => pane.classList.remove('active'));
-      
+
       tabItem.classList.add('active');
       if (tabPanes[index]) tabPanes[index].classList.add('active');
     }
 
+    // Version Dropdown Toggle
+    const versionToggle = e.target.closest('.version-dropdown-toggle');
+    if (versionToggle) {
+      e.preventDefault();
+      const dropdown = versionToggle.closest('.docmd-version-dropdown');
+      dropdown.classList.toggle('open');
+      versionToggle.setAttribute('aria-expanded', dropdown.classList.contains('open'));
+      return;
+    }
+
+    // Sticky Version Switching (Path Preservation)
+    const versionLink = e.target.closest('.version-dropdown-item');
+    if (versionLink) {
+      const targetRoot = versionLink.dataset.versionRoot;
+      // Use global fallback if undefined (e.g. on 404 pages)
+      const currentRoot = window.DOCMD_VERSION_ROOT || '/';
+
+      if (targetRoot && window.location.pathname) {
+        try {
+          let currentPath = window.location.pathname;
+          const normCurrentRoot = currentRoot.endsWith('/') ? currentRoot : currentRoot + '/';
+
+          // Only try sticky if we are actually INSIDE the known version path
+          if (currentPath.startsWith(normCurrentRoot)) {
+            e.preventDefault();
+            const suffix = currentPath.substring(normCurrentRoot.length);
+            const normTargetRoot = targetRoot.endsWith('/') ? targetRoot : targetRoot + '/';
+            window.location.href = normTargetRoot + suffix + window.location.hash;
+            return;
+          }
+        } catch (e) {
+          // Ignore errors, let default click happen
+        }
+      }
+      // If sticky logic skipped (e.g. on 404 page or outside root), default <a> click handles it
+    }
+
+    // Close Dropdown if clicked outside
+    if (!e.target.closest('.docmd-version-dropdown')) {
+      document.querySelectorAll('.docmd-version-dropdown.open').forEach(d => {
+        d.classList.remove('open');
+        d.querySelector('.version-dropdown-toggle').setAttribute('aria-expanded', 'false');
+      });
+    }
+
     // Copy Code Button
     const copyBtn = e.target.closest('.copy-code-button');
     if (copyBtn) {
@@ -79,21 +124,19 @@
     }
   });
 
-  // =========================================================================
   // 2. COMPONENT INITIALIZERS
-  // =========================================================================
   function injectCopyButtons() {
     if (document.body.dataset.copyCodeEnabled !== 'true') return;
     const svg = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg>`;
-    
+
     document.querySelectorAll('pre').forEach(preElement => {
-      if (preElement.closest('.code-wrapper')) return; 
+      if (preElement.closest('.code-wrapper')) return;
       const wrapper = document.createElement('div');
       wrapper.className = 'code-wrapper';
       wrapper.style.position = 'relative';
       preElement.parentNode.insertBefore(wrapper, preElement);
       wrapper.appendChild(preElement);
-      
+
       const copyButton = document.createElement('button');
       copyButton.className = 'copy-code-button';
       copyButton.innerHTML = svg;
@@ -107,7 +150,7 @@
     const tocLinks = document.querySelectorAll('.toc-link');
     const headings = document.querySelectorAll('.main-content h2, .main-content h3, .main-content h4');
     const tocContainer = document.querySelector('.toc-list');
-    
+
     if (tocLinks.length === 0 || headings.length === 0) return;
 
     scrollObserver = new IntersectionObserver((entries) => {
@@ -116,7 +159,7 @@
           tocLinks.forEach(link => link.classList.remove('active'));
           const id = entry.target.getAttribute('id');
           const activeLink = document.querySelector(`.toc-link[href="#${id}"]`);
-          
+
           if (activeLink) {
             activeLink.classList.add('active');
             if (tocContainer) {
@@ -143,9 +186,7 @@
     });
   }
 
-  // =========================================================================
   // 3. TARGETED SPA ROUTER
-  // =========================================================================
   function initializeSPA() {
     if (location.protocol === 'file:') return;
     if (document.body.dataset.spaEnabled !== 'true') return;
@@ -156,9 +197,9 @@
 
     // Intent-based Hover Prefetching
     document.addEventListener('mouseover', (e) => {
-      const link = e.target.closest('.sidebar-nav a, .page-navigation a');
+      const link = e.target.closest('.sidebar-nav a, .page-navigation a, .page-footer a, .main-content a');
       if (!link || link.target === '_blank' || link.hasAttribute('download')) return;
-      
+
       const url = new URL(link.href).href;
       if (new URL(url).origin !== location.origin) return;
       if (pageCache.has(url)) return;
@@ -166,10 +207,10 @@
       // Wait 65ms to ensure the user actually intends to click
       clearTimeout(prefetchTimer);
       prefetchTimer = setTimeout(() => {
-          pageCache.set(url, fetch(url).then(res => {
-              if (!res.ok) throw new Error('Prefetch failed');
-              return { html: res.text(), finalUrl: res.url };
-          }).catch(() => pageCache.delete(url)));
+        pageCache.set(url, fetch(url).then(res => {
+          if (!res.ok) throw new Error('Prefetch failed');
+          return { html: res.text(), finalUrl: res.url };
+        }).catch(() => pageCache.delete(url)));
       }, 65);
     });
 
@@ -179,42 +220,44 @@
     document.addEventListener('click', async (e) => {
       if (e.target.closest('.collapse-icon-wrapper')) return;
 
-      const link = e.target.closest('.sidebar-nav a, .page-navigation a');
+      if (e.target.closest('[data-spa-ignore]')) return;
+
+      const link = e.target.closest('.sidebar-nav a, .page-navigation a, .page-footer a, .main-content a');
       if (!link || link.target === '_blank' || link.hasAttribute('download')) return;
-      
+
       const url = new URL(link.href);
       if (url.origin !== location.origin) return;
       if (url.pathname === window.location.pathname && url.hash) return;
-      
+
       e.preventDefault();
       await navigateTo(url.href);
     });
 
     window.addEventListener('popstate', () => {
-      if (window.location.pathname === currentPath) return; 
+      if (window.location.pathname === currentPath) return;
       navigateTo(window.location.href, false);
     });
 
     async function navigateTo(url, pushHistory = true) {
       const layout = document.querySelector('.content-layout');
-      
+
       try {
         if (layout) layout.style.minHeight = layout.getBoundingClientRect().height + 'px';
-        
+
         let data;
         if (pageCache.has(url)) {
-            data = await pageCache.get(url);
-            data.html = await data.html; 
+          data = await pageCache.get(url);
+          data.html = await data.html;
         } else {
-            const res = await fetch(url);
-            if (!res.ok) throw new Error('Fetch failed');
-            data = { html: await res.text(), finalUrl: res.url };
-            pageCache.set(url, Promise.resolve(data));
+          const res = await fetch(url);
+          if (!res.ok) throw new Error('Fetch failed');
+          data = { html: await res.text(), finalUrl: res.url };
+          pageCache.set(url, Promise.resolve(data));
         }
 
         const finalUrl = data.finalUrl;
         const html = data.html;
-        
+
         const parser = new DOMParser();
         const doc = parser.parseFromString(html, 'text/html');
 
@@ -228,58 +271,62 @@
         const newAssets = Array.from(doc.head.querySelectorAll(assetSelectors));
 
         newAssets.forEach((newAsset, index) => {
-            if (oldAssets[index]) {
-                if (oldAssets[index].getAttribute('href') !== newAsset.getAttribute('href')) {
-                    oldAssets[index].setAttribute('href', newAsset.getAttribute('href'));
-                }
-            } else {
-                document.head.appendChild(newAsset.cloneNode(true));
+          if (oldAssets[index]) {
+            if (oldAssets[index].getAttribute('href') !== newAsset.getAttribute('href')) {
+              oldAssets[index].setAttribute('href', newAsset.getAttribute('href'));
             }
+          } else {
+            document.head.appendChild(newAsset.cloneNode(true));
+          }
         });
 
         // Sync Sidebar State
         const oldLis = Array.from(document.querySelectorAll('.sidebar-nav li'));
         const newLis = Array.from(doc.querySelectorAll('.sidebar-nav li'));
-        
+
         oldLis.forEach((oldLi, i) => {
-            const newLi = newLis[i];
-            if (newLi) {
-                oldLi.classList.toggle('active', newLi.classList.contains('active'));
-                oldLi.classList.toggle('active-parent', newLi.classList.contains('active-parent'));
-
-                if (newLi.classList.contains('expanded')) {
-                    oldLi.classList.add('expanded');
-                    oldLi.setAttribute('aria-expanded', 'true');
-                }
-
-                const oldA = oldLi.querySelector('a');
-                const newA = newLi.querySelector('a');
-                if (oldA && newA) {
-                    oldA.setAttribute('href', newA.getAttribute('href'));
-                    oldA.classList.toggle('active', newA.classList.contains('active'));
-                }
+          const newLi = newLis[i];
+          if (newLi) {
+            oldLi.classList.toggle('active', newLi.classList.contains('active'));
+            oldLi.classList.toggle('active-parent', newLi.classList.contains('active-parent'));
+
+            if (newLi.classList.contains('expanded')) {
+              oldLi.classList.add('expanded');
+              oldLi.setAttribute('aria-expanded', 'true');
             }
+
+            const oldA = oldLi.querySelector('a');
+            const newA = newLi.querySelector('a');
+            if (oldA && newA) {
+              oldA.setAttribute('href', newA.getAttribute('href'));
+              oldA.classList.toggle('active', newA.classList.contains('active'));
+            }
+          }
         });
 
-        const selectorsToSwap =[
-          '.content-layout', 
-          '.page-header .header-title', 
-          '.page-footer', 
+        const selectorsToSwap = [
+          '.content-layout',
+          '.page-header .header-title',
+          '.page-footer',
           '.footer-complete',
           '.page-footer-actions'
         ];
 
         selectorsToSwap.forEach(selector => {
-            const oldEl = document.querySelector(selector);
-            const newEl = doc.querySelector(selector);
-            if (oldEl && newEl) oldEl.innerHTML = newEl.innerHTML;
+          const oldEl = document.querySelector(selector);
+          const newEl = doc.querySelector(selector);
+          if (oldEl && newEl) oldEl.innerHTML = newEl.innerHTML;
         });
 
         const hash = new URL(finalUrl).hash;
         if (hash) {
+          try {
             document.querySelector(hash)?.scrollIntoView();
+          } catch (e) {
+            document.getElementById(hash.substring(1))?.scrollIntoView();
+          }
         } else {
-            window.scrollTo(0, 0);
+          window.scrollTo(0, 0);
         }
 
         injectCopyButtons();
@@ -290,36 +337,34 @@
         document.dispatchEvent(new CustomEvent('docmd:page-mounted', { detail: { url: finalUrl } }));
 
         setTimeout(() => {
-            const newLayout = document.querySelector('.content-layout');
-            if (newLayout) newLayout.style.minHeight = '';
+          const newLayout = document.querySelector('.content-layout');
+          if (newLayout) newLayout.style.minHeight = '';
         }, 100);
 
-      } catch(e) {
+      } catch (e) {
         window.location.assign(url);
       }
     }
   }
 
-  // =========================================================================
   // 4. BOOTSTRAP
-  // =========================================================================
   document.addEventListener('DOMContentLoaded', () => {
     if (localStorage.getItem('docmd-sidebar-collapsed') === 'true') {
-        document.body.classList.add('sidebar-collapsed');
+      document.body.classList.add('sidebar-collapsed');
     }
-    
+
     document.querySelectorAll('.theme-toggle-button').forEach(btn => {
       btn.addEventListener('click', () => {
         const t = document.documentElement.getAttribute('data-theme') === 'light' ? 'dark' : 'light';
         document.documentElement.setAttribute('data-theme', t);
         document.body.setAttribute('data-theme', t);
         localStorage.setItem('docmd-theme', t);
-        
+
         const lightLink = document.getElementById('hljs-light');
         const darkLink = document.getElementById('hljs-dark');
         if (lightLink && darkLink) {
-            lightLink.disabled = t === 'dark';
-            darkLink.disabled = t === 'light';
+          lightLink.disabled = t === 'dark';
+          darkLink.disabled = t === 'light';
         }
       });
     });
@@ -327,16 +372,29 @@
     injectCopyButtons();
     initializeScrollSpy();
     initializeSPA();
-    
+
     setTimeout(() => {
-        const activeNav = document.querySelector('.sidebar-nav a.active');
-        const sidebarNav = document.querySelector('.sidebar-nav');
-        if (activeNav && sidebarNav) {
-            sidebarNav.scrollTo({ top: activeNav.offsetTop - (sidebarNav.clientHeight / 2), behavior: 'instant' });
-        }
-        if (window.location.hash) {
-            document.querySelector(window.location.hash)?.scrollIntoView();
+      // PWA Unregistration Safety Net:
+      // If the PWA plugin is removed from docmd.config.js, the <link rel="manifest"> disappears.
+      // We explicitly unregister all ghost service workers to safely kill the offline cache.
+      if ('serviceWorker' in navigator && !document.querySelector('link[rel="manifest"]')) {
+        navigator.serviceWorker.getRegistrations().then(registrations => {
+          registrations.forEach(reg => reg.unregister().catch(() => { }));
+        });
+      }
+
+      const activeNav = document.querySelector('.sidebar-nav a.active');
+      const sidebarNav = document.querySelector('.sidebar-nav');
+      if (activeNav && sidebarNav) {
+        sidebarNav.scrollTo({ top: activeNav.offsetTop - (sidebarNav.clientHeight / 2), behavior: 'instant' });
+      }
+      if (window.location.hash) {
+        try {
+          document.querySelector(window.location.hash)?.scrollIntoView();
+        } catch (e) {
+          document.getElementById(window.location.hash.substring(1))?.scrollIntoView();
         }
+      }
     }, 100);
   });
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docmd/ui",
-  "version": "0.4.11",
-  "description": "Base UI templates and assets for docmd",
+  "version": "0.5.1",
+  "description": "Base UI templates and assets for docmd.",
   "main": "index.js",
   "files": [
     "templates",

package/templates/404.ejs

@@ -0,0 +1,89 @@
+<!--
+  ---------------------------------------------------------------
+  docmd : the minimalist, zero-config documentation generator.
+  @website https://docmd.io
+  [docmd-source] - Please do not remove this header.
+  ---------------------------------------------------------------
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= pageTitle %></title>
+    
+    <!-- Force absolute paths for assets using relativePathToRoot (which we will set to '/') -->
+    <%- faviconLinkHtml || '' %>
+    
+    <!-- 1. Core CSS -->
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-main.css?v=<%= buildHash %>">
+    
+    <!-- 2. Highlight.js (Theme aware) -->
+    <% 
+       const isDarkDefault = defaultMode === 'dark';
+    %>
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-highlight-light.css?v=<%= buildHash %>" id="hljs-light" <%= isDarkDefault ? 'disabled' : '' %>>
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-highlight-dark.css?v=<%= buildHash %>" id="hljs-dark" <%= isDarkDefault ? '' : 'disabled' %>>
+
+    <!-- 3. Theme CSS -->
+    <% if (theme && theme.name !== 'default') { %>
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-theme-<%= theme.name %>.css?v=<%= buildHash %>">
+    <% } %>
+
+    <!-- 4. Custom CSS -->
+    <% (customCssFiles || []).forEach(cssFile => { 
+       const cleanPath = cssFile.startsWith('/') ? cssFile.substring(1) : cssFile;
+    %>
+    <link rel="stylesheet" href="<%= relativePathToRoot %><%= cleanPath %>?v=<%= buildHash %>">
+    <% }); %>
+
+    <!-- 5. Theme Init (Dark Mode logic) -->
+    <%- themeInitScript %>
+
+    <style>
+        body {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+            text-align: center;
+            padding: 20px;
+            background-color: var(--bg-color);
+            color: var(--text-color);
+        }
+        .error-logo { height: 60px; margin-bottom: 2rem; width: auto; display: block; }
+        .error-logo.light { display: var(--display-light, block); }
+        .error-logo.dark { display: var(--display-dark, none); }
+        
+        /* Simple theme logic for logo if JS fails */
+        @media (prefers-color-scheme: dark) {
+            :root[data-theme="system"] .error-logo.light { display: none; }
+            :root[data-theme="system"] .error-logo.dark { display: block; }
+        }
+        :root[data-theme="dark"] .error-logo.light { display: none; }
+        :root[data-theme="dark"] .error-logo.dark { display: block; }
+
+        h1 { font-size: 5rem; margin: 0; line-height: 1; color: var(--link-color); font-weight: 700; }
+        h2 { font-size: 2rem; margin: 1rem 0; }
+        p { font-size: 1.2rem; color: var(--text-muted); margin-bottom: 2rem; max-width: 500px; }
+        .docmd-button { font-size: 1.1rem; padding: 0.8rem 1.5rem; }
+    </style>
+</head>
+<body>
+    <% if (logo) { %>
+        <% if (logo.light) { %>
+            <img src="<%= relativePathToRoot %><%= logo.light.replace(/^\//, '') %>" class="error-logo light" alt="Logo">
+        <% } %>
+        <% if (logo.dark) { %>
+            <img src="<%= relativePathToRoot %><%= logo.dark.replace(/^\//, '') %>" class="error-logo dark" alt="Logo">
+        <% } %>
+    <% } %>
+
+    <h1>404</h1>
+    <h2>Page Not Found</h2>
+    <p><%= content %></p>
+    <a href="<%= relativePathToRoot %>" class="docmd-button">Return Home</a>
+</body>
+</html>

package/templates/layout.ejs

@@ -10,14 +10,40 @@
 <html lang="en">
 <head>
     <meta charset="UTF-8">
-    <meta name="generator" content="docmd v0.4.x">
+    <meta name="generator" content="docmd v0.5.x">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <% 
+       let versionRoot = '/';
+       let siteRoot = relativePathToRoot;
+       
+       if (config.versions?.current && config._activeVersion?.id) {
+           const isSubVersion = config.versions.current !== config._activeVersion.id;
+           versionRoot = isSubVersion ? '/' + config._activeVersion.id + '/' : '/';
+           
+           // If we are in a sub-version (v04/), the relativePathToRoot takes us to /v04/.
+           // We need to go up one more level to reach the true site root.
+           if (isSubVersion) {
+               siteRoot = (relativePathToRoot === './' ? '' : relativePathToRoot) + '../';
+           }
+       }
+       
+       if (locals.isOfflineMode) {
+           versionRoot = '';
+       }
+    %>
     <script>
         var root = "<%= relativePathToRoot %>";
         if (root && !root.endsWith('/')) root += '/';
         if (root === '') root = './';
-        window.DOCMD_ROOT = root;
+        window.DOCMD_ROOT = root; // Context Root (Assets)
+        
+        var siteRoot = "<%= siteRoot %>";
+        if (siteRoot && !siteRoot.endsWith('/')) siteRoot += '/';
+        if (siteRoot === '') siteRoot = './';
+        window.DOCMD_SITE_ROOT = siteRoot; // True Site Root (Search Index)
+        
         window.DOCMD_DEFAULT_MODE = "<%= defaultMode %>";
+        window.DOCMD_VERSION_ROOT = "<%- versionRoot %>";
     </script>
     <title><%= pageTitle %></title>
     <%- faviconLinkHtml || '' %>
@@ -41,42 +67,60 @@
     <% }); %>
     <%- themeInitScript %>
 </head>
-<body class="<%= sidebarConfig?.collapsible ? 'sidebar-collapsible' : 'sidebar-not-collapsible' %>" 
-      data-default-collapsed="<%= sidebarConfig?.defaultCollapsed %>" 
-      data-copy-code-enabled="<%= config.copyCode === true %>"
-      data-spa-enabled="<%= config.layout?.spa !== false %>">
+<body class="<%= sidebarConfig?.enabled === false ? 'no-sidebar' : (sidebarConfig?.collapsible ? 'sidebar-collapsible' : 'sidebar-not-collapsible') %>" 
+data-default-collapsed="<%= sidebarConfig?.defaultCollapsed %>" 
+data-copy-code-enabled="<%= config.copyCode === true %>"
+data-spa-enabled="<%= config.layout?.spa !== false %>">
     
     <a href="#main-content" class="skip-link">Skip to main content</a>
-    
-    <aside class="sidebar">
-        <div class="sidebar-header">
-            <% if (logo && logo.light && logo.dark) { %>
-            <a href="<%= logo.href || relativePathToRoot %>" class="logo-link">
-                <img src="<%= relativePathToRoot %><%- logo.light.startsWith('/') ? logo.light.substring(1) : logo.light %>" alt="<%= logo.alt || siteTitle %>" class="logo-light" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
-                <img src="<%= relativePathToRoot %><%- logo.dark.startsWith('/') ? logo.dark.substring(1) : logo.dark %>" alt="<%= logo.alt || siteTitle %>" class="logo-dark" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
-            </a>
-            <% } else { %>
-            <h1><a href="<%= relativePathToRoot %>index.html"><%= siteTitle %></a></h1>
-            <% } %>
-            <span class="mobile-view sidebar-menu-button float-right">
-                <%- renderIcon("menu") %>
-            </span>
-        </div>
 
-        <% if (optionsMenu?.position === 'sidebar-top') { %>
-            <div class="sidebar-options-wrapper">
-                <%- include('partials/options-menu', { optionsMenu }) %>
+    <% if (sidebarConfig?.enabled !== false) { %>
+        <aside class="sidebar">
+            <div class="sidebar-header">
+                <% if (logo && logo.light && logo.dark) { %>
+                <a href="<%= logo.href || relativePathToRoot %>" class="logo-link">
+                    <img src="<%= relativePathToRoot %><%- logo.light.startsWith('/') ? logo.light.substring(1) : logo.light %>" alt="<%= logo.alt || siteTitle %>" class="logo-light" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
+                    <img src="<%= relativePathToRoot %><%- logo.dark.startsWith('/') ? logo.dark.substring(1) : logo.dark %>" alt="<%= logo.alt || siteTitle %>" class="logo-dark" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
+                </a>
+                <% } else { %>
+                <h1><a href="<%= relativePathToRoot %>index.html"><%= siteTitle %></a></h1>
+                <% } %>
+                <span class="mobile-view sidebar-menu-button float-right">
+                    <%- renderIcon("menu") %>
+                </span>
             </div>
-        <% } %>
 
-        <%- navigationHtml %>
+            <div class="sidebar-top-group">
+                <% if (locals.optionsMenu && optionsMenu.position === 'sidebar-top') { %>
+                    <div class="sidebar-options-wrapper">
+                        <%- include('partials/options-menu', { optionsMenu }) %>
+                    </div>
+                <% } %>
+                
+                <% if (config.versions && config.versions.position === 'sidebar-top') { %>
+                    <div class="sidebar-version-wrapper">
+                        <%- include('partials/version-dropdown', { versions: config.versions, activeVersion: config._activeVersion, relativePathToRoot }) %>
+                    </div>
+                <% } %>
+            </div>
+
+            <%- navigationHtml %>
+
+            <div class="sidebar-bottom-group mt-auto">
+                <% if (config.versions && config.versions.position === 'sidebar-bottom') { %>
+                    <div class="sidebar-version-wrapper">
+                        <%- include('partials/version-dropdown', { versions: config.versions, activeVersion: config._activeVersion, relativePathToRoot }) %>
+                    </div>
+                <% } %>
 
-        <% if (optionsMenu?.position === 'sidebar-bottom') { %>
-            <div class="sidebar-options-wrapper mt-auto">
-                <%- include('partials/options-menu', { optionsMenu }) %>
+                <% if (locals.optionsMenu && optionsMenu.position === 'sidebar-bottom') { %>
+                    <div class="sidebar-options-wrapper">
+                        <%- include('partials/options-menu', { optionsMenu }) %>
+                    </div>
+                <% } %>
             </div>
-        <% } %>
-    </aside>
+        </aside>
+    <% } %>
 
     <div class="main-content-wrapper">
         <% if (headerConfig?.enabled !== false) { %>

package/templates/no-style.ejs

@@ -10,7 +10,7 @@
 <html lang="en">
 <head>
     <meta charset="UTF-8">
-    <meta name="generator" content="docmd v0.4.x">
+    <meta name="generator" content="docmd v0.5.x">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
     <!-- 1. GLOBALS -->

package/templates/partials/footer.ejs

@@ -40,18 +40,22 @@
 
     <div class="footer-complete-bottom">
         <div class="user-footer"><%- footerHtml || (footerConfig.copyright ? footerConfig.copyright : '') %></div>
+        <% if (footerConfig.branding !== false) { %>
         <div class="branding-footer">
             Built with <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"></path><path d="M12 5 9.04 7.96a2.17 2.17 0 0 0 0 3.08c.82.82 2.13.85 3 .07l2.07-1.9a2.82 2.82 0 0 1 3.79 0l2.96 2.66"></path><path d="m18 15-2-2"></path><path d="m15 18-2-2"></path></svg> <a href="https://docmd.io" target="_blank" rel="noopener">docmd.</a>
         </div>
+        <% } %>
     </div>
 </footer>
 <% } else { %>
 <footer class="page-footer">
     <div class="footer-content">
         <div class="user-footer"><%- footerHtml || (footerConfig?.copyright ? footerConfig.copyright : '') %></div>
+        <% if (footerConfig?.branding !== false) { %>
         <div class="branding-footer">
             Built with <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"></path><path d="M12 5 9.04 7.96a2.17 2.17 0 0 0 0 3.08c.82.82 2.13.85 3 .07l2.07-1.9a2.82 2.82 0 0 1 3.79 0l2.96 2.66"></path><path d="m18 15-2-2"></path><path d="m15 18-2-2"></path></svg> <a href="https://docmd.io" target="_blank" rel="noopener">docmd.</a>
         </div>
+        <% } %>
     </div>
 </footer>
 <% } %>

package/templates/partials/version-dropdown.ejs

@@ -0,0 +1,50 @@
+<%# ---------------------------------------------------------------
+  # docmd : the minimalist, zero-config documentation generator.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% if (versions && versions.all.length > 0) { 
+    const current = activeVersion || versions.all.find(v => v.id === versions.current);
+    
+    // If we are in a sub-version (e.g. /v1/), we go up one level (../) to get to root.
+    const isCurrentSubVersion = current && current.id !== versions.current;
+    const upOneLevel = isCurrentSubVersion ? '../' : '';
+%>
+<div class="docmd-version-dropdown">
+    <button class="version-dropdown-toggle" aria-expanded="false" aria-label="Select Version">
+        <span class="version-label"><%= current ? current.label : 'Version' %></span>
+        <%- renderIcon('chevron-down', { class: 'version-chevron' }) %>
+    </button>
+    <ul class="version-dropdown-menu">
+        <% versions.all.forEach(v => { 
+            const isCurrentActive = current && v.id === current.id;
+            const isTargetRootVersion = v.id === versions.current;
+            
+            // We use the 'config' object which is available in all templates
+            
+            const base = config.base || '/';
+            const normalizedBase = base.endsWith('/') ? base : base + '/';
+            
+            const targetSuffix = isTargetRootVersion ? '' : v.id + '/';
+            const absoluteHref = normalizedBase + targetSuffix;
+            
+            // Data Root for JS Sticky Logic
+            const dataRoot = absoluteHref;
+        %>
+        <li>
+            <a href="<%= absoluteHref %>" 
+               class="version-dropdown-item <%= isCurrentActive ? 'active' : '' %>" 
+               data-spa-ignore
+               data-version-root="<%= dataRoot %>">
+                <%= v.label %>
+                <% if (isCurrentActive) { %>
+                    <%- renderIcon('check', { class: 'version-check' }) %>
+                <% } %>
+            </a>
+        </li>
+        <% }) %>
+    </ul>
+</div>
+<% } %>