@deot/docs-client 1.0.6 → 1.0.8

package/README.md

@@ -25,6 +25,20 @@ pnpm add @deot/docs-client
 					logo: './logo.svg',
 					label: { 'zh-CN': '组件文档', 'en-US': 'Component Docs' },
 					value: '/guide'
+				},
+				nav: {
+					'zh-CN': [
+						{ label: '指南', value: '/guide' },
+						{
+							label: '生态',
+							children: [
+								{ label: 'GitHub', value: 'https://github.com/deot/docs' }
+							]
+						}
+					],
+					'en-US': [
+						{ label: 'Guide', value: '/guide' }
+					]
 				}
 			}
 		},
@@ -69,6 +83,21 @@ const { app, router, disconnect } = await bootstrap(window.$docs);
 
 `disconnect()` 用于关闭当前实例创建的 SSE、空闲预加载和联网恢复监听。
 
+## Redirect 约定
+
+`sessionStorage['@deot/docs:redirect']` 是文档站点的深链约定：把待还原的**同站绝对路径**交给 Client，启动后再导航到部署目录内的对应路由。
+
+静态托管通常只会把未知路径交给入口 HTML 或自定义 404 页，不会像 `doc dev` / `doc preview` 那样做 history fallback。任意入口（常见是与 `index.html` 配套的 `404.html`）写入该键后跳转到**站点入口**（部署目录，例如 `'/'` 或 `'/docs/'`）：
+
+```html
+<script>
+	sessionStorage['@deot/docs:redirect'] = location.pathname + location.search + location.hash;
+</script>
+<meta http-equiv="refresh" content="0;URL='/'" />
+```
+
+`bootstrap()` 在路由就绪后读取并清除该键。路径必须以 `/` 开头且不能是 `//`，且必须落在当前部署目录内；随后 `router.push` 去掉部署前缀后的路由。非法或越界值会被丢弃，但键仍会清除，避免下次启动误跳。仓库根目录 [`404.html`](../../404.html) 是一份可直接部署的实现，其中刷新地址是本仓库的 `/docs/`；其他站点应改成自己的入口。
+
 ## `$docs` 配置
 
 | 字段 | 说明 |
@@ -77,14 +106,13 @@ const { app, router, disconnect } = await bootstrap(window.$docs);
 | `routes` | 去掉语言前缀后的路由配置。字符串和函数表示重定向。 |
 | `base` | production 资源的基准 URL。 |
 | `namespace` | IndexedDB 缓存隔离标识；未设置时使用规范化后的 `base`。 |
-| `repository` | 当前文档项目的 GitHub 仓库页面；内置 Footer 据此生成 Issues、需求与 Releases 链接。 |
+| `repository` | 当前文档项目的远程仓库页面。Header 在语言与工具之间展示入口，并在新窗口打开；GitHub 地址还会用于生成默认 Footer 的 Issues、需求与 Releases 链接。 |
 | `modules` | 站点级裸模块名到 URL 的映射，对所有 Playground（含 Markdown）生效；远程 SFC 仍可通过实例 `builtinImportMap` 覆盖。 |
 | `styles` | 站点级预览 CSS 默认地址；同名 key 覆盖内置样式表，也可追加。管理页 `/:lang/__docs/playground-resource` 与 `modules` 同一张表管理。 |
 | `prefetch` | 空闲预加载开关或 `{ batchSize, idleTimeout }` 配置，默认开启。 |
 | `theme` | 主题开关或 `{ default: 'system' \| 'light' \| 'dark' }`，默认跟随系统。 |
-| `layout.header` | 内置 Header 配置；`brand.logo`、`brand.label` 和 `brand.value` 均支持固定值或按语言配置。文案未配置时回退到 `namespace` 和内置翻译，链接未配置时指向当前语言首页。站内链接自动补语言前缀，外链在新窗口打开。 |
-| `layout.footer` | Footer 内容；未配置或 `default` 使用内置分组，`false` 全局隐藏，也可配置 `{ groups, poweredBy }`。两项均支持按语言代码配置，`groups` 复用 Sidebar 的 `{ label, value?, children? }` 结构。 |
-| `home` | 可选的 `{ locales }` 首页配置；语言值是 Renderer 文档或 `.page.json` 地址。未配置时首页为空。 |
+| `layout.header` | 内置 Header 配置；`brand.logo`、`brand.label` 和 `brand.value` 均支持固定值或按语言配置。文案未配置时回退到 `namespace` 和内置翻译，链接未配置时指向当前语言首页。站内链接自动补语言前缀，外链在新窗口打开。`nav` 是搜索后的横向导航，未配置时不渲染；条目复用 Sidebar 的 `{ label, value?, children? }` 结构，支持固定数组或按语言配置，有 `children` 的项以下拉展示。 |
+| `layout.footer` | Footer 内容；未配置或 `default` 使用内置分组，`false` 全局隐藏，也可配置 `{ nav, poweredBy }`。两项均支持按语言代码配置，`nav` 复用 Sidebar 的 `{ label, value?, children? }` 结构，按列分组渲染。 |
 | `renderers` | 业务自定义 Renderer 模块注册项；type 必须使用非 `docs:` 的命名空间。 |
 | `resolve.markdown` | 根据 `lang`、`value` 和当前路由生成 Markdown 逻辑地址。 |
 | `resolve.resource` | 将任意逻辑资源转换为最终 URL。 |
@@ -129,30 +157,32 @@ const sidebar = {
 
 ### 首页
 
-未配置 `routes['/']` 时，Client 渲染 `$docs.home`。首页文档必须由站点自己提供，Client 不内置示例页：
+未配置 `routes['/']` 时，Client 渲染空画布首页（默认 Header/Footer、无 Sidebar）。把首页文档写在 `routes['/'].content`：可以是 Renderer 文档、`.page.json` 地址，或按语言的映射（缺语言回退 `en-US`）。Client 不内置示例页：
 
 ```js
 window.$docs = {
-	home: {
-		locales: {
-			'zh-CN': './pages/home.page.json',
-			'en-US': {
-				schemaVersion: 2,
-				meta: { id: 'home-en', title: 'Home' },
-				layout: {
-					mode: 'sortable',
-					maxWidth: 1920,
-					minHeight: 600,
-					background: '#fff'
-				},
-				blocks: []
+	routes: {
+		'/': {
+			content: {
+				'zh-CN': './pages/home.page.json',
+				'en-US': {
+					schemaVersion: 2,
+					meta: { id: 'home-en', title: 'Home' },
+					layout: {
+						mode: 'sortable',
+						maxWidth: 1920,
+						minHeight: 600,
+						background: '#fff'
+					},
+					blocks: []
+				}
 			}
 		}
 	}
 };
 ```
 
-未配置 `home` 时首页画布为空，仍保留默认 Header/Footer、不展示 Sidebar。`routes['/']` 可以完全覆盖该首页路由。
+`content` 为 `'default'` / Markdown / SFC / `null` 时仍覆盖内置首页，走普通 ResourceSlot。其它路由上的 `content` 也可以写成语言映射，缺语言回退站点默认语言。
 
 首页入口链接由站点文档自己声明。业务 routes 和 Sidebar 只决定内容页怎么走：
 
@@ -165,7 +195,7 @@ window.$docs = {
 
 路由的 `content` 也可直接传入 Renderer 文档。`/:lang/__docs/renderer-editor` 在所有运行模式下都会注册；可从 Header 进入，编辑 Markdown、远程 SFC、内置模块和业务通过 `renderers` 声明的模块。development 下保存会 `PUT /__docs/page`，body 为 `{ lang, source, document }`，只写入工作区内带语言前缀的 `.page.json`；production 不开放该接口，仍可使用导入、导出和预览。Combo 草稿写入 IndexedDB 库 `deot-docs-renderer`，与 Gateway 的 `deot-docs` 分库。
 
-对照组合与短路径 `/:lang/renderer-editor-demos` 仅在 development 注入；目录页列出全部演示，`?name=landing` 进入对应 Combo。若站点占用了 `/renderer-editor-demos`，改从 `/:lang/__docs/renderer-editor-demos` 访问。production 不注册这些演示路由。工厂函数也可直接赋给 `$docs.home` 或路由 `content`：
+对照组合与短路径 `/:lang/renderer-editor-demos` 仅在 development 注入；目录页列出全部演示，`?name=landing` 进入对应 Combo。若站点占用了 `/renderer-editor-demos`，改从 `/:lang/__docs/renderer-editor-demos` 访问。production 不注册这些演示路由。工厂函数也可直接赋给 `routes['/'].content` 或其它路由 `content`：
 
 | 查询 | 内容 |
 |---|---|
@@ -183,9 +213,11 @@ window.$docs = {
 
 ```ts
 window.$docs = {
-	home: {
-		locales: {
-			'zh-CN': './home.page.json'
+	routes: {
+		'/': {
+			content: {
+				'zh-CN': './home.page.json'
+			}
 		}
 	}
 };