docnest 0.1.14 → 0.1.16

package/README.md

@@ -1,6 +1,6 @@
 # DocNest
 
-DocNest 是一个可复用的本地 Markdown 文档中心。文档内容归使用它的项目所有，DocNest 只提供查看、导航、Mermaid 图表、导出和本地 Watch 能力。
+DocNest 是一个可复用的本地 Markdown 文档中心。文档内容归使用它的项目所有，DocNest 只提供查看、导航、搜索、Mermaid 图表、导出和本地 Watch 能力。
 
 ## 快速接入
 
@@ -56,6 +56,16 @@ export default defineConfig({
 
 未配置 `appearance` 时使用 `slate-modern + auto`。旧配置中的 `current-docs` 会自动迁移到 `slate-modern`，正文视觉不会发生变化；旧版保存的 `markdown-theme` 明暗偏好也会自动迁移到新的项目级存储键。
 
+### 文档搜索
+
+普通阅读模式下，页面顶部提供文档搜索入口，也可以使用 `⌘K`（macOS）或
+`Ctrl K`（Windows/Linux）打开。搜索索引在首次打开搜索时才加载，覆盖文档标题、目录路径、标题层级、正文和代码块；中文按连续字符匹配，英文和带空格的查询按多个词匹配。结果按标题、目录和正文命中位置综合排序，并显示安全的文本摘要。
+
+搜索完全基于宿主项目自己的 Markdown 内容，不依赖 Algolia 或其他外部服务。动态服务通过同源
+`/search-index.json` 提供索引；静态站点需要把同一份响应保存为站点根目录的
+`search-index.json`，并保留页面上的静态站点标记，让结果链接指向 `/doc/<path>.html`。
+受限模式不生成搜索索引，也不显示搜索入口，避免摘要绕过阅读限制。
+
 PDF、页面水印和图表外带能力由一个开关统一控制，默认使用普通阅读模式：
 
 ```js

package/dist/server.js

@@ -422,6 +422,114 @@ app.get('/ready', async (req, res) => {
 // 消费项目可以在通用文档路由前注入自己的访问控制；DocNest 不实现任何项目身份系统。
 const beforeDocumentRoutes = globalThis.__DOCNEST_BEFORE_DOCUMENT_ROUTES__ || [];
 beforeDocumentRoutes.forEach((middleware) => app.use(middleware));
+const SEARCH_INDEX_VERSION = 1;
+let searchIndexCache = null;
+let searchIndexBuildPromise = null;
+function collectSearchDocPaths(tree, paths = []) {
+    for (const item of tree) {
+        if (item.type === 'directory') {
+            collectSearchDocPaths(item.children, paths);
+        }
+        else if (item.type === 'file') {
+            paths.push(item.path);
+        }
+    }
+    return paths;
+}
+function normalizeSearchText(value) {
+    return String(value || '').replace(/\s+/g, ' ').trim();
+}
+function getSearchInlineText(token) {
+    if (!Array.isArray(token.children))
+        return token.content;
+    return token.children.map((child) => {
+        if (child.type === 'softbreak' || child.type === 'hardbreak')
+            return ' ';
+        if (child.type === 'image')
+            return child.content || '';
+        return String(child.content || '').replace(/<[^>]+>/g, ' ');
+    }).join('');
+}
+function createSearchDocument(docPath, markdown) {
+    const tokens = md.parse(markdown, {});
+    const headings = [];
+    const textParts = [];
+    let insideHeading = false;
+    let title = '';
+    for (const token of tokens) {
+        if (token.type === 'heading_open') {
+            insideHeading = true;
+            continue;
+        }
+        if (token.type === 'heading_close') {
+            insideHeading = false;
+            continue;
+        }
+        if (token.type === 'inline') {
+            const text = normalizeSearchText(getSearchInlineText(token));
+            if (!text)
+                continue;
+            textParts.push(text);
+            if (insideHeading) {
+                headings.push(text);
+                if (!title)
+                    title = text;
+            }
+            continue;
+        }
+        if (token.type === 'code_block' || token.type === 'fence') {
+            const code = normalizeSearchText(token.content);
+            if (code)
+                textParts.push(code);
+        }
+    }
+    const fallbackTitle = path.basename(docPath).replace(/\.(md|markdown)$/i, '');
+    return {
+        path: docPath,
+        title: title || fallbackTitle,
+        directory: path.posix.dirname(docPath) === '.' ? '' : path.posix.dirname(docPath),
+        headings,
+        text: normalizeSearchText(textParts.join(' ')),
+    };
+}
+async function buildSearchIndex() {
+    if (searchIndexCache)
+        return searchIndexCache;
+    if (searchIndexBuildPromise)
+        return searchIndexBuildPromise;
+    searchIndexBuildPromise = (async () => {
+        const tree = await getDocTree(DOCS_DIR);
+        const paths = collectSearchDocPaths(tree);
+        const documents = [];
+        for (const docPath of paths) {
+            const markdown = await storageReadFile(docPath);
+            documents.push(createSearchDocument(docPath, markdown));
+        }
+        return { version: SEARCH_INDEX_VERSION, documents };
+    })()
+        .then((index) => {
+        searchIndexCache = index;
+        return index;
+    })
+        .finally(() => {
+        searchIndexBuildPromise = null;
+    });
+    return searchIndexBuildPromise;
+}
+function invalidateSearchIndex() {
+    searchIndexCache = null;
+}
+app.get('/search-index.json', async (req, res) => {
+    if (DOCS_RESTRICTED_MODE) {
+        return res.status(404).json({ ok: false, error: '搜索功能已关闭。' });
+    }
+    try {
+        return res.json(await buildSearchIndex());
+    }
+    catch (error) {
+        return res.status(503).json({ ok: false, error: `搜索索引暂不可用：${error.message}` });
+    }
+});
 // 获取文档目录树（排除隐藏目录和系统文件）
 async function getDocTree(dir, basePath = '') {
     const entries = await storageReadDir(basePath);
@@ -882,6 +990,7 @@ if (WATCH_ENABLED && !injectedDocumentStore) {
             return;
         }
         const relativePath = normalizePath(filePath);
+        invalidateSearchIndex();
         console.log(`📝 文件已更新: ${relativePath}`);
         try {
             // 重新读取文件内容并渲染
@@ -904,6 +1013,7 @@ if (WATCH_ENABLED && !injectedDocumentStore) {
     watcher.on('add', (filePath) => {
         if (filePath.endsWith('.md')) {
             const relativePath = normalizePath(filePath);
+            invalidateSearchIndex();
             console.log(`➕ 新文件已添加: ${relativePath}`);
             io.emit('file-added', { path: relativePath });
         }
@@ -911,6 +1021,7 @@ if (WATCH_ENABLED && !injectedDocumentStore) {
     watcher.on('unlink', (filePath) => {
         if (filePath.endsWith('.md')) {
             const relativePath = normalizePath(filePath);
+            invalidateSearchIndex();
             console.log(`🗑️  文件已删除: ${relativePath}`);
             io.emit('file-deleted', { path: relativePath });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docnest",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "可复用的本地 Markdown 文档中心",
   "repository": {
     "type": "git",

package/server/static/css/styles.css

@@ -167,6 +167,39 @@ body {
   min-width: 112px;
 }
 
+.doc-search-trigger {
+  min-width: 168px;
+  justify-content: flex-start;
+}
+
+.doc-search-trigger .header-action-text {
+  flex: 1;
+  text-align: left;
+}
+
+.doc-search-icon {
+  display: inline-block;
+  font-size: 1.2rem;
+  line-height: 1;
+}
+
+.doc-search-shortcut,
+.doc-search-input-key {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2.25rem;
+  padding: 0.15rem 0.35rem;
+  border: 1px solid var(--linear-border);
+  border-radius: 5px;
+  background: var(--linear-bg);
+  color: var(--linear-text-muted);
+  font: inherit;
+  font-size: 0.6875rem;
+  line-height: 1.2;
+  white-space: nowrap;
+}
+
 .theme-icon {
   display: inline-block;
   line-height: 1;
@@ -179,13 +212,26 @@ body {
 }
 
 .doc-pdf-export-root {
+  /* PDF pages use a light paper palette, independently of the live reading mode. */
+  --linear-bg: #ffffff;
+  --linear-bg-subtle: #fafafa;
+  --linear-border: #e5e5e5;
+  --linear-text: #111111;
+  --linear-text-muted: #6b6b6b;
+  --linear-accent: #5e6ad2;
+  --linear-accent-hover: #4c57b8;
+  --doc-surface-raised: #ffffff;
+  --doc-rule-strong: #bfc0c5;
+  --doc-accent-soft: rgba(94, 106, 210, 0.12);
+  --doc-code-bg: #f6f7f8;
+  --doc-code-text: #24262b;
   position: absolute;
   left: 0;
   top: 0;
   width: 960px;
   padding: 24px 32px;
-  background: #ffffff;
-  color: #111111;
+  background: var(--doc-surface-raised);
+  color: var(--linear-text);
   z-index: -1;
   pointer-events: none;
   overflow: visible;
@@ -540,6 +586,10 @@ body[data-theme="dark"] .dir-toggle.active {
   margin: 0 auto;
 }
 
+body.doc-search-open {
+  overflow: hidden;
+}
+
 .doc-toc {
   position: sticky;
   top: 12px;
@@ -2124,6 +2174,8 @@ body[data-theme="dark"] .tree-nav::-webkit-scrollbar-thumb:hover {
   .theme-toggle,
   .download-pdf-btn,
   .print-btn,
+  .doc-search-modal,
+  .doc-search-trigger,
   .sidebar,
   .sidebar-resizer {
     display: none !important;
@@ -2148,6 +2200,228 @@ body[data-theme="dark"] .tree-nav::-webkit-scrollbar-thumb:hover {
   }
 }
 
+.doc-search-modal {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  box-sizing: border-box;
+  padding: clamp(4rem, 12vh, 8rem) 1rem 2rem;
+  background: rgba(15, 23, 42, 0.48);
+  z-index: 20030;
+}
+
+.doc-search-modal[hidden] {
+  display: none;
+}
+
+.doc-search-modal__panel {
+  display: flex;
+  flex-direction: column;
+  width: min(720px, 100%);
+  max-height: min(680px, calc(100vh - 6rem));
+  overflow: hidden;
+  box-sizing: border-box;
+  border: 1px solid var(--linear-border);
+  border-radius: 16px;
+  background: var(--linear-bg);
+  color: var(--linear-text);
+  box-shadow: 0 24px 80px rgba(15, 23, 42, 0.28);
+}
+
+.doc-search-modal__topline {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 1.15rem 0.75rem;
+}
+
+.doc-search-modal__eyebrow {
+  color: var(--linear-text-muted);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.doc-search-modal__close {
+  width: 2rem;
+  height: 2rem;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--linear-text-muted);
+  cursor: pointer;
+  font-size: 1.4rem;
+  line-height: 1;
+}
+
+.doc-search-modal__close:hover {
+  background: var(--linear-bg-subtle);
+  color: var(--linear-text);
+}
+
+.doc-search-input-wrap {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin: 0 1.15rem;
+  padding: 0.7rem 0.8rem;
+  border: 1px solid var(--linear-border);
+  border-radius: 10px;
+  background: var(--linear-bg-subtle);
+}
+
+.doc-search-input-wrap:focus-within {
+  border-color: var(--linear-accent);
+  box-shadow: 0 0 0 3px var(--doc-accent-soft);
+}
+
+.doc-search-input-icon {
+  flex: 0 0 auto;
+  color: var(--linear-accent);
+  font-size: 1.35rem;
+  line-height: 1;
+}
+
+.doc-search-input {
+  min-width: 0;
+  flex: 1;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  color: var(--linear-text);
+  font: inherit;
+  font-size: 1rem;
+}
+
+.doc-search-input::placeholder {
+  color: var(--linear-text-muted);
+}
+
+.doc-search-input:disabled {
+  cursor: wait;
+  opacity: 0.65;
+}
+
+.doc-search-status {
+  min-height: 1.25rem;
+  padding: 0.75rem 1.25rem 0.5rem;
+  color: var(--linear-text-muted);
+  font-size: 0.75rem;
+}
+
+.doc-search-results {
+  min-height: 5rem;
+  overflow-y: auto;
+  padding: 0 0.6rem 0.6rem;
+  overscroll-behavior: contain;
+}
+
+.doc-search-result {
+  position: relative;
+  display: block;
+  padding: 0.8rem 2.5rem 0.75rem 0.8rem;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  color: var(--linear-text);
+  text-decoration: none;
+}
+
+.doc-search-result:hover,
+.doc-search-result.is-selected {
+  border-color: var(--linear-border);
+  background: var(--linear-bg-subtle);
+}
+
+.doc-search-result__title {
+  overflow: hidden;
+  color: var(--linear-text);
+  font-size: 0.9375rem;
+  font-weight: 650;
+  line-height: 1.4;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.doc-search-result__path {
+  margin-top: 0.15rem;
+  overflow: hidden;
+  color: var(--linear-accent);
+  font-size: 0.6875rem;
+  line-height: 1.4;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.doc-search-result__snippet {
+  display: -webkit-box;
+  overflow: hidden;
+  margin: 0.35rem 0 0;
+  color: var(--linear-text-muted);
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.doc-search-result__arrow {
+  position: absolute;
+  top: 50%;
+  right: 0.9rem;
+  color: var(--linear-text-muted);
+  font-size: 1rem;
+  transform: translateY(-50%);
+}
+
+.doc-search-result.is-selected .doc-search-result__arrow,
+.doc-search-result:hover .doc-search-result__arrow {
+  color: var(--linear-accent);
+}
+
+.doc-search-result mark {
+  border-radius: 3px;
+  background: var(--doc-accent-soft);
+  color: inherit;
+  font-weight: 700;
+}
+
+.doc-search-empty {
+  display: grid;
+  min-height: 5rem;
+  place-items: center;
+  padding: 1.5rem;
+  color: var(--linear-text-muted);
+  font-size: 0.8125rem;
+  text-align: center;
+}
+
+.doc-search-hint {
+  display: flex;
+  gap: 1rem;
+  padding: 0.7rem 1.15rem 0.85rem;
+  border-top: 1px solid var(--linear-border);
+  color: var(--linear-text-muted);
+  font-size: 0.6875rem;
+}
+
+@media (max-width: 768px) {
+  .doc-search-modal {
+    padding: 1rem;
+  }
+
+  .doc-search-modal__panel {
+    max-height: calc(100vh - 2rem);
+    border-radius: 12px;
+  }
+
+  .doc-search-hint {
+    gap: 0.65rem;
+    flex-wrap: wrap;
+  }
+}
+
 .pdf-export-modal {
   position: fixed;
   inset: 0;

package/server/static/css/themes.css

@@ -379,7 +379,8 @@ body[data-doc-theme][data-theme="dark"] .pdf-export-modal__btn {
 }
 
 /* Theme 01: Slate Modern — the package's original visual language. */
-body[data-doc-theme="slate-modern"] {
+body[data-doc-theme="slate-modern"],
+.doc-pdf-export-root[data-doc-theme="slate-modern"] {
   --doc-font-ui: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
     "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
   --doc-font-reading: var(--doc-font-ui);
@@ -387,7 +388,8 @@ body[data-doc-theme="slate-modern"] {
 }
 
 /* Theme 02: Editorial Atlas */
-body[data-doc-theme="editorial-atlas"] {
+body[data-doc-theme="editorial-atlas"],
+.doc-pdf-export-root[data-doc-theme="editorial-atlas"] {
   --linear-bg: #f3f0e7;
   --linear-bg-subtle: #ebe6da;
   --linear-sidebar: #eee9dd;
@@ -490,7 +492,8 @@ body[data-doc-theme="editorial-atlas"] .doc-toc {
 }
 
 /* Theme 03: Precision Index */
-body[data-doc-theme="precision-index"] {
+body[data-doc-theme="precision-index"],
+.doc-pdf-export-root[data-doc-theme="precision-index"] {
   --linear-bg: #eef2f3;
   --linear-bg-subtle: #e4eaec;
   --linear-sidebar: #e9eef0;
@@ -640,7 +643,8 @@ body[data-doc-theme="precision-index"] .doc-toc-title {
 }
 
 /* Theme 04: Archive Room */
-body[data-doc-theme="archive-room"] {
+body[data-doc-theme="archive-room"],
+.doc-pdf-export-root[data-doc-theme="archive-room"] {
   --linear-bg: #f3efe4;
   --linear-bg-subtle: #e9e2d3;
   --linear-sidebar: #ebe5d8;
@@ -775,7 +779,8 @@ body[data-doc-theme="archive-room"] .doc-toc {
 }
 
 /* Theme 05: Swiss Manual */
-body[data-doc-theme="swiss-manual"] {
+body[data-doc-theme="swiss-manual"],
+.doc-pdf-export-root[data-doc-theme="swiss-manual"] {
   --linear-bg: #f4f3ef;
   --linear-bg-subtle: #e9e7e0;
   --linear-sidebar: #eeece6;

package/server/static/js/core/doc-pdf-export.js

@@ -93,9 +93,40 @@
   function createExportRoot(article) {
     var root = document.createElement('div');
     root.className = EXPORT_CLASS;
+    root.setAttribute('data-doc-theme', document.body.getAttribute('data-doc-theme') || 'slate-modern');
+    root.setAttribute('data-theme', 'light');
 
     var clone = article.cloneNode(true);
     removeTransientNodes(clone);
+    // html2canvas may paint closed <details> descendants without reserving their
+    // height. Export static, expanded sections while leaving the live page alone.
+    Array.prototype.slice.call(clone.querySelectorAll('details')).reverse().forEach(function(details) {
+      var section = document.createElement('section');
+      Array.prototype.slice.call(details.attributes).forEach(function(attribute) {
+        if (attribute.name !== 'open') section.setAttribute(attribute.name, attribute.value);
+      });
+      section.style.display = 'block';
+      section.style.height = 'auto';
+      section.style.maxHeight = 'none';
+      section.style.overflow = 'visible';
+      section.style.margin = '1em 0';
+      while (details.firstChild) {
+        var child = details.firstChild;
+        if (child.tagName === 'SUMMARY') {
+          var heading = document.createElement('div');
+          heading.className = 'doc-pdf-section-title';
+          heading.style.fontWeight = '700';
+          heading.style.marginBottom = '12px';
+          while (child.firstChild) heading.appendChild(child.firstChild);
+          section.appendChild(heading);
+          details.removeChild(child);
+        } else {
+          section.appendChild(child);
+        }
+      }
+      details.parentNode.replaceChild(section, details);
+    });
+    clone.querySelectorAll('img').forEach(function(img) { img.loading = 'eager'; });
     root.appendChild(clone);
     document.body.appendChild(root);
 
@@ -137,18 +168,60 @@
     return breakpoints;
   }
 
+  function collectProtectedRegions(root, canvasScale) {
+    var rootRect = root.getBoundingClientRect();
+    var regions = [];
+    root.querySelectorAll('img, svg, canvas, figure, .mermaid').forEach(function(node) {
+      var rect = node.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      regions.push({
+        top: Math.max(0, Math.floor((rect.top - rootRect.top) * canvasScale)),
+        bottom: Math.max(0, Math.ceil((rect.bottom - rootRect.top) * canvasScale)),
+      });
+    });
+    regions.sort(function(a, b) { return a.top - b.top || b.bottom - a.bottom; });
+    var merged = [];
+    regions.forEach(function(region) {
+      var last = merged[merged.length - 1];
+      if (last && region.top < last.bottom) {
+        last.bottom = Math.max(last.bottom, region.bottom);
+      } else {
+        merged.push(region);
+      }
+    });
+    return merged;
+  }
+
   function cleanupExportRoot(root) {
     if (root && root.parentNode) {
       root.parentNode.removeChild(root);
     }
   }
 
-  function waitForExportReady() {
+  function waitForExportReady(root) {
     var fontReady = document.fonts && document.fonts.ready
       ? document.fonts.ready.catch(function() {})
       : Promise.resolve();
 
-    return fontReady.then(function() {
+    var imagesReady = Promise.all(Array.prototype.map.call(root.querySelectorAll('img'), function(img) {
+      if (img.complete) {
+        return img.naturalWidth > 0 ? Promise.resolve() : Promise.reject(new Error('文档图片加载失败'));
+      }
+      return new Promise(function(resolve, reject) {
+        var timer = setTimeout(function() { finish(new Error('等待文档图片超时')); }, 15000);
+        function finish(error) {
+          clearTimeout(timer);
+          img.removeEventListener('load', loaded);
+          img.removeEventListener('error', failed);
+          if (error) reject(error); else resolve();
+        }
+        function loaded() { finish(); }
+        function failed() { finish(new Error('文档图片加载失败')); }
+        img.addEventListener('load', loaded, { once: true });
+        img.addEventListener('error', failed, { once: true });
+      });
+    }));
+    return Promise.all([fontReady, imagesReady]).then(function() {
       return new Promise(function(resolve) {
         requestAnimationFrame(function() {
           requestAnimationFrame(resolve);
@@ -157,25 +230,111 @@
     });
   }
 
-  function renderCanvas(root) {
+  function renderCanvas(root, pageBackground) {
     var width = Math.max(root.scrollWidth, root.offsetWidth, 960);
     var height = Math.max(root.scrollHeight, root.offsetHeight, 1);
+    var background = pageBackground || getExportPageBackground(root);
 
     return window.html2canvas(root, {
       scale: 2,
       useCORS: true,
       allowTaint: true,
-      backgroundColor: '#ffffff',
+      backgroundColor: 'rgb(' + background.r + ', ' + background.g + ', ' + background.b + ')',
       logging: false,
       width: width,
       height: height,
-      windowWidth: width,
-      windowHeight: height,
+      // Keep vw/vh styles and media queries identical to the measured DOM.
+      windowWidth: window.innerWidth,
+      windowHeight: window.innerHeight,
       scrollX: 0,
       scrollY: 0,
     });
   }
 
+  function parseCssColor(value) {
+    var color = String(value || '').trim().toLowerCase();
+    if (!color || color === 'transparent') return null;
+
+    if (color.charAt(0) === '#') {
+      var hex = color.slice(1);
+      if (hex.length === 3 || hex.length === 4) {
+        hex = hex.split('').map(function(part) { return part + part; }).join('');
+      }
+      if (hex.length === 6 || hex.length === 8 && /^[0-9a-f]+$/.test(hex)) {
+        var hasAlpha = hex.length === 8;
+        if (!hasAlpha && !/^[0-9a-f]+$/.test(hex)) return null;
+        return {
+          r: parseInt(hex.slice(0, 2), 16),
+          g: parseInt(hex.slice(2, 4), 16),
+          b: parseInt(hex.slice(4, 6), 16),
+          alpha: hasAlpha ? parseInt(hex.slice(6, 8), 16) / 255 : 1,
+        };
+      }
+      return null;
+    }
+
+    var rgb = color.match(/^rgba?\(\s*([^,]+),\s*([^,]+),\s*([^,)]+)(?:,\s*([^)]+))?\s*\)$/);
+    if (!rgb) return null;
+
+    function channel(value) {
+      var parsed = parseFloat(value);
+      if (!Number.isFinite(parsed)) return null;
+      if (String(value).indexOf('%') !== -1) parsed = parsed * 2.55;
+      return Math.max(0, Math.min(255, Math.round(parsed)));
+    }
+
+    var red = channel(rgb[1]);
+    var green = channel(rgb[2]);
+    var blue = channel(rgb[3]);
+    var alpha = rgb[4] === undefined ? 1 : parseFloat(rgb[4]);
+    if (red === null || green === null || blue === null || !Number.isFinite(alpha)) return null;
+
+    return {
+      r: red,
+      g: green,
+      b: blue,
+      alpha: Math.max(0, Math.min(1, alpha)),
+    };
+  }
+
+  function readComputedColor(style, property) {
+    if (!style) return null;
+    var value = property.indexOf('--') === 0 && typeof style.getPropertyValue === 'function'
+      ? style.getPropertyValue(property)
+      : style[property] || (typeof style.getPropertyValue === 'function' ? style.getPropertyValue(property) : '');
+    return parseCssColor(value);
+  }
+
+  function withoutAlpha(color) {
+    return { r: color.r, g: color.g, b: color.b };
+  }
+
+  function blendColors(foreground, background) {
+    return {
+      r: Math.round(foreground.r * foreground.alpha + background.r * (1 - foreground.alpha)),
+      g: Math.round(foreground.g * foreground.alpha + background.g * (1 - foreground.alpha)),
+      b: Math.round(foreground.b * foreground.alpha + background.b * (1 - foreground.alpha)),
+    };
+  }
+
+  function getExportPageBackground(root) {
+    var getComputedStyle = typeof window.getComputedStyle === 'function'
+      ? window.getComputedStyle.bind(window)
+      : null;
+    var rootStyle = getComputedStyle ? getComputedStyle(root) : null;
+    var bodyStyle = getComputedStyle && document.body ? getComputedStyle(document.body) : null;
+    var themeSurface = readComputedColor(rootStyle, '--doc-surface-raised')
+      || readComputedColor(rootStyle, '--linear-bg')
+      || readComputedColor(bodyStyle, '--linear-bg')
+      || readComputedColor(bodyStyle, 'backgroundColor')
+      || parseCssColor('#ffffff');
+    var rootBackground = readComputedColor(rootStyle, 'backgroundColor');
+
+    if (!rootBackground || rootBackground.alpha === 0) return withoutAlpha(themeSurface);
+    if (rootBackground.alpha < 1) return blendColors(rootBackground, themeSurface);
+    return withoutAlpha(rootBackground);
+  }
+
   function getCanvasContext(canvas) {
     return canvas.getContext('2d', { willReadFrequently: true }) || canvas.getContext('2d');
   }
@@ -313,7 +472,15 @@
     return Math.max(minBreakY - startY, searchStartY + bestRow - startY);
   }
 
-  function addCanvasToPdf(pdf, canvas, margin, blockBreakpoints, watermark) {
+  function fillPdfPageBackground(pdf, pageBackground) {
+    if (!pageBackground || typeof pdf.setFillColor !== 'function' || typeof pdf.rect !== 'function') return;
+    var pageWidth = pdf.internal.pageSize.getWidth();
+    var pageHeight = pdf.internal.pageSize.getHeight();
+    pdf.setFillColor(pageBackground.r, pageBackground.g, pageBackground.b);
+    pdf.rect(0, 0, pageWidth, pageHeight, 'F');
+  }
+
+  function addCanvasToPdf(pdf, canvas, margin, blockBreakpoints, watermark, protectedRegions, pageBackground) {
     var pageWidth = pdf.internal.pageSize.getWidth();
     var pageHeight = pdf.internal.pageSize.getHeight();
     var usableWidth = pageWidth - margin * 2;
@@ -338,6 +505,16 @@
           sliceHeight = findBestPageBreak(canvas, sourceCtx, offsetY, pageCanvasHeight);
         }
       }
+      sliceHeight = Math.min(sliceHeight, remainingHeight, pageCanvasHeight);
+      var sliceEnd = offsetY + sliceHeight;
+      (protectedRegions || []).forEach(function(region) {
+        if (region.top < sliceEnd && region.bottom > sliceEnd) {
+          // Move a fitting image to the next page even if this leaves whitespace.
+          // A taller-than-page image receives one whole, scaled PDF page.
+          sliceEnd = region.top > offsetY ? region.top : Math.min(region.bottom, canvas.height);
+        }
+      });
+      sliceHeight = Math.max(1, sliceEnd - offsetY);
       var pageCanvas = document.createElement('canvas');
       pageCanvas.width = canvas.width;
       pageCanvas.height = sliceHeight;
@@ -362,7 +539,7 @@
           context,
           pageCanvas.width,
           pageCanvas.height,
-          pageCanvasHeight,
+          Math.max(pageCanvasHeight, sliceHeight),
           watermark.text,
         );
       }
@@ -370,14 +547,16 @@
       if (pageIndex > 0) {
         pdf.addPage();
       }
+      fillPdfPageBackground(pdf, pageBackground);
 
-      var imageHeight = (sliceHeight * usableWidth) / canvas.width;
+      var imageWidth = Math.min(usableWidth, (usableHeight * canvas.width) / sliceHeight);
+      var imageHeight = (sliceHeight * imageWidth) / canvas.width;
       pdf.addImage(
         pageCanvas.toDataURL('image/png'),
         'PNG',
+        margin + (usableWidth - imageWidth) / 2,
         margin,
-        margin,
-        usableWidth,
+        imageWidth,
         imageHeight,
         undefined,
         'FAST'
@@ -586,13 +765,16 @@
           format: 'a4',
           compress: true,
         });
-        return waitForExportReady()
+        var pageBackground = getExportPageBackground(exportRoot);
+        return waitForExportReady(exportRoot)
           .then(function() {
-            return renderCanvas(exportRoot);
+            return renderCanvas(exportRoot, pageBackground);
           })
           .then(function(canvas) {
-            var blockBreakpoints = collectBlockBreakpoints(exportRoot, canvas.height / Math.max(exportRoot.scrollHeight, 1));
-            addCanvasToPdf(pdf, canvas, margin, blockBreakpoints, watermark);
+            var canvasScale = canvas.height / Math.max(exportRoot.scrollHeight, 1);
+            var blockBreakpoints = collectBlockBreakpoints(exportRoot, canvasScale);
+            var protectedRegions = collectProtectedRegions(exportRoot, canvasScale);
+            addCanvasToPdf(pdf, canvas, margin, blockBreakpoints, watermark, protectedRegions, pageBackground);
             pdf.save(getExportFileName() + '.pdf');
           })
           .finally(function() {

package/server/static/js/core/doc-search.js

@@ -0,0 +1,424 @@
+(function() {
+  'use strict';
+
+  var MAX_RESULTS = 12;
+  var SNIPPET_LENGTH = 160;
+  var SEARCH_INDEX_PATH = '/search-index.json';
+  var state = {
+    index: null,
+    indexPromise: null,
+    modal: null,
+    trigger: null,
+    lastFocus: null,
+    results: [],
+    selectedIndex: -1,
+  };
+
+  function getAssetUrl(path) {
+    var base = document.querySelector('base');
+    if (base && base.getAttribute('href')) {
+      return base.getAttribute('href').replace(/\/?$/, '/') + path.replace(/^\//, '');
+    }
+    return path;
+  }
+
+  function isStaticSite() {
+    return document.documentElement.getAttribute('data-docnest-static') === 'true';
+  }
+
+  function normalizeText(value) {
+    var text = String(value || '');
+    if (typeof text.normalize === 'function') text = text.normalize('NFKC');
+    return text.trim().toLocaleLowerCase();
+  }
+
+  function getQueryTerms(query) {
+    return normalizeText(query).split(/\s+/).filter(function(term) { return term; });
+  }
+
+  function countOccurrences(text, term) {
+    var count = 0;
+    var offset = 0;
+    while (offset < text.length) {
+      var found = text.indexOf(term, offset);
+      if (found === -1) break;
+      count += 1;
+      offset = found + Math.max(term.length, 1);
+    }
+    return count;
+  }
+
+  function getDocumentFields(document) {
+    var title = normalizeText(document.title);
+    var directory = normalizeText(document.directory);
+    var path = normalizeText(document.path);
+    var headings = normalizeText(Array.isArray(document.headings) ? document.headings.join(' ') : '');
+    var text = normalizeText(document.text);
+    return {
+      title: title,
+      directory: directory,
+      path: path,
+      headings: headings,
+      text: text,
+      all: [title, directory, path, headings, text].join('\n'),
+    };
+  }
+
+  function scoreDocument(document, query, terms) {
+    var fields = getDocumentFields(document);
+    for (var i = 0; i < terms.length; i += 1) {
+      if (!fields.all.includes(terms[i])) return null;
+    }
+
+    var score = 0;
+    terms.forEach(function(term) {
+      if (fields.title.includes(term)) score += 120;
+      if (fields.headings.includes(term)) score += 70;
+      if (fields.directory.includes(term)) score += 40;
+      if (fields.path.includes(term)) score += 30;
+      score += Math.min(countOccurrences(fields.text, term), 8) * 4;
+    });
+
+    var phrase = normalizeText(query);
+    if (phrase.length > 1 && fields.all.includes(phrase)) score += 60;
+    return score;
+  }
+
+  function searchDocuments(query) {
+    var terms = getQueryTerms(query);
+    if (!state.index || terms.length === 0) return [];
+
+    return state.index.map(function(document, index) {
+      return {
+        document: document,
+        index: index,
+        score: scoreDocument(document, query, terms),
+      };
+    }).filter(function(result) {
+      return result.score !== null;
+    }).sort(function(left, right) {
+      if (right.score !== left.score) return right.score - left.score;
+      return left.index - right.index;
+    });
+  }
+
+  function getSnippet(document, terms) {
+    var text = String(document.text || '').replace(/\s+/g, ' ').trim();
+    if (!text) text = String((document.headings || []).join(' ')).trim();
+    if (!text) return '';
+
+    var normalized = normalizeText(text);
+    var matchIndex = -1;
+    terms.forEach(function(term) {
+      var index = normalized.indexOf(term);
+      if (index !== -1 && (matchIndex === -1 || index < matchIndex)) matchIndex = index;
+    });
+
+    if (matchIndex === -1) matchIndex = 0;
+    var start = Math.max(0, matchIndex - 54);
+    var end = Math.min(text.length, start + SNIPPET_LENGTH);
+    if (end - start < SNIPPET_LENGTH && start > 0) {
+      start = Math.max(0, end - SNIPPET_LENGTH);
+    }
+    return (start > 0 ? '…' : '') + text.slice(start, end) + (end < text.length ? '…' : '');
+  }
+
+  function escapeRegExp(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  function appendHighlightedText(container, text, terms) {
+    var value = String(text || '');
+    var uniqueTerms = Array.from(new Set(terms.filter(function(term) { return term; })))
+      .sort(function(left, right) { return right.length - left.length; });
+    if (uniqueTerms.length === 0) {
+      container.appendChild(document.createTextNode(value));
+      return;
+    }
+
+    var pattern = new RegExp('(' + uniqueTerms.map(escapeRegExp).join('|') + ')', 'gi');
+    var cursor = 0;
+    value.replace(pattern, function(match, ignored, offset) {
+      if (offset > cursor) container.appendChild(document.createTextNode(value.slice(cursor, offset)));
+      var mark = document.createElement('mark');
+      mark.textContent = match;
+      container.appendChild(mark);
+      cursor = offset + match.length;
+      return match;
+    });
+    if (cursor < value.length) container.appendChild(document.createTextNode(value.slice(cursor)));
+  }
+
+  function encodeDocumentPath(documentPath) {
+    return String(documentPath || '').split('/').map(function(segment) {
+      return encodeURIComponent(segment);
+    }).join('/');
+  }
+
+  function buildDocumentUrl(documentPath) {
+    var normalizedPath = String(documentPath || '').replace(/\\/g, '/').replace(/^\/+/, '');
+    if (isStaticSite()) {
+      var staticPath = normalizedPath.replace(/\.(md|markdown)$/i, '.html');
+      return getAssetUrl('/doc/' + encodeDocumentPath(staticPath));
+    }
+    return getAssetUrl('/doc?path=' + encodeURIComponent(normalizedPath));
+  }
+
+  function setStatus(message) {
+    if (state.modal && state.modal.status) state.modal.status.textContent = message;
+  }
+
+  function createEmptyState(message) {
+    var empty = document.createElement('div');
+    empty.className = 'doc-search-empty';
+    empty.textContent = message;
+    return empty;
+  }
+
+  function setSelectedIndex(index) {
+    if (!state.modal || state.results.length === 0) {
+      state.selectedIndex = -1;
+      return;
+    }
+    state.selectedIndex = Math.max(0, Math.min(index, state.results.length - 1));
+    var options = state.modal.results.querySelectorAll('.doc-search-result');
+    options.forEach(function(option, optionIndex) {
+      var selected = optionIndex === state.selectedIndex;
+      option.classList.toggle('is-selected', selected);
+      option.setAttribute('aria-selected', String(selected));
+    });
+    var selectedOption = options[state.selectedIndex];
+    if (selectedOption) {
+      state.modal.input.setAttribute('aria-activedescendant', selectedOption.id);
+      selectedOption.scrollIntoView({ block: 'nearest' });
+    }
+  }
+
+  function createResult(result, resultIndex, terms) {
+    var documentData = result.document;
+    var option = document.createElement('a');
+    option.className = 'doc-search-result';
+    option.id = 'doc-search-result-' + resultIndex;
+    option.href = buildDocumentUrl(documentData.path);
+    option.setAttribute('role', 'option');
+    option.setAttribute('aria-selected', 'false');
+
+    var title = document.createElement('div');
+    title.className = 'doc-search-result__title';
+    appendHighlightedText(title, documentData.title || documentData.path, terms);
+
+    var pathLabel = document.createElement('div');
+    pathLabel.className = 'doc-search-result__path';
+    appendHighlightedText(pathLabel, documentData.path, terms);
+
+    var snippet = document.createElement('p');
+    snippet.className = 'doc-search-result__snippet';
+    appendHighlightedText(snippet, getSnippet(documentData, terms), terms);
+
+    var arrow = document.createElement('span');
+    arrow.className = 'doc-search-result__arrow';
+    arrow.setAttribute('aria-hidden', 'true');
+    arrow.textContent = '↗';
+
+    option.appendChild(title);
+    option.appendChild(pathLabel);
+    if (snippet.textContent) option.appendChild(snippet);
+    option.appendChild(arrow);
+    option.addEventListener('mouseenter', function() { setSelectedIndex(resultIndex); });
+    option.addEventListener('click', function(event) {
+      event.preventDefault();
+      closeSearch();
+      var url = buildDocumentUrl(documentData.path);
+      if (!isStaticSite() && typeof window.navigateToDoc === 'function') {
+        window.navigateToDoc(url);
+      } else {
+        window.location.href = url;
+      }
+    });
+    return option;
+  }
+
+  function renderResults() {
+    if (!state.modal) return;
+    var query = state.modal.input.value.trim();
+    state.modal.results.textContent = '';
+    state.results = [];
+    state.selectedIndex = -1;
+
+    if (!query) {
+      setStatus('输入标题、目录或正文关键词');
+      state.modal.results.appendChild(createEmptyState('支持中文关键词、英文词组和文档路径搜索'));
+      return;
+    }
+
+    var terms = getQueryTerms(query);
+    var matches = searchDocuments(query);
+    if (matches.length === 0) {
+      setStatus('没有找到匹配的文档');
+      state.modal.results.appendChild(createEmptyState('换个关键词试试，或检查目录名称是否完整'));
+      return;
+    }
+
+    state.results = matches.slice(0, MAX_RESULTS);
+    setStatus(matches.length > MAX_RESULTS
+      ? '找到 ' + matches.length + ' 篇文档，显示最相关的 ' + MAX_RESULTS + ' 篇'
+      : '找到 ' + matches.length + ' 篇文档');
+    state.results.forEach(function(result, index) {
+      state.modal.results.appendChild(createResult(result, index, terms));
+    });
+    setSelectedIndex(0);
+  }
+
+  function createModal() {
+    var overlay = document.createElement('div');
+    overlay.className = 'doc-search-modal';
+    overlay.id = 'doc-search-modal';
+    overlay.hidden = true;
+    overlay.setAttribute('aria-hidden', 'true');
+    overlay.innerHTML = [
+      '<div class="doc-search-modal__panel" role="dialog" aria-modal="true" aria-labelledby="doc-search-title" aria-describedby="doc-search-status">',
+        '<div class="doc-search-modal__topline">',
+          '<span class="doc-search-modal__eyebrow" id="doc-search-title">搜索文档</span>',
+          '<button type="button" class="doc-search-modal__close" aria-label="关闭搜索">×</button>',
+        '</div>',
+        '<div class="doc-search-input-wrap">',
+          '<span class="doc-search-input-icon" aria-hidden="true">⌕</span>',
+          '<input class="doc-search-input" type="search" autocomplete="off" spellcheck="false" placeholder="搜索标题、目录、正文或路径" aria-label="搜索文档" aria-controls="doc-search-results">',
+          '<kbd class="doc-search-input-key">Esc</kbd>',
+        '</div>',
+        '<div class="doc-search-status" id="doc-search-status" role="status" aria-live="polite"></div>',
+        '<div class="doc-search-results" id="doc-search-results" role="listbox" aria-label="搜索结果"></div>',
+        '<div class="doc-search-hint"><span>↑↓ 选择</span><span>Enter 打开</span><span>Esc 关闭</span></div>',
+      '</div>',
+    ].join('');
+
+    var modal = {
+      overlay: overlay,
+      input: overlay.querySelector('.doc-search-input'),
+      status: overlay.querySelector('.doc-search-status'),
+      results: overlay.querySelector('.doc-search-results'),
+      close: overlay.querySelector('.doc-search-modal__close'),
+    };
+    modal.input.addEventListener('input', renderResults);
+    modal.close.addEventListener('click', closeSearch);
+    overlay.addEventListener('click', function(event) {
+      if (event.target === overlay) closeSearch();
+    });
+    document.body.appendChild(overlay);
+    state.modal = modal;
+    return modal;
+  }
+
+  function loadSearchIndex() {
+    if (state.index) return Promise.resolve(state.index);
+    if (state.indexPromise) return state.indexPromise;
+
+    state.indexPromise = fetch(getAssetUrl(SEARCH_INDEX_PATH), {
+      credentials: 'same-origin',
+      headers: { Accept: 'application/json' },
+    }).then(function(response) {
+      if (!response.ok) throw new Error('搜索索引请求失败：' + response.status);
+      return response.json();
+    }).then(function(payload) {
+      if (!payload || !Array.isArray(payload.documents)) {
+        throw new Error('搜索索引格式无效');
+      }
+      state.index = payload.documents.filter(function(documentData) {
+        return documentData && typeof documentData.path === 'string';
+      });
+      return state.index;
+    }).catch(function(error) {
+      state.indexPromise = null;
+      throw error;
+    });
+    return state.indexPromise;
+  }
+
+  function openSearch() {
+    if (!state.modal) createModal();
+    state.lastFocus = document.activeElement;
+    state.modal.overlay.hidden = false;
+    state.modal.overlay.setAttribute('aria-hidden', 'false');
+    document.body.classList.add('doc-search-open');
+    state.modal.input.disabled = true;
+    state.modal.input.value = '';
+    state.modal.results.textContent = '';
+    setStatus('正在加载文档索引…');
+    window.requestAnimationFrame(function() { state.modal.input.focus(); });
+
+    loadSearchIndex().then(function() {
+      if (state.modal.overlay.hidden) return;
+      state.modal.input.disabled = false;
+      renderResults();
+      state.modal.input.focus();
+    }).catch(function() {
+      if (state.modal.overlay.hidden) return;
+      state.modal.input.disabled = true;
+      setStatus('搜索索引加载失败，请刷新页面后重试');
+      state.modal.results.appendChild(createEmptyState('当前无法读取文档索引'));
+    });
+  }
+
+  function closeSearch() {
+    if (!state.modal || state.modal.overlay.hidden) return;
+    state.modal.overlay.hidden = true;
+    state.modal.overlay.setAttribute('aria-hidden', 'true');
+    document.body.classList.remove('doc-search-open');
+    if (state.lastFocus && typeof state.lastFocus.focus === 'function') state.lastFocus.focus();
+  }
+
+  function moveSelection(delta) {
+    if (!state.results.length) return;
+    setSelectedIndex(state.selectedIndex + delta);
+  }
+
+  function onKeyDown(event) {
+    if (event.isComposing) return;
+    if ((event.metaKey || event.ctrlKey) && String(event.key).toLowerCase() === 'k') {
+      event.preventDefault();
+      openSearch();
+      return;
+    }
+    if (!state.modal || state.modal.overlay.hidden) return;
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      closeSearch();
+    } else if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      moveSelection(1);
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      moveSelection(-1);
+    } else if (event.key === 'Enter' && state.selectedIndex >= 0 && state.results[state.selectedIndex]) {
+      event.preventDefault();
+      var selected = state.results[state.selectedIndex].document;
+      closeSearch();
+      var url = buildDocumentUrl(selected.path);
+      if (!isStaticSite() && typeof window.navigateToDoc === 'function') {
+        window.navigateToDoc(url);
+      } else {
+        window.location.href = url;
+      }
+    }
+  }
+
+  function init() {
+    var config = window.DOCNEST_CONFIG || {};
+    if (config.restrictedMode === true) return;
+    var trigger = document.getElementById('doc-search-trigger');
+    if (!trigger) return;
+
+    state.trigger = trigger;
+    trigger.addEventListener('click', openSearch);
+    var shortcut = trigger.querySelector('.doc-search-shortcut');
+    var isMac = /Mac|iPhone|iPad|iPod/i.test((window.navigator && window.navigator.platform) || '');
+    if (shortcut) shortcut.textContent = isMac ? '⌘ K' : 'Ctrl K';
+    document.addEventListener('keydown', onKeyDown);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/server/views/partials/header.ejs

@@ -13,6 +13,13 @@
     </div>
     <div class="header-meta">
       <div class="header-actions">
+        <% if (!docsRestrictedMode) { %>
+          <button type="button" id="doc-search-trigger" class="header-action-btn doc-search-trigger" aria-haspopup="dialog" aria-controls="doc-search-modal" title="搜索文档（⌘K / Ctrl K）">
+            <span class="doc-search-icon" aria-hidden="true">⌕</span>
+            <span class="header-action-text">搜索文档</span>
+            <kbd class="doc-search-shortcut" aria-label="打开搜索快捷键">⌘ K</kbd>
+          </button>
+        <% } %>
         <% if (typeof showPrintButton !== 'undefined' && showPrintButton && !docsRestrictedMode) { %>
           <button type="button" id="print-doc-btn" class="header-action-btn print-btn" title="打印当前文章">
             <span class="print-icon">🖨️</span>
@@ -58,6 +65,9 @@
     </div>
   </div>
 </header>
+<% if (!docsRestrictedMode) { %>
+  <script src="/static/js/core/doc-search.js?v=<%= typeof assetVersion !== 'undefined' ? assetVersion : 'dev' %>"></script>
+<% } %>
 <% if (docsAuthEnabled) { %>
   <script src="/static/js/core/auth.js?v=<%= typeof assetVersion !== 'undefined' ? assetVersion : 'dev' %>"></script>
 <% } %>