docnest 0.1.1 → 0.1.3

package/README.md

@@ -7,7 +7,7 @@ DocNest 是一个可复用的本地 Markdown 文档中心。文档内容归使
 在项目根目录执行：
 
 ```bash
-npm install docnest@0.1.0
+npm install docnest
 ```
 
 项目默认读取 `docs/`，可直接启动：
@@ -22,6 +22,40 @@ npx docnest serve
 
 复制 `docnest.config.example.mjs` 为项目根目录的 `docnest.config.mjs`，配置项目自己的标题、目录顺序、存储键前缀和 PDF 水印。
 
+### 外观主题
+
+DocNest 内置五套独立主题，主题风格与明暗模式分别选择、分别持久化：
+
+- `slate-modern`：中性灰阶与克制强调色构成的现代文档风格，也是默认主题
+- `editorial-atlas`：强调长文阅读与技术出版秩序
+- `precision-index`：高信息密度的工程索引
+- `archive-room`：带有档案与阅览室气质的纸张风格
+- `swiss-manual`：黑白网格与信号色构成的工程手册
+
+页面右上角可以选择主题风格；相邻的明暗模式按钮在 `auto → light → dark` 之间循环。偏好使用 `site.storageKeyPrefix` 隔离，因此同一域名下的多个 DocNest 实例不会互相覆盖。
+
+宿主项目可以设置默认外观，并限制用户可选主题：
+
+```js
+import { defineConfig } from 'docnest/config'
+
+export default defineConfig({
+  appearance: {
+    defaultTheme: 'editorial-atlas',
+    defaultMode: 'auto',
+    enabledThemes: [
+      'slate-modern',
+      'editorial-atlas',
+      'precision-index',
+      'archive-room',
+      'swiss-manual',
+    ],
+  },
+})
+```
+
+未配置 `appearance` 时使用 `slate-modern + auto`。旧配置中的 `current-docs` 会自动迁移到 `slate-modern`，正文视觉不会发生变化；旧版保存的 `markdown-theme` 明暗偏好也会自动迁移到新的项目级存储键。
+
 水印默认关闭。开启后，PDF 导出弹窗会读取配置文字，并允许本次导出临时修改；临时修改不会写回文件或浏览器存储。
 
 如需显式指定端口、文档目录或监听地址：

package/dist/cli.js

