如何使用 AsciiDoc 创建博客

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

A introduction to creating documents in LaTeX

图片来源

Opensource.com

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

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

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

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

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

一种不同的开发平台

当我开发博客时，我从“内容优先”的想法开始，并尽量不让自己陷入平台之中。这是一个好主意，但实际上，我不断地调整站点。然后我再稍微调整一下，然后一个周末就过去了，我还没有写任何内容。我把所有的时间都花在摆弄主题或处理后端服务上。

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

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

文档工作流程

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

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

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

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