From c81cf221efcb68aa49c6266ac00bc81553e52fca Mon Sep 17 00:00:00 2001 From: hypercross Date: Sun, 13 Sep 2026 14:24:34 +0800 Subject: [PATCH] docs: correct stale routing and url references Document that the CLI mounts the content directory at the URL root and that the app uses History API routing, not the old /content hash scheme. Replace the removed
iconPath prop with the actual upward assets/ lookup, and fix the deck_preview preview_url example. --- docs/cli.md | 33 ++++++++++++++++++++------------- docs/markdown.md | 18 +++++++++--------- docs/mcp.md | 4 +++- src/components/Article.tsx | 2 +- 4 files changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 3ab61ed..7072b2b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -39,14 +39,14 @@ tttk serve [dir] -p 3000 | 选项 | 说明 | 默认值 | |------|------|--------| | `-p, --port ` | 端口号 | `3000` | -| `-h, --host ` | 主机地址 | `0.0.0.0` | +| `--host ` | 主机地址 | `0.0.0.0` | **功能：** -- 扫描目录下的所有 `.md`、`.csv`、`.yarn` 文件 -- 为每个文件创建路由 -- 提供实时文件监听，修改后自动刷新 -- 通过 `/__CONTENT_INDEX.json` 提供文件索引 +- 扫描目录下的 `.md`、`.csv`、`.yarn`、`.svg` 文件（跳过以 `.` 开头的文件和 `node_modules`） +- 把内容目录挂在 URL 根路径下，文档 `rules/combat.md` 对应路由 `/rules/combat` +- 监听文件变化并重建内存中的内容注册表 +- 提供 `/__CONTENT_INDEX.json`、`/__CONTENT_REGISTRY.json`、`/__COMPLETIONS.json` 等接口（见[开发服务器特性](#开发服务器特性)） **示例：** @@ -218,20 +218,27 @@ my-ttrpg-content/ ## 开发服务器特性 -### 实时索引 +### 内容接口 -访问 `http://localhost:3000/__CONTENT_INDEX.json` 可获取当前内容目录的文件索引。 +- `/__CONTENT_INDEX.json` — 原始文件索引（`{ 路径: 文件内容 }`） +- `/__CONTENT_REGISTRY.json` — 内容注册表（文件路径索引 + 文档内联内容） +- `/__COMPLETIONS.json` — 补全数据（骰点、链接、spark 表格、声明、标签修饰符） -### 自动刷新 +### 内容目录与 URL 的对应关系 -文件变化时，服务器会自动重新加载内容，无需手动刷新页面。 +内容目录挂在 URL 根路径下，文档去掉 `.md` 扩展名后即为路由： + +- 文档 `rules/combat.md` → `http://localhost:3000/rules/combat` +- 图片 `rules/maps/city.png` → `http://localhost:3000/rules/maps/city.png` + +### 文件监听 + +服务器会监听内容目录的变化并重建内存中的注册表；重新加载页面即可看到最新内容。 ### SPA 路由 -使用 hash 路由支持单页应用导航： - -- `/content/rules/combat.md` → `#/content/rules/combat.md` -- 支持浏览器前进/后退 +路由基于 History API（而非 hash）。直接访问深层链接或刷新页面时，未知路径会回退到 `index.html`， +因此浏览器前进/后退与深链接均可正常工作。 ## 常见问题 diff --git a/docs/markdown.md b/docs/markdown.md index abd527d..164d8d7 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -100,19 +100,19 @@ **注意：** CSS class 名称始终使用不带扩展名的图标名称（如 `icon-attack`），方便统一样式控制。 -### 配置图标前缀 +### 图标查找路径 -可通过 `iconPath` 属性指定图标目录： +图标没有单独的配置项。`:[name]` 会从当前文档所在目录开始，逐级向上查找 `assets/` 目录， +直到内容目录根： -```markdown -
+```text +rules/combat.md 中的 :[attack] + → rules/assets/attack.png + → assets/attack.png ``` -或使用空字符串禁用图标前缀： - -```markdown -
-``` +因此把图标放在内容目录（或其子目录）的 `assets/` 下即可。`tttk check` 会用同样的规则 +校验图标是否存在（诊断 `TTTK-A001`）。 ## 组件库 diff --git a/docs/mcp.md b/docs/mcp.md index 394adca..fc97f53 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -246,10 +246,12 @@ ttrpg mcp generate-card-deck \ { "success": true, "message": "预览文件已创建", - "preview_url": "http://localhost:3000/#/content/cards.md" + "preview_url": "http://localhost:3000/cards" } ``` +`preview_url` 以服务器工作目录为基准，去掉了 `.md` 扩展名（需要 `tttk serve` 正在运行）。 + ## CSV 文件格式 CSV 文件使用 YAML frontmatter 定义模板和配置： diff --git a/src/components/Article.tsx b/src/components/Article.tsx index 0e548b2..d42b9e4 100644 --- a/src/components/Article.tsx +++ b/src/components/Article.tsx @@ -109,7 +109,7 @@ export const Article: Component = (props) => { e.preventDefault(); // Resolve relative hrefs against the current page path so that - // e.g. "blah.md" on /content/page.md becomes /content/blah + // e.g. "blah.md" on /rules/page becomes /rules/blah const resolved = new URL(href, window.location.origin + window.location.pathname); let pathname = resolved.pathname; // Strip .md extension so refreshes hit the SPA fallback, not the raw file