Xberg 样式化 HTML 输出稳定性契约（HTML Styling Contract）深度解析

后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载Xberg 的样式化 HTML 渲染器Styled HTML Renderer会将提取到的文档结构渲染为带语义化kb-*CSS 类与--kb-*CSS 自定义属性的 HTML。本文以仓库中的 HTML Styling Contract 参考文档 为骨架结合 渲染器源码、配置结构体 与配套的 HTML Output 指南系统讲解这一输出契约的稳定性保证、CSS 变量与类名清单、版本化规则以及如何在应用层安全、可维护地依赖这套契约进行二次定制。一、什么是样式化 HTML 输出契约Xberg 的提取管线在output_format html且配置了html_output时会构建StyledHtmlRenderer而不是默认的 comrak 纯文本 HTML 渲染器把内部文档模型InternalDocument直接渲染为 HTML5。这个渲染器产出的 HTML 具有两个核心特征每个结构元素都带语义化 CSS 类默认以kb-前缀开头例如kb-doc、kb-p、kb-table每个内置主题都在:root上定义一组--kb-*CSS 自定义属性design tokens供主题与用户样式统一取色。所谓契约Contract就是 Xberg 对这两类对外暴露的接口给出的跨版本稳定性承诺只要你的应用在次版本升级范围内依赖这些类名与 CSS 变量就可以放心升级而不用担心样式体系被破坏。该契约的完整定义记录在 html-styling-contract.md而渲染器源码的模块注释也明确引用了这一约定见 html_styled.rs 头部注释。二、稳定性保证Stability Guarantee契约的核心承诺只有一句话Styled HTML 渲染器发射的所有 CSS 类名以配置的class_prefix为前缀默认kb-以及所有 CSS 自定义属性--kb-*在次版本minor version之间保持稳定。具体包含三层含义类名稳定kb-p、kb-h2、kb-table这类类名在 4.8 → 4.9 这样的次版本升级中不会被删除或改名CSS 变量稳定--kb-text-color、--kb-max-width等变量名及其语义在次版本间不变破坏性变更只发生在主版本类名或变量的移除、重命名只会在主版本如 4.x → 5.x升级时发生且所有变更会记录在 CHANGELOG.md 与迁移指南中。从源码看这一保证是结构级而非视觉级的渲染器通过write!(buf, r#p class{p}p#)这类模板拼接统一发射类名见 render_elements类名前缀在构造渲染器时即已从配置中解析并固化因此只要前缀配置不变输出的类名体系就是确定且可预测的。三、CSS 自定义属性--kb-*清单所有内置主题default、github、dark、lightunstyled除外都会在:root上定义以下 12 个 CSS 自定义属性。下表完整列出默认default主题下的默认值属性默认值default 主题描述--kb-font-familysystem-ui, sans-serif正文字体栈--kb-mono-font-familyui-monospace, monospace代码字体栈--kb-text-color#1a1a1a正文文字颜色--kb-bg-color#ffffff背景颜色--kb-heading-color#111111标题颜色--kb-link-color#0066cc链接颜色--kb-link-hover-color#004499链接悬停颜色--kb-code-bg#f5f5f5代码块背景--kb-code-color#c7254e行内代码颜色--kb-border-color#e0e0e0通用边框颜色--kb-table-border#cccccc表格边框颜色--kb-blockquote-border#0066cc引用块左边框--kb-max-width72ch内容最大宽度--kb-line-height1.6正文行高这些默认值可以直接在源码中核对default 主题的 CSS 定义于 DEFAULT_CSS 常量github 主题为 GITHUB_CSSdark 主题为 DARK_CSS。值得注意的是github主题将--kb-max-width设为80ch、字体栈换成-apple-system/BlinkMacSystemFont/Segoe UI栈而dark主题把背景换为#0d1117、文字换为#e6edf3——这说明变量语义稳定但数值会随主题不同而变化用户代码不应硬编码任何主题的默认数值。利用变量做主题微调由于变量语义受契约保护最安全的自定义方式就是覆盖变量而非重写整套样式。例如来自 html-output.mdx 的 CSS Customization 章节:root { --kb-font-family: Inter, sans-serif; --kb-text-color: #333; --kb-max-width: 60ch; }这样既保留了主题其余的设计又只改动你关心的局部。四、类名清单Class Reference契约引用 HTML Output 指南的 Class Reference 章节 作为完整的类名参考。以下是核心类名与对应 HTML 元素、语义的完整清单类名元素描述kb-docdiv根容器kb-contentmain内容区kb-doc-titleh1文档标题kb-h、kb-h1..kb-h6h1..h6各级标题kb-pp段落kb-list、kb-ul、kb-olul、ol列表kb-lili列表项kb-blockquoteblockquote引用块kb-prepre代码块kb-codecode行内/块级代码kb-tabletable表格kb-thead、kb-tbodythead、tbody表头/表体kb-th、kb-td、kb-trth、td、tr表单元格/行kb-figurefigure图片容器kb-imgimg图片kb-page-breakhr分页符kb-footnoteaside脚注定义kb-footnote-refsup脚注引用kb-citationcite引文kb-linka超链接kb-metadatadl元数据块kb-formulapre数学公式kb-slidesection幻灯片节kb-dt、kb-dddt、dd定义术语/描述kb-admonitionaside提示块admonitionkb-groupdiv分组内容除上表外渲染器还会按需发射一些辅助类例如代码块的kb-lang-{lang}语言类、列表项带原文标记时的kb-list-marker、OCR 纯文本输出时的kb-ocr-text、公式输出时的kb-math配合data-math-styledisplay、提示块按类型的kb-admonition-{kind}、以及幻灯片标记的data-slide{number}属性——这些细节都可以在 html_styled.rs 的各渲染函数 中逐一核对。自定义类前缀默认前缀是kb-如果你的宿主应用已经占用了kb-*命名空间可以通过class_prefix改成任意只含字母、数字、连字符与下划线的字符串。设置成my-后所有类名变为my-doc、my-content、my-h1等见 html-output.mdx 的 Custom prefix 提示。渲染器在构造时会对前缀做校验见 StyledHtmlRenderer::new 的校验逻辑不合法的前缀会直接返回校验错误。需要特别留意的是内置主题的 CSS 只针对kb-*类名编写。如果你在非unstyled主题下自定义了前缀主题样式将不会命中任何元素渲染器会给出tracing::warn!警告并建议使用unstyled主题配合自定义前缀同一段源码 L168-L176。这是契约中非常实用的一个坑位提示值得在集成时注意。五、版本化规则Versioning契约明确规定了三种变更类型的版本归属次版本如 4.8 → 4.9类名与 CSS 自定义属性只增不减additive only不存在删除或重命名。这意味着你在次版本升级后可以安全地保留现有样式表。主版本如 4.x → 5.x允许移除或重命名类名所有变更都会在迁移指南中记录。升级主版本前应检查迁移说明重新对齐样式表。主题 CSS视觉外观颜色、间距、字体等纯视觉层面的调整可以在次版本中变化稳定性保证只覆盖结构类名structural class names。也就是说同一版本内的视觉观感允许演进但用什么类名去选中哪个结构这件事不会变。这组规则的工程含义很清晰应用层应当基于kb-*类名与--kb-*变量编写样式而不是基于某个主题的具体颜色值后者不受契约保护。六、配置与实操如何在应用中使用这套契约配置结构体HtmlOutputConfig定义于 crates/xberg/src/core/config/html_output.rs字段如下可对照 configuration.md 的 HtmlOutputConfig 章节字段类型默认值说明cssOptionStringNone行内 CSS 字符串注入在主题样式表之后与css_file同时设置时拼接在其后css_fileOptionPathBufNoneCSS 文件路径在渲染器构造时加载一次与css同时设置时拼接在其前themeHtmlThemeHtmlTheme::Unstyled内置主题default、github、dark、light、unstyledclass_prefixStringkb-应用到所有发射类名的前缀embed_cssbooltrue是否把解析后的 CSS 写进style块false时只输出结构标记配合外部样式表其中HtmlTheme枚举html_output.rs L82-L100在序列化时使用小写命名github、dark等五个主题的差异可参考 html-output.mdx 的内置主题表主题说明unstyled默认不内置任何 CSS只输出带kb-*类的结构标记适合完全自备样式表default系统字体栈、中性配色、72ch 最大宽度定义全部 CSS 自定义属性githubGitHub Markdown 风格调色板、标题下边框、80ch 最大宽度dark深色背景#0d1117、浅色文字适合终端/IDE 集成light极简浅色主题间距宽松快速开始示例以 Python 为例对应 html-output.mdx 的 Quick Startfrom xberg import ExtractInput, ExtractionConfig, HtmlOutputConfig, HtmlTheme, extract config ExtractionConfig( output_formathtml, html_outputHtmlOutputConfig(themeHtmlTheme.GitHub), ) output await extract(ExtractInput(kinduri, uridoc.pdf), configconfig) result output.results[0] print(result.content) # 带样式与 kb-* 类的 HTML 字符串Rust 侧对应写法html-output.mdx L53-L67use xberg::{extract, ExtractInput, ExtractionConfig, HtmlOutputConfig, HtmlTheme}; let config ExtractionConfig { output_format: html.to_string(), html_output: Some(HtmlOutputConfig { theme: HtmlTheme::GitHub, ..Default::default() }), ..Default::default() }; let output extract(ExtractInput::from_uri(doc.pdf), config).await?; println!({}, output.results[0].content);CLI 方式CLI 提供了五个--html-*覆盖开关见 html-output.mdx 的 CLI Flags 表实现位于 crates/xberg-cli/src/commands/overrides/html.rs标志说明--html-theme THEME内置主题default、github、dark、light、unstyled隐含--content-format html--html-css CSS追加在主题样式表之后的行内 CSS 字符串--html-css-file PATH渲染时加载的 CSS 文件路径最大 1 MiB--html-class-prefix PREFIXCSS 类前缀默认kb-只允许字母数字、连字符与下划线--html-no-embed-css抑制style块改用外部样式表典型用法xberg extract doc.pdf --html-theme github \ --html-css :root { --kb-max-width: 60ch; } xberg extract doc.pdf --html-theme github \ --html-css-file custom.css从 apply_html_styled 实现 可以看到只要出现任意--html-*标志CLI 就会把output_format强制切换为 HTML 并合并进html_output配置其中未知主题名会回退为HtmlTheme::Default。完全自备样式表如果希望完全摆脱内置样式使用unstyled主题并关闭style块html-output.mdx L215-L225config ExtractionConfig( output_formathtml, html_outputHtmlOutputConfig( themeHtmlTheme.Unstyled, embed_cssFalse, ), )此时输出只有结构标记 kb-*类名。注意即便在unstyled下--kb-*变量仍会定义在:root上因此你自己的样式表依然可以引用这些 token参见 HtmlTheme::Unstyled 的文档注释。七、源码级实现与测试佐证渲染流程StyledHtmlRenderer实现了InternalRenderertrait注册名为html。其 render 方法 输出结构固定为div classkb-doc ← 根容器若 embed_css 为真紧跟 style 块 main classkb-content ← 内容区 …结构元素… /main /div所有元素文本通过v_htmlescape::escape_string做 HTML 转义esc 函数避免注入风险。CSS 的拼接顺序为主题样式表 →css_file内容 → 行内css见 StyledHtmlRenderer::new并且会在拼接后剥离/style//STYLE序列作为注入防护。契约在测试中的落地html_output_quality.rs 用InternalDocumentBuilder构造含标题、段落、列表、代码块、表格的富文档并校验 HTML 输出的空行、尾随空白、CRLF、body闭合等质量问题issue_69_styled_html_slide_section.rs 是契约的回归测试它逐字节断言 ODP 演示文稿输出为section classkb-slide>赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐OpenMed CLI 机器可读契约machine-contract实战--json 信封、退出码与稳定错误码的确定性脚本化输出OpenMed CLI 机器可读契约machine contract实战 json 信封、退出码与稳定错误码的确定性脚本化输出 OpenMed 的命令行工人工智能NLP医疗健康数据脱敏本地部署大模型AI 应用MCP 服务联邦学习OpenMAIC PPTX 文本序列化器深度解析textSerializer 的七级样式继承与 HTML 输出管线OpenMAIC PPTX 文本序列化器深度解析textSerializer 的七级样式继承与 HTML 输出管线 导读 本指南以 OpenMAIC 仓库中人工智能AI 应用AI Agent多智能体教育前端后端RAGauto-video-generateor完全指南从0到1打造你的AI视频创作流水线auto video generateor完全指南从0到1打造你的AI视频创作流水线 想要快速制作专业的解说视频却苦于缺乏技术能力auto video geAI 应用媒体生成语音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考