Asciidoctor项目升级指南：从1.5.x迁移到2.0版本

Asciidoctor项目升级指南：从1.5.x迁移到2.0版本

asciidoctor :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor

前言

本文旨在帮助使用Asciidoctor 1.5.x版本的用户顺利升级到2.0版本。作为一款功能强大的文档处理工具，Asciidoctor在2.0版本中引入了多项改进和新特性，同时也对一些旧语法进行了调整。了解这些变化对于确保文档的兼容性和充分利用新功能至关重要。

升级前的注意事项

在开始升级前，建议您：

1. 备份现有文档
2. 在测试环境中先行验证
3. 逐步更新文档语法
4. 了解兼容性模式的使用场景

主要变更内容

1. 行内格式化语法变更

2.0版本对文本格式化语法进行了标准化处理：

| 功能 | 旧语法 | 新语法 | 说明 | |------|--------|--------|------| | 斜体文本 | italic text | _italic text_ | 兼容模式下仍可使用旧语法 | | 等宽文本 | +monospace text+ | `monospace text` | 兼容模式下仍可使用旧语法 | | 字面等宽文本 | `literal monospace text` | `+literal monospace text+` | 兼容模式下仍可使用旧语法 | | 弯引号 | ``double quotes'' | "double quotes" | 建议使用新语法或直接输入Unicode字符 | | 弯单引号 | single quotes' | 'single quotes' | 建议使用新语法或直接输入Unicode字符 |

技术建议：新语法更加直观且与Markdown风格保持一致，建议逐步迁移到新语法体系。

2. 目录(TOC)功能改进

目录功能在2.0版本中得到了简化和统一：

| 功能 | 旧语法 | 新语法 | 说明 | |------|--------|--------|------| | 可滚动左侧目录 | toc2 | :toc: left | 新语法更加语义化 | | 目录位置设置 | toc-placement/toc-position | :toc: <value> | 统一使用:toc属性 | | 自定义目录位置 | :toc-placement: manual | :toc: macro | 使用宏方式更灵活 |

最佳实践：新目录系统提供了更清晰的语义表达，建议在升级时优先更新目录相关语法。

3. 文档标题格式变更

文档标题的书写方式发生了变化：

| 功能 | 旧语法 | 新语法 | 说明 | |------|--------|--------|------| | 两行式标题 | Title + ===== | = Title | 旧语法会隐式启用兼容模式 |

迁移建议：虽然两行式标题仍被支持，但建议统一使用单行式标题以获得最佳兼容性。

4. API变更

对于开发者而言，API也有重要变化：

| 功能 | 旧方法 | 新方法 | |------|--------|--------| | 渲染方法 | .render(input, options = {}) | .convert(input, options = {}) |

开发建议：新方法名convert更准确地反映了实际功能，建议在代码中及时更新。

新特性概览

2.0版本引入了众多新功能，包括但不限于：

1. 增强的表格处理能力
2. 改进的扩展机制
3. 更强大的属性系统
4. 优化的性能表现

建议查阅官方发布说明了解完整的新特性列表。

兼容性模式

当无法立即更新所有文档时，可以使用兼容模式：

:compat-mode:

注意：兼容模式并非支持所有旧语法，它只是提供过渡期的临时解决方案。

升级策略建议

1. 分阶段升级：先升级工具，再逐步更新文档语法
2. 自动化检查：使用脚本检查文档中的旧语法
3. 团队培训：确保所有文档编写者了解新语法规范
4. 文档测试：升级后全面测试文档输出效果

结语

Asciidoctor 2.0带来了许多改进和新功能，虽然升级过程可能需要一些调整，但这些变化最终将带来更好的文档编写体验和更强大的功能。建议用户充分利用新版本的特性，逐步将文档迁移到新的语法体系。

asciidoctor :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor