Doc To HTML

使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。

下载

最自然做法是在内用包裹说明文字；避免用title、或data-desc伪元素破坏语义；长说明宜用；必要说明须为直接子内容。

有序列表项后直接加说明文字

HTML 的 <ol></ol> 本身不提供“描述性副文本”的原生属性，但你完全可以在每个 <li> 内部自由混排文本、<span></span> 或内联元素——这是最自然、语义最清晰的做法。

常见错误是试图用 title 属性或额外的 <p></p> 块级标签破坏列表结构，导致缩进错乱或屏幕阅读器朗读异常。

• 把说明文字写在 <li> 开始标签之后、结束标签之前
• 用 <span class="desc"></span> 包裹说明部分，方便 CSS 控制样式（比如变灰、斜体）
• 避免在 <li> 内使用 <div> 或多个 <code><p></p>，否则可能触发浏览器默认外边距，破坏垂直对齐

  <ol>
  <li>初始化配置 <span class="desc">（需提前创建 config.json）</span>
  </li>
    <li>启动服务 <span class="desc">端口默认为 3000，可通过 --port 覆盖</span>
  </li>
  </ol>

  用 CSS 伪元素添加带样式的说明（不推荐初学者）

  如果你需要说明文字视觉上缩进更深、字号更小，又不想改动 HTML 结构，可以用 ::after 伪元素 + data-desc 属性。但要注意：这类内容不会被搜索引擎索引，也不被大多数屏幕阅读器读出。

  • 必须给 <li> 设置 position: relative，否则 absolute 定位会脱离上下文
  • content 中的值要加引号，否则空格会被压缩，中文可能显示异常
  • 移动端小屏下容易换行错位，需额外加 white-space: normal

• 启用热重载

li::after {
  content: attr(data-desc);
  font-size: 0.85em;
  color: #666;
  margin-left: 0.5em;
}

避免用

的 start 或 value 属性“模拟”说明

有人尝试用 start="2" 或手动设 value="3" 来腾出编号位置写文字，这属于滥用语义。浏览器只会渲染数字，无法承载任何可访问性或结构化信息。

• start 和 value 仅控制序号数值，不是占位符
• 若列表项逻辑上不是连续编号（比如跳过某步、分阶段），应拆成多个 <ol></ol>，而非硬调 value
• 用 list-style-type: none + 自定义编号时，务必同步用 aria-label 补充序号，否则无障碍失效

需要多行说明？用

折叠（现代方案）

当说明文字较长（超过两行）、且不是每项都必须展开时，<details></details> 是比纯文本更友好的选择。它原生支持展开/收起，键盘可操作，语义明确。

• 把说明放进 <details><summary>说明</summary>…</details>，放在 <li> 内部
• 不要给 <summary></summary> 加 display: block，否则会破坏默认焦点行为
• 若需默认展开，加 open 属性；但首次加载时注意避免布局抖动
• 构建产物输出路径
  查看路径规则

  默认为 dist/；可通过 vite.config.js 的 build.outDir 修改。
真正容易被忽略的是：说明文字是否构成列表项的**必要组成部分**。如果去掉说明后，列表项本身语义不完整（比如“配置数据库”没说明用哪个配置文件就无法执行），那它就应该和主文本一样，是 <li> 的直接子内容，而不是靠 CSS 或属性“附加”上去的。