如何使用 AsciiDoc 创建博客

将 AsciiDoc 标记语言与 Hugo 发布平台结合使用，可以生成快速、易于维护的网站和博客。

A introduction to creating documents in LaTeX

图片来源

Opensource.com

我每天都在使用内容管理工具，并为首选标记语言是 AsciiDoc 的文档编写者提供支持。它语法简单，但功能足够强大，即使是硬核文档爱好者也会满意。AsciiDoc 允许您以更自然的方式编写文档，并对其进行清晰的标记，以便在网络上或以 PDF 形式呈现。这让我想到，“如果能够完全使用 AsciiDoc 来维护网站，那不是会很方便吗？”

经过一番谷歌搜索并与同事聊天后，我找到了 Hugo，这是一个发布平台，可以将用 Markdown 或 AsciiDoc 编写的文章转换为可在网络上使用的内容。它是一个功能非常丰富的平台，具有用于处理模板和主题的丰富语言，而且使用起来非常有趣。

对我来说，一个很大的优势是 Hugo 不需要数据库来支持功能丰富的博客站点。页面以 HTML 呈现，因此站点速度极快且非常易于维护。它甚至自带服务器，因此我可以在工作时测试我的站点。只要您的服务器可以提供 HTML，一切就都很好。

缺少数据库或对 PHP 等语言的需求降低了 SQL 注入的风险，使其特别适用于创建安全站点。它还使网站比传统平台上的网站更快，并且将其与内容分发网络 (CDN) 结合使用可以生成非常快速的网站。

它支持通常由博客平台驱动的任务；例如，当添加新文章时，它可以自动填充 RSS 源。您团队中的每个人都可以在本地运行站点的副本，这样他们就可以在草稿状态下处理他们的文章，并在准备好后再发布它们。如果您将其与 Git 分支策略结合使用，则多位作者可以处理博客和文章，然后在准备好发布时将其放回您的主分支。其他交互元素（例如评论）可以使用 Disqus 添加。

一种不同的开发平台

当我开发博客时，我首先想到的是“内容优先”，并尽量不被平台所束缚。这是一个很好的想法，但实际上，我一直在调整站点。然后我又稍微调整了一下，然后一个周末就过去了，我还没有写任何内容。我把所有时间都花在了摆弄主题或处理后端服务上。

将 Hugo 平台与 AsciiDoc 标记语言和 AsciiDoctor（AsciiDoc 的数字瑞士军刀）结合使用，可以帮助我专注于内容和结构，而不是演示。Hugo 有一个不错的模板系统，所以我可以用更少的代码做更多的事情。AsciiDoc 帮助我编写结构良好的文档，Hugo 使用 AsciiDoctor 将文档转换为其他格式，例如 PDF 或 Linux 手册页，就像我编写它们一样。因为我可以在本地以 HTML 预览它们，所以我可以识别出我的内容需要改进的地方。通过在控制台中运行 Hugo，我可以在每次保存文档时看到问题，这样我就可以修复它们并继续前进。这与我通常的例程不同

“我的博客文章完成了！现在要把我的杰作发送到全世界！…… 等等，为什么我的所有文本都是 H1？我讨厌我自己。”
—我，凌晨 3 点，睡眠不足，咖啡喝太多

文档工作流程

我通常用简单的英语写我的初稿。我为每篇文章使用 Git 中的新分支，这使得事情保持简洁明了，直到我准备好发布。一旦我对我的文章进行几次编辑以确保一切顺利，我就会添加 AsciiDoc 标记，以便 Hugo 可以将文章格式化为干净的 HTML。当文章准备好发布时，我将其合并回我的主分支。

我经常处理包含标准化文本或内容（例如，关于许可、支持或公司描述的信息）的文档。我使用 include 语句来处理这些样板内容，并在我的模板中进行设置或定义内容类型以添加它，具体取决于我正在处理的内容。这种方法使标准化的、重复的内容更加模块化，更易于维护。

您还可以定义您的主题可以用来组织内容的元数据，例如，标记文章、对内容进行分组、将页面定义为“解决方案”或“常见问题解答”等。这对于 AsciiDoc 尤其方便，因为文档的标题将具有标准的元数据部分，文章和博客文章之间可能会有所不同。我可以在 Hugo 中定义元数据，当我创建新内容时，它会为我完成工作。

我首选的编辑器 Vim，有可用于 AsciiDoc 的语法文件。如果您正在寻找更直观的内容处理方法，我推荐使用 Atom 编辑器和 AsciiDoc Preview 插件。它提供页面的实时预览，使您可以轻松检查您的文档。Atom 由 GitHub 创建，并内置了对 Git 的支持，因此可以轻松地跨不同分支处理文档。