@@ -59,6 +59,9 @@ function exposeConfig(config) {
     process.env.DOCS_LOGO = config.site.logo;
     process.env.DOCS_STORAGE_KEY_PREFIX = config.site.storageKeyPrefix;
     process.env.DOCS_ROOT_DIRECTORY_ORDER = JSON.stringify(config.navigation.rootDirectoryOrder);
+    process.env.DOCS_THEME_DEFAULT = config.appearance.defaultTheme;
+    process.env.DOCS_THEME_MODE_DEFAULT = config.appearance.defaultMode;
+    process.env.DOCS_THEME_ENABLED = JSON.stringify(config.appearance.enabledThemes);
     process.env.DOCS_WATERMARK_ENABLED = String(config.export.watermark.enabled);
     process.env.DOCS_WATERMARK_TEXT = config.export.watermark.text;
     process.env.DOCS_HOST = config.server.host;

package/dist/config.d.ts

@@ -1,3 +1,8 @@
+export declare const DOCNEST_THEME_NAMES: readonly ["slate-modern", "editorial-atlas", "precision-index", "archive-room", "swiss-manual"];
+declare const DOCNEST_LEGACY_THEME_NAMES: readonly ["current-docs"];
+export declare const DOCNEST_COLOR_MODES: readonly ["auto", "light", "dark"];
+export type DocNestThemeName = (typeof DOCNEST_THEME_NAMES)[number] | (typeof DOCNEST_LEGACY_THEME_NAMES)[number];
+export type DocNestColorMode = (typeof DOCNEST_COLOR_MODES)[number];
 export type DocNestConfig = {
     docsDir?: string;
     site?: {
@@ -9,6 +14,11 @@ export type DocNestConfig = {
     navigation?: {
         rootDirectoryOrder?: string[];
     };
+    appearance?: {
+        defaultTheme?: DocNestThemeName;
+        defaultMode?: DocNestColorMode;
+        enabledThemes?: DocNestThemeName[];
+    };
     server?: {
         host?: string;
         port?: number;
@@ -28,9 +38,11 @@ export type ResolvedDocNestConfig = Required<DocNestConfig> & {
     docsDir: string;
     site: Required<NonNullable<DocNestConfig['site']>>;
     navigation: Required<NonNullable<DocNestConfig['navigation']>>;
+    appearance: Required<NonNullable<DocNestConfig['appearance']>>;
     server: Required<NonNullable<DocNestConfig['server']>>;
     export: {
         watermark: Required<NonNullable<NonNullable<DocNestConfig['export']>['watermark']>>;
     };
 };
 export declare function loadConfig(projectRoot?: string): Promise<ResolvedDocNestConfig>;
+export {};

package/dist/config.js

@@ -3,11 +3,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCNEST_COLOR_MODES = exports.DOCNEST_THEME_NAMES = void 0;
 exports.defineConfig = defineConfig;
 exports.loadConfig = loadConfig;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = require("node:url");
+exports.DOCNEST_THEME_NAMES = [
+    'slate-modern',
+    'editorial-atlas',
+    'precision-index',
+    'archive-room',
+    'swiss-manual',
+];
+const DOCNEST_LEGACY_THEME_NAMES = ['current-docs'];
+exports.DOCNEST_COLOR_MODES = ['auto', 'light', 'dark'];
 function defineConfig(config) {
     return config;
 }
@@ -31,6 +41,30 @@ function normalizePort(value, fallback) {
         return fallback;
     return port;
 }
+function normalizeThemeName(value) {
+    if (value === 'current-docs')
+        return 'slate-modern';
+    return typeof value === 'string' && exports.DOCNEST_THEME_NAMES.includes(value)
+        ? value
+        : null;
+}
+function isColorMode(value) {
+    return typeof value === 'string' && exports.DOCNEST_COLOR_MODES.includes(value);
+}
+function resolveAppearance(config) {
+    const defaultTheme = normalizeThemeName(config.defaultTheme) ?? 'slate-modern';
+    const configuredThemes = Array.isArray(config.enabledThemes)
+        ? Array.from(new Set(config.enabledThemes.map(normalizeThemeName).filter((theme) => theme !== null)))
+        : [...exports.DOCNEST_THEME_NAMES];
+    const enabledThemes = configuredThemes.length > 0 ? configuredThemes : [...exports.DOCNEST_THEME_NAMES];
+    if (!enabledThemes.includes(defaultTheme))
+        enabledThemes.unshift(defaultTheme);
+    return {
+        defaultTheme,
+        defaultMode: isColorMode(config.defaultMode) ? config.defaultMode : 'auto',
+        enabledThemes,
+    };
+}
 async function loadConfig(projectRoot = process.cwd()) {
     const configPath = node_path_1.default.join(projectRoot, DEFAULT_CONFIG_FILE);
     let userConfig = {};
@@ -46,6 +80,7 @@ async function loadConfig(projectRoot = process.cwd()) {
     const projectName = await readProjectName(projectRoot);
     const site = userConfig.site ?? {};
     const navigation = userConfig.navigation ?? {};
+    const appearance = userConfig.appearance ?? {};
     const server = userConfig.server ?? {};
     const watermark = userConfig.export?.watermark ?? {};
     const storageKeyPrefix = site.storageKeyPrefix?.trim() || `docnest:${projectName}`;
@@ -63,6 +98,7 @@ async function loadConfig(projectRoot = process.cwd()) {
                 ? navigation.rootDirectoryOrder.filter((item) => typeof item === 'string')
                 : [],
         },
+        appearance: resolveAppearance(appearance),
         server: {
             host: server.host?.trim() || '127.0.0.1',
             port: normalizePort(server.port, 3000),

package/dist/server.js

@@ -32,6 +32,27 @@ const DOCS_TITLE = process.env.DOCS_TITLE || 'DocNest';
 const DOCS_SUBTITLE = process.env.DOCS_SUBTITLE || '本地 Markdown 文档服务';
 const DOCS_LOGO = process.env.DOCS_LOGO || '';
 const DOCS_STORAGE_KEY_PREFIX = process.env.DOCS_STORAGE_KEY_PREFIX || 'docnest';
+const DOCS_THEME_NAMES = ['slate-modern', 'editorial-atlas', 'precision-index', 'archive-room', 'swiss-manual'];
+function normalizeThemeName(value) {
+    return value === 'current-docs' ? 'slate-modern' : value;
+}
+const configuredThemeDefault = normalizeThemeName(process.env.DOCS_THEME_DEFAULT || 'slate-modern');
+const DOCS_THEME_DEFAULT = DOCS_THEME_NAMES.includes(configuredThemeDefault)
+    ? configuredThemeDefault
+    : 'slate-modern';
+const DOCS_THEME_MODE_DEFAULT = process.env.DOCS_THEME_MODE_DEFAULT || 'auto';
+const DOCS_THEME_ENABLED = (() => {
+    try {
+        const parsed = JSON.parse(process.env.DOCS_THEME_ENABLED || '[]');
+        const normalized = Array.isArray(parsed)
+            ? [...new Set(parsed.map(normalizeThemeName).filter((item) => DOCS_THEME_NAMES.includes(item)))]
+            : [];
+        return normalized.length > 0 ? normalized : [...DOCS_THEME_NAMES];
+    }
+    catch {
+        return [...DOCS_THEME_NAMES];
+    }
+})();
 const DOCS_WATERMARK_ENABLED = process.env.DOCS_WATERMARK_ENABLED === 'true';
 const DOCS_WATERMARK_TEXT = process.env.DOCS_WATERMARK_TEXT || DOCS_TITLE;
 const DOCS_DIR = path.resolve(process.env.DOCS_ROOT || path.join(process.cwd(), 'docs'));
@@ -74,6 +95,9 @@ app.locals.docsTitle = DOCS_TITLE;
 app.locals.docsSubtitle = DOCS_SUBTITLE;
 app.locals.docsLogo = DOCS_LOGO;
 app.locals.docsStorageKeyPrefix = DOCS_STORAGE_KEY_PREFIX;
+app.locals.docsThemeDefault = DOCS_THEME_DEFAULT;
+app.locals.docsThemeModeDefault = DOCS_THEME_MODE_DEFAULT;
+app.locals.docsThemeEnabled = DOCS_THEME_ENABLED;
 app.locals.docsWatermarkEnabled = DOCS_WATERMARK_ENABLED;
 app.locals.docsWatermarkText = DOCS_WATERMARK_TEXT;
 function normalizeDocRelativePath(value) {
@@ -358,7 +382,7 @@ function renderTree(tree, level = 0) {
             html += `<li class="directory collapsed"${dataDirPath}>
         <span class="dir-toggle">
           <span class="toggle-icon">▼</span>
-          <span class="dir-name" title="${itemName}">📁 ${itemName}</span>
+          <span class="dir-name" title="${itemName}"><span class="tree-kind-icon tree-kind-icon-directory" aria-hidden="true">📁</span>${itemName}</span>
         </span>
         <div class="dir-children">${renderTree(item.children, level + 1)}</div>
       </li>`;
@@ -367,7 +391,7 @@ function renderTree(tree, level = 0) {
             // 文件路径直接使用，路径重定向在 resolveDocPath 中处理
             const url = `/doc?path=${encodeURIComponent(item.path)}`;
             html += `<li class="file">
-        <a href="${url}" class="file-link" title="${itemName}">📄 ${itemName}</a>
+        <a href="${url}" class="file-link" title="${itemName}"><span class="tree-kind-icon tree-kind-icon-file" aria-hidden="true">📄</span>${itemName}</a>
       </li>`;
         }
     }

package/package.json

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