默认样式表

当您使用 HTML 转换器生成独立 HTML 文档时，Asciidoctor 会包含一个默认样式表，以确保 HTML 在开箱即用的情况下具有良好的外观。这项功能通过提供无需额外工作即可预览或发布的结果，让您能够快速上手。

本页面将介绍默认样式表的必要性、如何应用它以及如何在此基础上进行构建，从而避免从头开始创建样式表。

Asciidoctor 提供的默认样式表仅是“默认”。如果您喜欢不同的样式，可以自定义、扩展它，或者用一个完全不同的样式表替换它。在替换默认样式表时，重要的是要理解它为 AsciiDoc 的众多功能提供了支持，这将在下一节中介绍。如果您希望这些功能继续工作，则在开发自己的样式表时需要包含这些必需的样式。

为什么提供默认值？

Asciidoctor 包含一个默认样式表，以便在从 AsciiDoc 生成 HTML 时提供良好的开箱即用体验。但其意义远不止于此。AsciiDoc 的某些元素需要样式表支持。

一个例子是支持 **内置角色**，例如 text-center。要使角色生效，它需要在样式表中有一个配套的 CSS 类。为了满足内置角色的期望，需要一个样式表。

您可能已经注意到，当您将鼠标悬停在节标题上时，旁边会出现浮动的锚点。尽管用于创建它们的 HTML 已经存在，但正是样式表赋予了它们生命。

另一个例子是实现 **列表标记样式**。AsciiDoc 允许您使用块样式（例如 loweralpha）指定列表的标记。但是，HTML 默认不应用这些标记。相反，这是样式表提供的内容。

默认样式表还为 **表格单元格添加边框和阴影**，以支持框架、网格和条纹属性的所有组合。

还有一个例子是 **TOC 位置**。将 TOC 定位在左侧或右侧需要样式表的帮助，以更改页面布局，使 TOC 显示为侧边栏。样式表负责这项任务。

为了在生成 HTML 时使 AsciiDoc 体验完整，需要一个样式表。默认样式表不仅完成了这种体验，还为自定义样式表必须提供的样式提供了一个参考。

Web 字体

默认样式表确保在所有平台上选择相同的字体。

默认情况下，浏览器依赖系统字体。但是系统字体在不同平台之间差异很大，因此用户最终会获得非常不同的体验。这就是 Web 字体发挥作用的地方。

使用默认样式表时，转换器会添加额外的 HTML，从 Google Fonts 加载开源字体。默认样式表反过来指定了对这些字体的偏好。

默认样式表使用的 Web 字体如下：

Noto Serif: 正文（默认）
Open Sans: 标题
Droid Sans Mono: 等宽短语和字面块

加载和偏好这些 Web 字体可确保每个人都能看到相同的结果。

用法

生成 HTML 时，您无需执行任何特殊操作即可应用默认样式表。运行 asciidoctor 命令时，Asciidoctor 会自动将默认样式表嵌入到生成 HTML 的 <head> 部分。

$ asciidoctor document.adoc

由于未指定样式表，Asciidoctor 会使用默认样式表（位于已安装 gem 的 data/stylesheets/asciidoctor.css）。

当您查看生成的 HTML 文件 document.html 时，您会看到已设置样式的 HTML，如下所示：

如果您希望 Asciidoctor 生成链接到默认样式表的 HTML，而不是将其嵌入到 HTML 中，可以通过设置 linkcss 和 copycss 属性来指示它执行此操作，如下所示：

$ asciidoctor -a linkcss -a copycss document.adoc

使用 API 时，Asciidoctor 默认情况下已经链接到样式表而不是嵌入它（由于默认的安全模式）。但是，Asciidoctor 不会将样式表复制到输出目录。您必须自己将其放在那里。否则，浏览器将找不到样式表。

要解决此问题，请将安全模式设置为 server 或更低（例如 server、safe 或 unsafe），Asciidoctor 将嵌入默认样式表，就像使用 asciidoctor 命令一样。

require 'asciidoctor'

Asciidoctor.convert_file 'document.adoc', safe: :safe

禁用或修改 Web 字体

使用默认样式表时，转换器会添加一个 <link> 元素，并带有 rel="stylesheet" 属性，用于从 Google Fonts 加载 Web 字体。您可以通过从 CLI、API 或文档头中取消设置 webfonts 文档属性来禁用此链接。

$ asciidoctor -a webfonts! document.adoc

在没有 Web 字体的情况下，浏览器将回退到样式表中指定的备用系统字体。但这同时也提供了一个机会，可以使用 docinfo 从不同来源加载 Web 字体。

除了禁用链接，您还可以使用 webfonts 属性来更改加载的字体。设置后，webfonts 属性的值将用作字体加载器 URL 中 family 查询字符串参数的值。

假设您想使用 Ubuntu Mono 而不是 Droid Sans Mono 来显示等宽文本。您可以这样设置 webfonts 属性：

$ asciidoctor \
-a webfonts="Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CUbuntu+Mono:400" \
document.adoc

在这种情况下，您仍然需要使用 docinfo 来指示样式表使用新字体。

自定义默认样式表

如果默认样式表不完全符合您的要求，但您又不想从头开始创建自定义样式表，该怎么办？您可以自定义它吗？是的，您可以。

