Kramdown AsciiDoc 使用教程

Kramdown AsciiDoc 使用教程

kramdown-asciidoc A kramdown extension for converting Markdown documents to AsciiDoc. 项目地址: https://gitcode.com/gh_mirrors/kr/kramdown-asciidoc

1. 项目介绍

Kramdown AsciiDoc 是一个开源项目，旨在提供一个将 Markdown 文档转换为 AsciiDoc 格式的工具。它基于 Kramdown Markdown 解析器，并生成适用于 Asciidoctor 的现代 AsciiDoc 语法。此工具适用于那些需要将 Markdown 文档转换为 AsciiDoc 格式的开发者。

2. 项目快速启动

首先，确保您的系统中已安装 Ruby 2.3 或更高版本。然后，通过以下命令安装 Kramdown AsciiDoc gem：

gem install kramdown-asciidoc

安装完成后，您可以使用以下命令来转换 Markdown 文件到 AsciiDoc 格式：

kramdoc sample.md

默认情况下，该命令会在与输入文件相同的目录下生成一个名为 sample.adoc 的 AsciiDoc 文件。

如果您需要指定输出文件名，可以使用 -o 选项：

kramdoc -o result.adoc sample.md

要将输出重定向到控制台（即标准输出），请使用 - 作为特殊值：

kramdoc -o - sample.md

查看所有可用选项，请使用 -h 选项：

kramdoc -h

3. 应用案例和最佳实践

配置共享图片目录

如果您的 Markdown 文档中的图片有一个共同的目录前缀，例如 images/，您可以配置转换器来提取这个前缀，并可选地将其提升到文档头部。

例如，如果您想要转换以下 Markdown 源：

# 文档标题
![Octocat](images/octocat.png)

可以使用以下命令来提取 images/ 前缀并将其添加到输出文档的头部：

kramdoc -a imagesdir=images sample.md

自动生成 IDs

您可以通过启用 --auto-ids 标志来自动为每个没有明确分配 ID 的标题（即标题）生成显式 ID：

kramdoc --auto-ids sample.md

4. 典型生态项目

Kramdown AsciiDoc 作为文档转换工具，可以与 Asciidoctor 生态系统中的其他工具配合使用，例如 Asciidoctor PDF、Asciidoctor EPUB 等等，以生成各种格式的文档。它也常用于自动化文档工作流程，特别是在需要将 Markdown 文档集成到 AsciiDoc 项目的场景中。

kramdown-asciidoc A kramdown extension for converting Markdown documents to AsciiDoc. 项目地址: https://gitcode.com/gh_mirrors/kr/kramdown-asciidoc