@hia-doc/renderer-html 0.1.7 → 1.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +243 -0
- package/dist/index.d.ts +1623 -126
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +829 -159
- package/dist/index.js.map +1 -1
- package/dist/information-architecture.d.ts +284 -20
- package/dist/information-architecture.d.ts.map +1 -1
- package/dist/information-architecture.js +42 -15
- package/dist/information-architecture.js.map +1 -1
- package/dist/portal-ui-locale.d.ts +108 -20
- package/dist/portal-ui-locale.d.ts.map +1 -1
- package/dist/portal-ui-locale.js +103 -27
- package/dist/portal-ui-locale.js.map +1 -1
- package/dist/presentation-profile.d.ts +176 -16
- package/dist/presentation-profile.d.ts.map +1 -1
- package/dist/presentation-profile.js +40 -14
- package/dist/presentation-profile.js.map +1 -1
- package/dist/route-history.d.ts +193 -0
- package/dist/route-history.d.ts.map +1 -0
- package/dist/route-history.js +246 -0
- package/dist/route-history.js.map +1 -0
- package/dist/site-chrome.d.ts +173 -0
- package/dist/site-chrome.d.ts.map +1 -0
- package/dist/site-chrome.js +187 -0
- package/dist/site-chrome.js.map +1 -0
- package/dist/site-navigation-chrome.d.ts +36 -0
- package/dist/site-navigation-chrome.d.ts.map +1 -0
- package/dist/site-navigation-chrome.js +430 -0
- package/dist/site-navigation-chrome.js.map +1 -0
- package/dist/site-navigation.d.ts +175 -0
- package/dist/site-navigation.d.ts.map +1 -0
- package/dist/site-navigation.js +176 -0
- package/dist/site-navigation.js.map +1 -0
- package/dist/site-reading.d.ts +171 -0
- package/dist/site-reading.d.ts.map +1 -0
- package/dist/site-reading.js +534 -0
- package/dist/site-reading.js.map +1 -0
- package/dist/source-lines.d.ts +3 -2
- package/dist/source-lines.d.ts.map +1 -1
- package/dist/source-lines.js +15 -9
- package/dist/source-lines.js.map +1 -1
- package/dist/theme-assets.d.ts +12 -3
- package/dist/theme-assets.d.ts.map +1 -1
- package/dist/theme-assets.js.map +1 -1
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -1,11 +1,207 @@
|
|
|
1
1
|
# @hia-doc/renderer-html
|
|
2
2
|
|
|
3
|
+
采用站点导航时,交互页会在正文首次布局前确定移动目录的折叠状态。阅读控件绑定前保留空间并隐藏,绑定后才进入键盘访问顺序。禁用脚本时可使用展开的原生目录及静态链接。
|
|
4
|
+
|
|
5
|
+
With site navigation, interactive pages determine mobile-directory disclosure before the first prose layout. Reading controls reserve space while hidden and enter keyboard navigation after binding. Script-disabled pages provide native open directories and static links.
|
|
6
|
+
|
|
7
|
+
## Entry loading with site navigation
|
|
8
|
+
|
|
9
|
+
显式采用站点导航的多页Portal通过同次生成的路径打开已知条目深链,正文可在目录及检索索引读取完成前呈现。目录恢复实际祖先,检索按实际查询读取索引,未知条目标识继续使用索引回退。语言、成员锚点及规范/呈现路径保留各自身份。
|
|
10
|
+
|
|
11
|
+
Multi-page Portals with explicit site navigation open known entry deep links through paths emitted in the same generation. Prose can appear before directory and search reads complete. Directory restoration follows actual ancestors, searches load their index on demand, and unknown entry identities retain index fallback. Language, member anchors and canonical/presentation paths retain their own identities.
|
|
12
|
+
|
|
13
|
+
较新的条目选择或筛选重置会使旧异步响应失效。目录或检索不可用时,已加载正文继续可读,无脚本页面保留普通链接。
|
|
14
|
+
|
|
15
|
+
Newer entry selections and filter resets invalidate older asynchronous responses. Loaded prose remains readable when directory or search data is unavailable, and script-free pages retain ordinary links.
|
|
16
|
+
|
|
17
|
+
## Source availability and recovery
|
|
18
|
+
|
|
19
|
+
显式阅读信息架构会区分未提供公开片段、未获本地公开读取许可、文件或资产缺失、摘要不符及读取失败。文档正文在这些状态下保持可读。固定双语反馈使用已有公开诊断代码与实际请求结果,远端响应正文、statusText和原始网络异常均不会成为状态文案。
|
|
20
|
+
|
|
21
|
+
The explicit reading layout distinguishes an absent public excerpt, denied local publication authority, missing files or assets, integrity failures and read failures. Documentation prose remains readable. Fixed bilingual feedback uses existing public diagnostic fields and actual request outcomes. Response bodies, server status text and original network exceptions stay outside feedback copy.
|
|
22
|
+
|
|
23
|
+
恢复源资产原字节或读取许可后,点击“重置”并重新展开源码即可重新经过原摘要校验。加载期间同一按钮用于取消。静态页面会显示构建时已知的可用性反馈,禁用脚本时使用普通阅读路径。源码模式`none`继续按该模式隐藏,读取失败沿当前模式呈现。
|
|
24
|
+
|
|
25
|
+
After restoring the original asset bytes or read authority, select **Reset** and reopen the source panel to repeat the original integrity checks. During loading, the same control cancels the request. Static pages show build-time availability feedback and support ordinary reading with scripts disabled. Source mode `none` retains its visibility policy, and failures remain within the selected mode.
|
|
26
|
+
|
|
27
|
+
键盘手动加载时,焦点跟随已显示的取消控件。重置后,焦点返回手动加载按钮或原生展开入口,并滚入可见位置。异步读取期间用户已移走的焦点继续保持。
|
|
28
|
+
|
|
29
|
+
During keyboard-triggered manual loading, focus follows the visible cancel control. Reset restores focus to the manual load button or native disclosure and reveals it. Asynchronous reading respects focus that the user has moved elsewhere.
|
|
30
|
+
|
|
31
|
+
独立源码页的行号链接可直接打开或复制。激活行号后,Tab继续下一行,Shift+Tab返回上一行,整行选中样式保留,禁用脚本时同样可用。
|
|
32
|
+
|
|
33
|
+
Standalone source line links support direct navigation and copying. After activating a line, Tab continues to the next line and Shift+Tab returns to the preceding line, retaining full-line selection with scripts disabled as well.
|
|
34
|
+
|
|
35
|
+
构建时的来源失败需要修正文件或配置后重新构建,浏览器读取器的重置只重新请求已发布的资产。Build-time source failures require correcting files or configuration and rebuilding. A browser reader reset only requests assets already published.
|
|
36
|
+
|
|
37
|
+
CLI通过已有条目diagnostics传递以下固定信息类别,重复准备会重算这些瞬时结果,其它生产者诊断保持。These fixed informational codes use existing entry diagnostics. Repeated preparation recomputes these transient outcomes and preserves other producer diagnostics.
|
|
38
|
+
|
|
39
|
+
已显示来源提示的同一诊断以`data-hia-source-diagnostic`保留公开代码,其它诊断继续在诊断区显示。The same diagnostic already represented by a source notice retains its public code in `data-hia-source-diagnostic`, while other diagnostics remain in the diagnostics section.
|
|
40
|
+
|
|
41
|
+
| Code | Meaning |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `HIA_CLI_SOURCE_NOT_AUTHORIZED` | 本地公开读取未授权 / Local public-source reading was not authorized. |
|
|
44
|
+
| `HIA_CLI_SOURCE_NOT_FOUND` | 来源文件或路径不存在 / The source file or path was not found. |
|
|
45
|
+
| `HIA_CLI_SOURCE_READ_FAILED` | 其它本地读取失败 / Another local read failure occurred. |
|
|
46
|
+
| `HIA_CLI_SOURCE_NOT_PROVIDED` | 未取得可公开片段,原因按已有证据保留 / No public excerpt was obtained, with the cause limited to available evidence. |
|
|
47
|
+
|
|
48
|
+
## Shared site chrome
|
|
49
|
+
|
|
50
|
+
The `@hia-doc/renderer-html/site-chrome` subpath provides synchronous ESM and
|
|
51
|
+
CommonJS access to `createSiteChrome`, the existing navigation validator and
|
|
52
|
+
`renderSourceLines` on the documented Node.js runtime baseline.
|
|
53
|
+
|
|
54
|
+
中文说明。共享子入口接收显式页面角色、界面语言、实际同页语言路径和生成器已安全处理的正文/目录HTML。`createSiteChrome({ navigation, entries })`返回独立快照、一次生成一份的`assets`和同步`renderPage(page)`。调用方负责写文件和源码公开许可。
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
const { createSiteChrome } = require("@hia-doc/renderer-html/site-chrome");
|
|
58
|
+
const site = createSiteChrome({ navigation, entries: [] });
|
|
59
|
+
const html = site.renderPage({
|
|
60
|
+
role: "entry",
|
|
61
|
+
outputPath: "greet.en.html",
|
|
62
|
+
uiLocale: "en",
|
|
63
|
+
localePages: { en: "greet.en.html", "zh-CN": "greet.zh-CN.html" },
|
|
64
|
+
title: "greet",
|
|
65
|
+
bodyHtml: '<article><h1>greet</h1></article>',
|
|
66
|
+
directoryHtml: '<a href="greet.en.html">greet</a>',
|
|
67
|
+
sections: []
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`navigation` must satisfy `documentation-site-navigation@0.1.0-draft`.
|
|
72
|
+
Entry `page` and `localePages` targets are relative to the generation root.
|
|
73
|
+
Page `outputPath` is an HTML path, `uiLocale` is explicitly `en` or `zh-CN`,
|
|
74
|
+
and every section ID must exist in `bodyHtml`. Missing locale counterparts
|
|
75
|
+
remain disabled. Optional `stylesheets`/`scripts` use generation-root-relative
|
|
76
|
+
paths. HTML slots belong to a trusted generator and require its sanitization.
|
|
77
|
+
|
|
78
|
+
The service performs no I/O. It emits shared CSS, progressive-enhancement JS
|
|
79
|
+
and a body-free search index once per generation. Source-role pages are
|
|
80
|
+
script-free with a restrictive CSP. Invalid input throws a public `TypeError`
|
|
81
|
+
with `HIA_SITE_CHROME_INVALID` or the existing navigation diagnostic, without
|
|
82
|
+
echoing rejected values. Read-only asset lists can be reused across pages.
|
|
83
|
+
|
|
84
|
+
中文说明。搜索按实际静态页面跳转,搜索及设置只在当前页面运行,设置不持久化。源码正文、文件归属、语言/版本和坐标精度由各生产方及现有契约负责,导航数据只提供公开站点目标。
|
|
85
|
+
|
|
86
|
+
中文。`RenderProjectEntry.identityScope` 为可选聚合作用域。父子、成员与来源关系按作用域隔离,含作用域条目的索引使用 `0.2.0-draft`,原无作用域索引保持 `0.1.0-draft`。调用方负责稳定作用域和唯一条目标识,源码授权按来源策略核验。详见[聚合迁移](../../docs/project-manifest-migration.md#scoped-aggregation)。
|
|
87
|
+
|
|
88
|
+
English. Optional `RenderProjectEntry.identityScope` isolates parent/member and provenance relations. Indexes containing scoped entries use `0.2.0-draft`, with unscoped indexes retaining `0.1.0-draft`. Callers supply stable scopes and unique entry IDs. Source authority follows the source policy.
|
|
89
|
+
|
|
90
|
+
## 正文来源语言 / Prose source language
|
|
91
|
+
|
|
92
|
+
正文选择语言与实际原文语言分别管理。`data-hia-locale` 保留请求语言,段落 `lang` 使用字段解析后的实际语言。普通摘要使用条目现有 `i18n.defaultLocale`,单文档渲染还可使用所属文档的 `defaultLocale`。直接项目调用没有来源声明时输出 `lang=""`,避免继承界面语言。切换语言不会生成译文。
|
|
93
|
+
|
|
94
|
+
English. Content selection and source language are independent. `data-hia-locale` retains the requested locale while paragraph `lang` identifies the resolved text language. Bare summaries use an entry's existing `i18n.defaultLocale`, or the owning document's `defaultLocale` for document rendering. Direct project calls without a source declaration emit `lang=""` to prevent inheriting the UI language. Locale selection does not generate translations.
|
|
95
|
+
|
|
96
|
+
## 1.0.0 source candidate
|
|
97
|
+
|
|
98
|
+
This source tree targets a coordinated 1.0.0 package candidate. It does not
|
|
99
|
+
announce npm availability. See the [package migration guide](../../docs/package-v1-migration.md)
|
|
100
|
+
for matching dependencies, artifact versions and source compatibility.
|
|
101
|
+
|
|
102
|
+
中文:当前为1.0.0源码候选,实际发布及工件版本请分别核对迁移说明。
|
|
103
|
+
|
|
104
|
+
|
|
3
105
|
HIA 文档的 HTML renderer,同时支持单一 document 与统一项目站。
|
|
4
106
|
|
|
5
107
|
The renderer consumes `@hia-doc/core` data and returns file payloads. It does not read from disk or own CLI behavior.
|
|
6
108
|
|
|
7
109
|
## Current Scope
|
|
8
110
|
|
|
111
|
+
### Optional website navigation
|
|
112
|
+
|
|
113
|
+
中文。站点阅读页的 JS 领域徽标在 `entry.source.language` 明确为 `typescript` 时显示 TypeScript,其余情况沿用 JavaScript。原领域分组、索引身份和源码数据保持各自职责。
|
|
114
|
+
|
|
115
|
+
English. Adopted reading pages label JS-domain entries as TypeScript when `entry.source.language` explicitly equals `typescript`, retaining JavaScript otherwise. Domain grouping, index identity and source metadata retain their respective roles.
|
|
116
|
+
|
|
117
|
+
中文。项目渲染的 `projectSite.siteNavigation` 接受独立 `documentation-site-navigation@0.1.0-draft` 数据。宿主明确提供品牌、两语言标签、部署内路由与实际文档版本,同时设置 `projectSite.uiLocale`。渲染器在交互页、静态索引/条目和独立源码页生成固定顶部、原生版本菜单、文档栏目及手机菜单,输出一份 `assets/hia-site-navigation.css`。原生菜单可在禁用脚本时使用。正文语言与界面语言分别管理。源码权限仍来自原输入和来源策略。
|
|
118
|
+
|
|
119
|
+
English. Project rendering accepts independent `documentation-site-navigation@0.1.0-draft` data through `projectSite.siteNavigation`. Hosts provide branding, bilingual labels, deployment-local routes, actual documentation versions, and an explicit `projectSite.uiLocale`. The renderer adds a fixed header, native version menu, documentation tabs, and mobile menu to interactive pages, static indexes/entries, and standalone source viewers, emitting one `assets/hia-site-navigation.css`. Native menus work without scripts. UI and content languages are independent. Source authority comes from the existing inputs and source policy.
|
|
120
|
+
|
|
121
|
+
```js
|
|
122
|
+
import { assertDocumentationSiteNavigation, renderProjectHtmlDocumentToWriter } from "@hia-doc/renderer-html";
|
|
123
|
+
|
|
124
|
+
// 中文。数据由宿主读取或构造,渲染器不读取文件。
|
|
125
|
+
// English. Hosts load or construct the data. The renderer performs no file reads.
|
|
126
|
+
const navigation = {
|
|
127
|
+
contract: "documentation-site-navigation",
|
|
128
|
+
contractVersion: "0.1.0-draft",
|
|
129
|
+
deploymentBase: "/product/",
|
|
130
|
+
brand: {
|
|
131
|
+
title: "Example Documentation",
|
|
132
|
+
captionByLocale: { "zh-CN": "开发文档", en: "Developer documentation" },
|
|
133
|
+
homeByLocale: { "zh-CN": "/product/", en: "/product/en/" }
|
|
134
|
+
},
|
|
135
|
+
primaryNavigation: [{
|
|
136
|
+
id: "docs",
|
|
137
|
+
labelByLocale: { "zh-CN": "文档", en: "Docs" },
|
|
138
|
+
hrefByLocale: { "zh-CN": "/product/docs/zh-CN/", en: "/product/docs/en/" }
|
|
139
|
+
}],
|
|
140
|
+
documentationTabs: [{
|
|
141
|
+
id: "code",
|
|
142
|
+
labelByLocale: { "zh-CN": "代码文档", en: "Code reference" },
|
|
143
|
+
hrefByLocale: { "zh-CN": "/product/api/zh-CN/", en: "/product/api/en/" }
|
|
144
|
+
}],
|
|
145
|
+
activePrimaryId: "docs",
|
|
146
|
+
activeTabId: "code",
|
|
147
|
+
documentationVersion: {
|
|
148
|
+
version: "1.0.0", status: "preview",
|
|
149
|
+
entries: [{ version: "1.0.0", status: "preview", hrefByLocale: { "zh-CN": "/product/api/zh-CN/", en: "/product/api/en/" } }],
|
|
150
|
+
history: {
|
|
151
|
+
labelByLocale: { "zh-CN": "历史版本", en: "Archives" },
|
|
152
|
+
hrefByLocale: { "zh-CN": "/product/versions/", en: "/product/versions/en/" }
|
|
153
|
+
}
|
|
154
|
+
},
|
|
155
|
+
localeTargets: { "zh-CN": "/product/api/zh-CN/", en: "/product/api/en/" }
|
|
156
|
+
};
|
|
157
|
+
assertDocumentationSiteNavigation(navigation);
|
|
158
|
+
await renderProjectHtmlDocumentToWriter(projectInput, writer, {
|
|
159
|
+
projectSite: { uiLocale: "zh-CN", informationArchitecture: {}, siteNavigation: navigation }
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
中文。两种语言 `zh-CN`/`en` 的标签和目标均为必填。字段采用闭集。主导航和栏目各限1–16项,组内身份使用至多32位小写字母数字且以字母起始,选中身份必须存在。版本菜单限1–64项,完整三段版本号唯一,当前版本和状态必须在菜单精确出现一次。状态为 `preview`、`stable`、`archive`。菜单只列真实存在的版本,宿主负责版本事实及链接存在性。界面语言评估采用实际输入标签;报告不包含译文正文。
|
|
164
|
+
|
|
165
|
+
English. Labels and targets are required for both `zh-CN` and `en`, using closed fields. Primary navigation and tabs each contain 1–16 entries. IDs contain at most 32 lowercase alphanumeric characters, beginning with a letter, and selected IDs must exist. Version menus contain 1–64 entries with unique complete three-component versions and exactly one matching current version/status. Statuses are `preview`, `stable`, and `archive`. Hosts supply actual versions and verify target existence. UI-language evaluation uses the actual input labels, excluding translated text from reports.
|
|
166
|
+
|
|
167
|
+
中文。部署根以 `/` 开始及结束;目标为部署根下的站点绝对路径,可带显式锚点。草案拒绝查询参数、协议、本机地址、反斜杠、点段、路径百分号编码及越根目标。标签非空有界,拒绝控制符、尖括号和模板花括号,其余文本在HTML中转义。标题最多128字符,其它标签最多256字符,目标最多2048字符。无效输入在写者首写前抛出 `HIA_SITE_NAVIGATION_INVALID`,缺少明确界面语言抛出 `HIA_SITE_NAVIGATION_UI_LOCALE_REQUIRED`。渲染器复制导航供惰性生成使用,写者回调期间修改外部对象不会改变后续页面。
|
|
168
|
+
|
|
169
|
+
English. Deployment roots begin and end with `/`. Targets are site-absolute paths within that root and may carry explicit anchors. The draft rejects queries, schemes, local addresses, backslashes, dot segments, percent-encoded paths, and root escapes. Labels are nonblank and bounded, rejecting controls, angle brackets, and template braces, with remaining text HTML-escaped. Titles allow 128 characters, other labels 256, and targets 2048. Invalid input throws `HIA_SITE_NAVIGATION_INVALID` before the first writer call. Missing explicit UI locale throws `HIA_SITE_NAVIGATION_UI_LOCALE_REQUIRED`. Navigation is snapshotted for lazy generation, so writer-time changes to caller objects cannot change later pages.
|
|
170
|
+
|
|
171
|
+
中文。没有导航输入时保留原输出。导航不会从 `project.productVersion` 推导站点版本或历史路由。单一文档的 `renderHtmlDocument` 不消费项目导航。CLI采用方式见其分发的 `USAGE.md`。
|
|
172
|
+
|
|
173
|
+
English. Omitting navigation preserves existing output. Navigation does not derive documentation versions or historical routes from `project.productVersion`. Single-document `renderHtmlDocument` does not consume project navigation. CLI adoption is described in its distributed `USAGE.md`.
|
|
174
|
+
|
|
175
|
+
中文。API只接受普通JSON数据属性和稠密数组,拒绝getter、隐藏字段、symbol字段及自定义数组迭代器。导航可以与旧项目布局组合;未启用显式信息架构时,语言报告使用 `portal.sitenavigation` 身份,仅评估新增导航标签。显式信息架构则把这些标签加入完整Portal消息清单。长主导航和栏目在各自容器内滚动,极长品牌保留完整可访问名称及title提示,视觉限制为两行。
|
|
176
|
+
|
|
177
|
+
English. The API accepts ordinary JSON data properties and dense arrays, rejecting getters, hidden or symbol fields, and custom array iterators. Navigation also works with legacy project layouts. Without explicit information architecture, the language report uses `portal.sitenavigation` and evaluates the added navigation labels alone. Explicit information architecture adds those labels to the complete Portal message inventory. Long primary navigation and tabs scroll within their own containers. Very long brands retain their complete accessible name and title tooltip with a two-line visual limit.
|
|
178
|
+
|
|
179
|
+
中文。独立源码页和原静态路径使用构建明确指定的界面语言,`pages/{uiLocale}/` 使用路径中已知的界面语言。交互页的运行时语言切换只更新当前页。语言入口和版本入口使用宿主提供的实际目标,当前草案不根据文件名猜测跨语言、跨版本的同符号或同行号对应关系。
|
|
180
|
+
|
|
181
|
+
English. Standalone source viewers and legacy static routes use the build-explicit UI locale, while `pages/{uiLocale}/` uses its known route locale. Runtime UI switching updates the current interactive page. Language and version entries use actual host-supplied targets. The draft does not guess same-symbol or same-line counterparts across languages or versions from file names.
|
|
182
|
+
|
|
183
|
+
### Adopted reading layout
|
|
184
|
+
|
|
185
|
+
中文。显式站点导航同时采用三栏阅读布局、真实小节目录和手机原生折叠目录。标准API字段及既有.NET字段别名使用可读双语标题,字段身份、签名、所有正文语言和源码字节保留。接口深链仅展开其祖先分片,快速切换时忽略过期响应;加载或失败时保留已读正文。页内目录的普通链接可直接打开现有静态对应页。
|
|
186
|
+
|
|
187
|
+
具名参数、类型参数和异常按已有字段名称归组为“名称/说明”表格,保留逐字段锚点及所有语言正文。表格不推断输入未提供的类型、默认值或精度。
|
|
188
|
+
|
|
189
|
+
English. Explicit site navigation also selects the three-column reading layout, actual-section outlines, and native mobile directories. Standard API fields and existing .NET aliases receive readable bilingual headings while retaining field identities, signatures, every prose locale, and source bytes. API deep links expand only their ancestor shards. Stale selection responses are ignored, and loading or failure retains already displayed prose. Ordinary outline links can open existing static counterparts directly.
|
|
190
|
+
|
|
191
|
+
Named parameters, type parameters, and exceptions are grouped into name/description tables using existing field names, retaining per-field anchors and every prose locale. Tables infer no unprovided types, defaults, or precision.
|
|
192
|
+
|
|
193
|
+
中文。交互入口额外生成一份 `assets/hia-site-reading.js`,提供当前生成项目的本地索引检索、签名复制和阅读设置。设置支持浅色/深色/系统、代码滚动/换行及源码行号,采用构建默认且仅作用于当前页。界面语言和正文语言继续独立。静态页和独立源码页保持无脚本,省去运行时专用属性和不可用工具按钮。独立源码页保留原CSP、真实行号及返回接口入口,精度仍由来源证据决定。普通浏览器中的宿主文件定位请求会显示为禁用,同源公开源码链接仍可使用。
|
|
194
|
+
|
|
195
|
+
English. Interactive entries additionally emit one `assets/hia-site-reading.js` for local generated-project search, signature copying, and reading settings. Settings cover light/dark/system appearance, code scrolling/wrapping, and source line numbers, using build defaults and affecting the current page only. UI and prose locales remain independent. Static and standalone source pages remain script-free and omit runtime-only payloads and unavailable tool buttons. Source viewers preserve their CSP, real line anchors, and API-return links, with precision determined by source evidence. Host file-navigation requests are disabled in standalone browsers while public same-origin source links remain available.
|
|
196
|
+
|
|
197
|
+
中文。显式信息架构的附加字段标题与元数据、源码状态共用界面语言消息目录。正文保有各自语言标记,界面与正文可分别切换;兼容入口继续使用原有标题。
|
|
198
|
+
|
|
199
|
+
English. Explicit-IA additional-field headings share the UI-language catalog used by metadata and source states. Prose retains its own language markers, and UI and content languages switch independently. Compatibility entry points retain their existing headings.
|
|
200
|
+
|
|
201
|
+
中文。.NET 导航按程序集与文档类型身份分组。类型声明提供的语义显示名用于标签,成员的父类型文档标识用于归属;旧文档可从文档标识取得所属类型,保留泛型参数数量。导航中的类型入口可以展开到成员入口。
|
|
202
|
+
|
|
203
|
+
English. .NET navigation groups entries by assembly and documentation type identity. Declaration-provided semantic names supply labels, while parent type documentation IDs associate members. Legacy documentation IDs retain generic arity and supply owner-type fallbacks. Type navigation entries expand to member entries.
|
|
204
|
+
|
|
9
205
|
- 大站可调用 `renderProjectHtmlDocumentToWriter(input, writer, options)`,逐文件生成并等待writer;返回无正文的manifest/diagnostics/fileCount。旧API仍显式收集完整数组。详见[构建内存与源码边界](../../docs/project-build-memory.md)。
|
|
10
206
|
- Large sites can use the awaited per-file writer API; input/index metadata still scales with the site, and explicit single-page/eager outputs may remain large.
|
|
11
207
|
|
|
@@ -52,3 +248,50 @@ The renderer manifest schema version is exported as `HIA_RENDER_HTML_MANIFEST_SC
|
|
|
52
248
|
Native `<details>/<summary>` remains the disclosure authority. Expanded state comes from `details[open]` and the browser accessibility mapping; the renderer does not duplicate authored `aria-expanded`. Split-site 的 `<noscript>` 入口会转到独立多页输出;默认 `fetch` 源码在该输出中降级为构建生成的同源资源链接,而不是恢复外部 locator。Print/forced-colors fallback 由 theme asset 提供。
|
|
53
249
|
|
|
54
250
|
Renderer output is separate from CLI filesystem output. See `docs/contract-index.md` for the current layering rule.
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
独立生成器共享框架的已声明语言对应页,在脚本启用时保留本页实际存在的符号或小节锚点。显式目标片段优先,未知或畸形片段不传播,切换片段会重新计算目标。静态无脚本链接保留已生成对应页,具体符号可通过该页目录定位。
|
|
254
|
+
|
|
255
|
+
English. With scripts enabled, declared same-page locale counterparts in independent-generator chrome retain symbol or section anchors that actually exist on the current page. Explicit target fragments take precedence, unknown or malformed fragments are excluded, and fragment changes recalculate targets. Script-free links retain the generated counterpart page, whose directory provides symbol navigation.
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
项目Portal的侧栏检索共享在途索引读取,查询与领域过滤以最新操作为准。缺失或非法索引给出明确失败反馈,清空查询恢复静态层级,修复索引后再次输入可重试。索引读取错误采用固定公开文案。启用站点导航时,读取失败期间已读正文仍可继续阅读。
|
|
259
|
+
|
|
260
|
+
English. Project-Portal sidebar searches share in-flight index reads and apply the latest query and domain filter. Missing or invalid indexes produce explicit failure feedback. Clearing restores the hierarchy, and another input retries after the index is repaired. Index-read failures use fixed public text. With site navigation enabled, the current prose remains readable during these failures.
|
|
261
|
+
|
|
262
|
+
## Persistent publication identities and historical routes
|
|
263
|
+
|
|
264
|
+
`projectSite.routeHistory` adopts `documentation-project-route-history@0.1.0-draft` for split-site project rendering. The host records persistent public entry IDs, explicit current native-symbol bindings, and previously published entry/path aliases. Native symbols, scoped parentage and source-map references retain their actual current values.
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
import { renderProjectHtmlDocument } from "@hia-doc/renderer-html";
|
|
268
|
+
|
|
269
|
+
const result = renderProjectHtmlDocument(project, {
|
|
270
|
+
projectSite: {
|
|
271
|
+
uiLocale: "en",
|
|
272
|
+
routeHistory
|
|
273
|
+
}
|
|
274
|
+
});
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The history object has these fields.
|
|
278
|
+
|
|
279
|
+
| Field | Meaning |
|
|
280
|
+
| --- | --- |
|
|
281
|
+
| `contract` | `documentation-project-route-history` |
|
|
282
|
+
| `contractVersion` | `0.1.0-draft` |
|
|
283
|
+
| `projectId` | Exact rendered project identity |
|
|
284
|
+
| `sources` | Published index provenance, with `repository`, `commit`, `locale` and `indexSha256` |
|
|
285
|
+
| `bindings` | Current `identityScope` (optional), `view`, `symbolId` and persistent `entryId` |
|
|
286
|
+
| `entryAliases` | Historical `entryId` pointing directly to an actual `canonicalEntryId` |
|
|
287
|
+
| `pathAliases` | Published relative HTML `path`, `kind` (`page` or `fragment`), canonical `entryId`, optional static `uiLocale`, and `anchors` containing historical `id`/current `targetId` pairs |
|
|
288
|
+
|
|
289
|
+
`assertDocumentationProjectRouteHistory(value)` validates the independent draft. Inputs are bounded to 16 MiB and 100,000 records per collection. The renderer validates project ownership, unique bindings, canonical targets, path collisions and actual rendered anchors before its first writer callback. It snapshots the history for lazy output. Unknown versions, ambiguous bindings, alias chains/cycles and unsafe or conflicting paths raise `HIA_PROJECT_ROUTE_HISTORY_INVALID`.
|
|
290
|
+
|
|
291
|
+
Aliases resolve through the direct entry catalog before a search request. Ordinary canonical entries retain their public IDs across source-coordinate changes through the host's updated explicit bindings. The host supplies verified historical provenance and declaration correspondences as part of its publication process.
|
|
292
|
+
|
|
293
|
+
Historical fragment URLs return actual HTML prose with their recorded anchors. Historical pages share one `assets/hia-route-history.js` asset, which restores known sections through same-origin navigation with history replacement. With scripts disabled, ordinary links lead to the current entry and corresponding sections. Unknown or malformed incoming fragments retain the recovery page and its readable links. Explicit localized aliases require a generated counterpart in that UI locale.
|
|
294
|
+
|
|
295
|
+
The normal inventory includes `route-history.json` and every generated compatibility file. Publication capacity checks include those files. Existing rendering calls can continue omitting the history option.
|
|
296
|
+
|
|
297
|
+
中文说明。发布者通过独立登记维护持久公开条目身份,显式记录当前原生声明和历史地址。原生符号与源码地图仍反映实际源码。旧hash直接恢复当前正文,旧片段返回真实HTML,旧静态页在启用脚本时精确进入当前小节,禁脚本时保留对应普通链接。项目、绑定、路径与小节在首写前验证,兼容产物计入正常清单和容量。
|