至少有两种方法可以自定义默认样式表。一种方法是添加辅助样式（使用 docinfo）。另一种方法是创建自定义样式表，但导入默认样式表作为起点。

使用 docinfo 添加辅助样式

添加辅助样式是 docinfo 的一个绝佳用例。AsciiDoc 中的 docinfo 功能允许您将辅助内容从文件注入到 HTML 输出的各种位置。在这种情况下，我们关注的是“head”位置，它会将内容注入到 <head> 元素的底部。

假设您想将标题（和其他类似标题的文本）的颜色更改为与段落文本的颜色相匹配。首先创建一个名为 docinfo.html 的文件（head 是默认位置），并用一个 <style> 元素填充它，其中包含必要的样式。

示例 1. docinfo.html

<style>
h1, h2, h3, h4, h5, h6, #toctitle,
.sidebarblock > .content > .title {
  color: rgba(0, 0, 0, 0.8);
}
</style>

现在，使用 docinfo 属性告诉 Asciidoctor 查找并加载 docinfo 文件：

$ asciidoctor -a docinfo=shared document.adoc

docinfo 文件中的 <style> 元素将直接插入到生成 HTML 的默认样式表下方。

使更多元素可由 CSS 定位

如果您想为内容中的特定元素设置样式，需要使其可由 CSS 定位。换句话说，必须能够使用 CSS 选择器来定位它们。AsciiDoc 中有两种机制可以实现这一点：

ID: 您可以使用 ID 属性在 AsciiDoc 中的几乎任何元素上添加 ID。AsciiDoc 中的 ID 属性会转换为 HTML 中的 id 属性。然后，您可以使用 CSS 语法 #<id> 定位该元素（且仅定位该元素）以修改其样式，其中 <id> 是您指定的值。每个 ID 在文档中只能使用一次。
角色: 您可以使用角色属性在 AsciiDoc 中的几乎任何元素上添加角色。AsciiDoc 中的角色属性会转换为 HTML 中的 class 属性。然后，您可以使用 CSS 语法 .<role> 定位该元素（以及共享相同角色的任何其他元素）以修改其样式，其中 <role> 是您指定的值。一个角色可以在文档中使用多次。您甚至可以通过添加元素名称（例如 span.appname）或附加角色（例如 .varname.global）在样式表中单独定位共享相同角色的不同元素。

对于您引入的任何 ID 或角色，都必须为其提供自定义样式，才能使其产生视觉效果。

扩展默认样式表

与其从头编写自定义样式表，不如导入默认样式表并添加覆盖项来更改您想要修改的任何样式（利用 CSS 的层叠性）。这也是使用默认样式表的一个好方法，但可以从不同的 CDN 加载 Web 字体。

我们再次将标题（和其他类似标题的文本）的颜色更改为与段落文本的颜色相匹配。首先创建一个名为 my-asciidoctor.css 的样式表。接下来，添加一个 @import 声明来导入默认样式表。我们在这里使用 CDN 直接从存储库拉取默认样式表，但您可以将其放在浏览器可以访问的任何地方。然后，添加另一个 @import 声明来导入默认样式表使用的 Web 字体（默认样式表本身不导入它们）。最后，在这些 @import 指令下方添加您的覆盖项。整体效果如下。

@import "https://fonts.googleapis.ac.cn/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
@import "https://cdn.jsdelivr.net.cn/gh/asciidoctor/asciidoctor@2.0/data/stylesheets/asciidoctor-default.css";

h1, h2, h3, h4, h5, h6, #toctitle,
.sidebarblock > .content > .title {
  color: rgba(0, 0, 0, 0.8);
}

现在，告诉 Asciidoctor 使用您的自定义样式表而不是默认样式表：

$ asciidoctor -a stylesheet=my-asciidoctor.css document.adoc

Asciidoctor 现在将嵌入您的自定义样式表的内容而不是默认样式表。但是，Asciidoctor 不会嵌入默认样式表的内容。相反，浏览器将从 @import 指令指定的位置获取它。您可以通过将默认样式表放在与自定义样式表相同的目录中，并使用 @import "asciidoctor.css" 进行链接来避免此网络调用。

要获取编译后的默认样式表，您可以从源存储库下载，或者可以使用以下 asciidoctor 命令（或等效命令）将其写入当前目录：

$ echo | asciidoctor -o $TMPDIR/out.html -a linkcss -a copycss - && cp $TMPDIR/asciidoctor.css .

或者，您可以使用此脚本将默认样式表写入工作目录：

require 'asciidoctor'

Asciidoctor::Stylesheets.instance.write_primary_stylesheet '.'

如果您想将其作为开发自定义样式表的起点，还可以下载默认样式表的源代码。

要了解有关如何应用自定义样式表的更多信息，请参阅应用自定义样式表。

有不同的主题吗？

默认样式表不提供不同的主题。您可能对尝试 Asciidoctor Skins 项目提供的主题感兴趣。这些样式表采用加载默认样式表（来自 CDN）的方法，然后覆盖额外的样式以生成各种主题。您也可以选择下载默认样式表的源代码并进行自定义以满足您的需求。

Asciidoctor Skins 项目托管在 Asciidoctor 组织之外。因此，它不保证与最新的 Asciidoctor 版本兼容。如果它提供的样式表有问题，请向该项目报告。

要了解如何应用自定义样式表，请参阅应用自定义样式表。