docnest 0.1.24 → 0.1.26

package/README.md

@@ -58,20 +58,31 @@ export default defineConfig({
 
 ### 文档搜索
 
-普通阅读模式下，页面顶部提供文档搜索入口，也可以使用 `⌘K`（macOS）或
+整理目录时可以把文档移动到原目录下的分类文件夹。旧地址会在原目录子树中按完全相同的文件名查找，只有唯一匹配时才跳转；重名、目录不存在或读取失败时保留 404，避免打开错误的文档。直接访问现有路径始终优先。
+
+文档搜索默认开启，与 `restrictedMode` 独立。页面顶部提供搜索入口，也可以使用 `⌘K`（macOS）或
 `Ctrl K`（Windows/Linux）打开。搜索索引在首次打开搜索时才加载，覆盖文档标题、目录路径、标题层级、正文和代码块；中文按连续字符匹配，英文和带空格的查询按多个词匹配。结果按标题、目录和正文命中位置综合排序，并显示安全的文本摘要。
 
 搜索完全基于宿主项目自己的 Markdown 内容，不依赖 Algolia 或其他外部服务。动态服务通过同源
 `/search-index.json` 提供索引；静态站点需要把同一份响应保存为站点根目录的
 `search-index.json`，并保留页面上的静态站点标记，让结果链接指向 `/doc/<path>.html`。
-受限模式不生成搜索索引，也不显示搜索入口，避免摘要绕过阅读限制。
+只有 `search.enabled: false` 才关闭搜索入口、快捷键与索引接口；省略该项时包括受限模式在内均默认开启。索引继续经过原有授权检查；当前实现将可检索的 Markdown 文本索引交给已授权浏览器处理，不索引嵌入 HTML 的正文。
+
+```js
+export default defineConfig({
+  search: { enabled: true },
+  restrictedMode: true,
+})
+```
+
+`search.enabled` 只接受布尔值。使用 CLI 时由配置文件解析并传递给运行时；直接嵌入 `docnest/server` 时可通过 `DOCS_SEARCH_ENABLED=true|false` 设置，缺省为开启。
 
 搜索框为空时显示最近搜索：仅记录有结果的关键词，去重后保留最近 10 条，点击即可再次搜索。
 历史保存在当前浏览器，按 `site.storageKeyPrefix` 隔离；不上传服务器。
 
 多空间托管场景可设置 `DOCS_ALLOW_RAW_HTML=false`，把 Markdown 中的原始 HTML 显示为文本，避免文档内脚本取得宿主页面权限；Markdown 语法与 Mermaid 不受影响。默认保留原始 HTML 兼容行为。
 
-PDF、页面水印和图表外带能力由一个开关统一控制，默认使用普通阅读模式：
+复制、导出与页面水印由 `restrictedMode` 控制；搜索独立配置，图表放大查看始终可用：
 
 ```js
 export default defineConfig({
@@ -80,9 +91,9 @@ export default defineConfig({
 ```
 
 - `restrictedMode: false`：显示打印和 PDF 导出，允许 Mermaid 图下载与大图查看。导出 PDF 时会弹出本次水印设置，可选择是否添加并自定义文案；默认文案为 `site.title`，不会写回配置。
-- `restrictedMode: true`：隐藏打印和 PDF 导出入口且不加载导出模块；使用 `site.title` 作为固定水印，禁止文字选择、复制、剪切和拖拽，并隐藏 Mermaid 下载与大图查看入口。Mermaid 仍会在正文中正常渲染。
+- `restrictedMode: true`：隐藏打印和 PDF 导出入口且不加载导出模块；使用 `site.title` 作为固定水印，禁止文字选择、复制、剪切和拖拽，并隐藏 Mermaid 复制与下载入口。Mermaid 可正常渲染、放大、缩小、重置和全屏查看，查看器内保留水印。
 
-受限模式只移除 DocNest 提供的页面入口和脚本，不承诺对浏览器开发者工具或系统级截图提供绝对防护。
+图表查看没有启用／禁用配置项。受限模式只限制 DocNest 提供的复制和导出入口，不承诺对浏览器开发者工具或系统级截图提供绝对防护。
 
 页面水印使用 4% 透明度，保持可辨识而不遮挡正文和图表。Mermaid 代码围栏按独立图表渲染，不继承普通代码块的等宽字体；节点内的 HTML 换行与图表字体测量保持一致。
 

package/dist/cli.js

@@ -63,6 +63,7 @@ function exposeConfig(config) {
     process.env.DOCS_THEME_MODE_DEFAULT = config.appearance.defaultMode;
     process.env.DOCS_THEME_ENABLED = JSON.stringify(config.appearance.enabledThemes);
     process.env.DOCS_RESTRICTED_MODE = String(config.restrictedMode);
+    process.env.DOCS_SEARCH_ENABLED = String(config.search.enabled);
     process.env.DOCS_HOST = config.server.host;
     process.env.DOCS_PORT_START = String(config.server.port);
     process.env.DOCS_WATCH_ENABLED = String(config.server.watch);

package/dist/config.d.ts

@@ -14,6 +14,10 @@ export type DocNestConfig = {
     navigation?: {
         rootDirectoryOrder?: string[];
     };
+    search?: {
+        /** Search is enabled by default, independently of restrictedMode. */
+        enabled?: boolean;
+    };
     appearance?: {
         defaultTheme?: DocNestThemeName;
         defaultMode?: DocNestColorMode;
@@ -38,8 +42,8 @@ export type DocNestConfig = {
         sessionTtlMinutes?: number;
     };
     /**
-     * Restrict the reading experience to in-browser viewing only.
-     * Restricted mode also enables the fixed site-title watermark.
+     * Restrict copying and export, and enable the fixed site-title watermark.
+     * Search and diagram viewing are reading capabilities and remain independent.
      */
     restrictedMode?: boolean;
 };
@@ -49,6 +53,9 @@ export type ResolvedDocNestConfig = Required<DocNestConfig> & {
     docsDir: string;
     site: Required<NonNullable<DocNestConfig['site']>>;
     navigation: Required<NonNullable<DocNestConfig['navigation']>>;
+    search: {
+        enabled: boolean;
+    };
     appearance: Required<NonNullable<DocNestConfig['appearance']>>;
     server: Required<NonNullable<DocNestConfig['server']>>;
     auth: {

package/dist/config.js

@@ -98,6 +98,11 @@ async function loadConfig(projectRoot = process.cwd()) {
     const projectName = await readProjectName(projectRoot);
     const site = userConfig.site ?? {};
     const navigation = userConfig.navigation ?? {};
+    const search = userConfig.search ?? {};
+    if (typeof search !== 'object' || Array.isArray(search) ||
+        (search.enabled !== undefined && typeof search.enabled !== 'boolean')) {
+        throw new Error('search.enabled must be a boolean');
+    }
     const appearance = userConfig.appearance ?? {};
     const server = userConfig.server ?? {};
     const auth = userConfig.auth ?? {};
@@ -117,6 +122,7 @@ async function loadConfig(projectRoot = process.cwd()) {
                 ? navigation.rootDirectoryOrder.filter((item) => typeof item === 'string')
                 : [],
         },
+        search: { enabled: search.enabled ?? true },
         appearance: resolveAppearance(appearance),
         server: {
             host: server.host?.trim() || '127.0.0.1',

package/dist/server.js

@@ -55,6 +55,11 @@ const DOCS_THEME_ENABLED = (() => {
     }
 })();
 const DOCS_RESTRICTED_MODE = process.env.DOCS_RESTRICTED_MODE === 'true';
+if (process.env.DOCS_SEARCH_ENABLED !== undefined &&
+    !['true', 'false'].includes(process.env.DOCS_SEARCH_ENABLED)) {
+    throw new Error('DOCS_SEARCH_ENABLED must be true or false');
+}
+const DOCS_SEARCH_ENABLED = process.env.DOCS_SEARCH_ENABLED !== 'false';
 const DOCS_PDF_ENABLED = !DOCS_RESTRICTED_MODE;
 const DOCS_PAGE_WATERMARK_TEXT = DOCS_TITLE;
 const DOCS_DIR = path.resolve(process.env.DOCS_ROOT || path.join(process.cwd(), 'docs'));
@@ -110,6 +115,7 @@ app.locals.docsThemeDefault = DOCS_THEME_DEFAULT;
 app.locals.docsThemeModeDefault = DOCS_THEME_MODE_DEFAULT;
 app.locals.docsThemeEnabled = DOCS_THEME_ENABLED;
 app.locals.docsRestrictedMode = DOCS_RESTRICTED_MODE;
+app.locals.docsSearchEnabled = DOCS_SEARCH_ENABLED;
 app.locals.docsPageWatermarkText = DOCS_PAGE_WATERMARK_TEXT;
 app.locals.docsAuthEnabled = BUILT_IN_AUTH_ENABLED;
 app.locals.docsAuthStorageKey = AUTH_CONFIG.localStorageKey || `${DOCS_STORAGE_KEY_PREFIX}:auth-passphrase`;
@@ -526,7 +532,7 @@ function invalidateSearchIndex() {
     searchIndexCache = null;
 }
 app.get('/search-index.json', async (req, res) => {
-    if (DOCS_RESTRICTED_MODE) {
+    if (!DOCS_SEARCH_ENABLED) {
         return res.status(404).json({ ok: false, error: '搜索功能已关闭。' });
     }
     try {
@@ -719,7 +725,10 @@ async function resolveDocPath(requestedPath) {
         if (await storageFileExists(resolvedPath)) {
             return { resolvedPath };
         }
-        return null;
+        // A document may have moved into a subdirectory during catalog cleanup.
+        // Resolve only an unambiguous filename inside its original directory.
+        const movedPath = await findFileInTree(resolvedDirPath, fileName);
+        return movedPath ? { resolvedPath: movedPath } : null;
     }
     // 如果只是文件名，尝试在整个文档目录中查找
     try {
@@ -733,29 +742,32 @@ async function resolveDocPath(requestedPath) {
     }
     return null;
 }
-// 在目录树中查找文件
-async function findFileInTree(dir, fileName, basePath = '') {
-    try {
-        const effectiveBasePath = basePath || dir || '';
-        const entries = await storageReadDir(effectiveBasePath);
+// Find one exact filename; ambiguity or an unreadable subtree must not redirect.
+async function findFileInTree(dir, fileName) {
+    const matches = [];
+    async function visit(basePath) {
+        const entries = await storageReadDir(basePath);
         for (const entry of entries) {
             if (entry.name.startsWith('.'))
                 continue;
-            const relativePath = joinDocPath(effectiveBasePath, entry.name);
+            const relativePath = joinDocPath(basePath, entry.name);
             if (entry.isDirectory) {
-                const found = await findFileInTree('', fileName, relativePath);
-                if (found)
-                    return found;
+                await visit(relativePath);
             }
             else if (entry.isFile && entry.name === fileName && entry.name.endsWith('.md')) {
-                return relativePath;
+                matches.push(relativePath);
             }
+            if (matches.length > 1)
+                return;
         }
     }
+    try {
+        await visit(dir || '');
+    }
     catch (e) {
-        // 忽略错误
+        return null;
     }
-    return null;
+    return matches.length === 1 ? matches[0] : null;
 }
 // 构建面包屑：基于文档路径
 async function buildBreadcrumbs(docPath) {

package/docnest.config.example.mjs

@@ -43,7 +43,10 @@ export default defineConfig({
     localStorageKey: 'my-project:auth-passphrase',
     sessionTtlMinutes: 24 * 60,
   },
-  // 受限阅读模式；默认关闭。开启后隐藏打印/PDF、Mermaid 下载和大图查看，
+  // 搜索默认开启，独立于受限模式；设为 false 时同时关闭入口和索引。
+  search: { enabled: true },
+  // 受限阅读模式；默认关闭。开启后隐藏打印/PDF 和 Mermaid 复制、下载，
   // 并使用 site.title 显示固定水印，同时禁止页面文字选择与复制。
+  // 图表放大查看始终可用，没有单独配置项。
   restrictedMode: false,
 })

package/package.json

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

package/server/static/css/themes.css

@@ -59,13 +59,7 @@ html.docnest-page-protected body [contenteditable="true"] {
   user-select: text !important;
 }
 
-/* Restricted mode keeps Mermaid inline but removes every affordance for opening
- * or exporting a larger copy of the diagram. */
-html.docnest-restricted .markdown-body .mermaid {
-  cursor: default;
-}
-
-html.docnest-restricted .markdown-body .mermaid::after,
+/* Diagram viewing is always available; restricted mode only hides export. */
 html.docnest-restricted .markdown-body .mermaid-download-btn {
   display: none !important;
 }

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

@@ -88,7 +88,10 @@
   function getAssetUrl(path) {
     var base = document.querySelector('base');
     if (base && base.getAttribute('href')) {
-      return base.getAttribute('href').replace(/\/?$/, '/') + path.replace(/^\//, '');
+      var prefix = base.getAttribute('href').replace(/\/?$/, '/');
+      // A mounting proxy may have already rewritten a root-relative link.
+      if (path.indexOf(prefix) === 0) return path;
+      return prefix + path.replace(/^\//, '');
     }
     return path;
   }
@@ -510,7 +513,7 @@
 
   function init() {
     var config = window.DOCNEST_CONFIG || {};
-    if (config.restrictedMode === true) return;
+    if (config.searchEnabled === false) return;
     var trigger = document.getElementById('doc-search-trigger');
     if (!trigger) return;
 

package/server/static/js/diagram/diagram-viewer.js

@@ -3,6 +3,7 @@ let currentZoom = 1;
 let defaultZoom = 1;
 let currentSvg = null;
 let isFullscreen = false;
+let viewerPreviousFocus = null;
 
 function isDocNestRestrictedMode() {
   return !!(window.DOCNEST_CONFIG && window.DOCNEST_CONFIG.restrictedMode === true);
@@ -44,45 +45,42 @@ function getDiagramIntrinsicDimensions(svgElement) {
 }
 
 function setupDiagramViewer() {
-  if (isDocNestRestrictedMode()) return;
   const diagrams = document.querySelectorAll('.markdown-body .mermaid');
   diagrams.forEach((diagram, index) => {
-    // 添加下载按钮
-    const downloadBtn = document.createElement('button');
-    downloadBtn.className = 'mermaid-download-btn';
-    downloadBtn.innerHTML = '⬇️ 下载';
-    downloadBtn.title = '下载图表';
-    downloadBtn.onclick = function(e) {
-      e.stopPropagation(); // 阻止触发点击查看大图
-      const svg = diagram.querySelector('svg');
-      if (svg) {
-        if (typeof showDownloadMenu === 'function') {
+    let downloadBtn = diagram.querySelector('.mermaid-download-btn');
+    if (isDocNestRestrictedMode()) {
+      if (downloadBtn) downloadBtn.remove();
+      downloadBtn = null;
+    } else if (!downloadBtn) {
+      downloadBtn = document.createElement('button');
+      downloadBtn.className = 'mermaid-download-btn';
+      downloadBtn.innerHTML = '⬇️ 下载';
+      downloadBtn.title = '下载图表';
+      downloadBtn.onclick = function(e) {
+        e.stopPropagation();
+        const svg = diagram.querySelector('svg');
+        if (svg && typeof showDownloadMenu === 'function') {
           showDownloadMenu(svg.cloneNode(true), `diagram-${index + 1}`);
         }
-      }
-    };
-    diagram.appendChild(downloadBtn);
-    
-    // 点击查看大图
-    diagram.addEventListener('click', function(e) {
-      // 如果点击的是下载按钮，不打开查看器
-      if (e.target === downloadBtn || downloadBtn.contains(e.target)) {
-        return;
-      }
+      };
+      diagram.appendChild(downloadBtn);
+    }
+
+    // Repeated renders must not accumulate viewer handlers or download buttons.
+    diagram.onclick = function(e) {
+      if (downloadBtn && (e.target === downloadBtn || downloadBtn.contains(e.target))) return;
       const svg = diagram.querySelector('svg');
-      if (svg) {
-        openDiagramViewer(svg.cloneNode(true));
-      }
-    });
+      if (svg) openDiagramViewer(svg.cloneNode(true));
+    };
   });
 }
 
 function openDiagramViewer(svgElement) {
-  if (isDocNestRestrictedMode()) return;
   const viewer = document.getElementById('diagram-viewer');
   const container = document.getElementById('diagram-viewer-svg-container');
   
   if (!viewer || !container) return;
+  viewerPreviousFocus = document.activeElement;
   
   // viewBox 才是图表的实际尺寸；不能把 Mermaid 的 width="100%" 解析成 100。
   const { width: originalWidth, height: originalHeight } = getDiagramIntrinsicDimensions(svgElement);
@@ -159,6 +157,7 @@ function openDiagramViewer(svgElement) {
   
   viewer.classList.add('show');
   document.body.style.overflow = 'hidden';
+  viewer.querySelector('.diagram-viewer-close')?.focus();
   
   // 重置全屏状态
   isFullscreen = false;
@@ -207,6 +206,8 @@ function closeDiagramViewer() {
   if (typeof removeModal === 'function') {
     removeModal('diagram-viewer');
   }
+  viewerPreviousFocus?.focus?.();
+  viewerPreviousFocus = null;
 }
 
 function resetDiagramZoom() {

package/server/views/doc.ejs

@@ -39,14 +39,14 @@
       </main>
     </div>
   </div>
+  <%- include('partials/diagram-viewer') %>
+  <!-- 按依赖顺序加载模块 -->
+  <script src="/static/js/utils/modal-stack.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-viewer.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-zoom.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-drag.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-controls.js?v=<%= assetVersion %>"></script>
   <% if (!docsRestrictedMode) { %>
-    <%- include('partials/diagram-viewer') %>
-    <!-- 按依赖顺序加载模块 -->
-    <script src="/static/js/utils/modal-stack.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-viewer.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-zoom.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-drag.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-controls.js?v=<%= assetVersion %>"></script>
     <script src="/static/js/diagram/diagram-download.js?v=<%= assetVersion %>"></script>
   <% } %>
   <script src="/static/js/utils/app.js?v=<%= assetVersion %>"></script>

package/server/views/index.ejs

@@ -30,14 +30,14 @@
       </main>
     </div>
   </div>
+  <%- include('partials/diagram-viewer') %>
+  <!-- 按依赖顺序加载模块 -->
+  <script src="/static/js/utils/modal-stack.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-viewer.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-zoom.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-drag.js?v=<%= assetVersion %>"></script>
+  <script src="/static/js/diagram/diagram-controls.js?v=<%= assetVersion %>"></script>
   <% if (!docsRestrictedMode) { %>
-    <%- include('partials/diagram-viewer') %>
-    <!-- 按依赖顺序加载模块 -->
-    <script src="/static/js/utils/modal-stack.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-viewer.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-zoom.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-drag.js?v=<%= assetVersion %>"></script>
-    <script src="/static/js/diagram/diagram-controls.js?v=<%= assetVersion %>"></script>
     <script src="/static/js/diagram/diagram-download.js?v=<%= assetVersion %>"></script>
   <% } %>
   <script src="/static/js/utils/app.js?v=<%= assetVersion %>"></script>

package/server/views/partials/appearance-head.ejs

@@ -4,6 +4,7 @@
     authStorageKey: <%- JSON.stringify(docsAuthStorageKey) %>,
     siteTitle: <%- JSON.stringify(docsTitle) %>,
     restrictedMode: <%= docsRestrictedMode ? 'true' : 'false' %>,
+    searchEnabled: <%= docsSearchEnabled ? 'true' : 'false' %>,
     storageKeyPrefix: <%- JSON.stringify(docsStorageKeyPrefix) %>,
     appearance: {
       defaultTheme: <%- JSON.stringify(docsThemeDefault) %>,

package/server/views/partials/diagram-viewer.ejs

@@ -1,15 +1,24 @@
 <!-- 图表查看器模态框 -->
-<div id="diagram-viewer" class="diagram-viewer">
+<div id="diagram-viewer" class="diagram-viewer" role="dialog" aria-modal="true" aria-label="图表查看器">
+  <% if (docsRestrictedMode) { %>
+    <div class="docnest-page-watermark" aria-hidden="true">
+      <% for (let index = 0; index < 12; index += 1) { %>
+        <span class="docnest-page-watermark__item"><%= docsPageWatermarkText %></span>
+      <% } %>
+    </div>
+  <% } %>
   <div class="diagram-viewer-content">
-    <button class="diagram-viewer-close" onclick="closeDiagramViewer()">×</button>
+    <button class="diagram-viewer-close" type="button" aria-label="关闭图表查看器" onclick="closeDiagramViewer()">×</button>
     <div class="diagram-viewer-controls">
       <button onclick="zoomDiagram('out')">缩小</button>
       <span class="zoom-info" id="zoom-info">100%</span>
       <button onclick="zoomDiagram('in')">放大</button>
       <button onclick="resetDiagramZoom()">重置</button>
       <button onclick="toggleFullscreen()" class="fullscreen-btn" id="fullscreen-btn">⛶ 全屏</button>
-      <button onclick="copyCurrentDiagram()" class="copy-btn">📋 复制</button>
-      <button onclick="downloadCurrentDiagram()" class="download-btn">⬇️ 下载</button>
+      <% if (!docsRestrictedMode) { %>
+        <button onclick="copyCurrentDiagram()" class="copy-btn">📋 复制</button>
+        <button onclick="downloadCurrentDiagram()" class="download-btn">⬇️ 下载</button>
+      <% } %>
     </div>
     <div id="diagram-viewer-svg-container" class="diagram-viewer-svg-container"></div>
   </div>

package/server/views/partials/header.ejs

@@ -1,5 +1,5 @@
 <header class="header">
-  <div class="header-content<%= !docsRestrictedMode ? ' header-content-with-search' : '' %>">
+  <div class="header-content<%= docsSearchEnabled ? ' header-content-with-search' : '' %>">
     <div class="header-title-group">
       <h1>
         <% if (docsLogo) { %><img class="brand-logo" src="<%= docsLogo %>" alt=""><% } else { %><span class="brand-fallback" aria-hidden="true"><span class="brand-fallback-emoji">📚</span><span class="brand-fallback-shape"></span></span><% } %>
@@ -11,7 +11,7 @@
         <p class="subtitle"><%= docsSubtitle %></p>
       <% } %>
     </div>
-        <% if (!docsRestrictedMode) { %>
+        <% if (docsSearchEnabled) { %>
           <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>
@@ -65,7 +65,7 @@
     </div>
   </div>
 </header>
-<% if (!docsRestrictedMode) { %>
+<% if (docsSearchEnabled) { %>
   <script src="/static/js/core/doc-search.js?v=<%= typeof assetVersion !== 'undefined' ? assetVersion : 'dev' %>"></script>
 <% } %>
 <% if (docsAuthEnabled) { %>