默认样式表

当您使用HTML转换器生成独立的HTML文档时，Asciidoctor会包含一个默认的样式表以确保HTML一开始就呈现得很好。这个功能让您能够快速启动，因为它为您提供了一个可以预览或发布的结果，而无需做任何额外的工作。

这个页面介绍了默认设置为何必要、如何应用它，以及如何在其基础上进行构建，这样你就不必从头开始创建一个样式表。

Note	Asciidoctor 提供的默认样式表正如其名称，仅仅是一个_默认_的样式表。如果你更倾向于不同的风格，你可以自定义它、扩展它，或者用一个完全不同的样式表替换它。当替换默认样式表时，理解它确实为AsciiDoc中的众多特性提供了支持是很重要的，正如下一节所述。如果你想要这些特性继续工作，开发自己的样式表时你需要包含这些必需的样式。

为什么要提供一个默认值？

Asciidoctor 在从 AsciiDoc 生成 HTML 时包含了一个默认样式表，以提供良好的开箱即用体验。但还有更多内容。有些 AsciiDoc 的元素需要样式表的支持。

一个例子是为了尊重*内置角色*，例如`text-center`。为了让角色生效，它需要在样式表中有一个伴随的CSS类。为了满足内置角色的期望，需要一个样式表。

你可能已经注意到当你将鼠标悬停在它们上面时，旁边的部分标题旁会出现浮动锚点。虽然制作它们的HTML代码已经存在，但使它们活跃起来的是样式表。

另一个例子是实现*列表标记样式*。AsciiDoc允许你使用块样式（例如，loweralpha）来指定列表的标记。然而，HTML默认并不应用这些标记。而是样式表提供的功能。

默认样式表还将*边框和底纹应用于表格单元*，以支持 frame、grid 和 stripes 属性的所有组合。

又一个例子是*TOC位置*。要将TOC定位在左边或右边，需要样式表的帮助来改变页面布局，使TOC看起来像一个侧边栏。这是由样式表来处理的任务。

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

网页字体

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

默认情况下，浏览器依赖系统字体。但系统字体因平台而异，所以用户最终会得到非常不同的体验。这就是网络字体发挥作用的地方。

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

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

诺托衬线: 正文文本（默认）
Open Sans: 标题
Droid Sans Mono: 等宽短语和逐字块

加载并优先使用这些网页字体可以确保每个人看到相同的结果。

用法

在生成HTML时，你不需要做任何特别的事情来应用默认样式表。当你运行`asciidoctor`命令时，Asciidoctor会自动将默认样式表嵌入到生成的HTML的`<head>`中。

$ asciidoctor document.adoc

既然没有指定样式表，Asciidoctor将使用默认的样式表（位于已安装宝石内的[.path]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

禁用或修改网页字体

当使用默认样式表时，转换器会添加一个通过属性`rel="stylesheet"`专门化的`<link>`元素，以从Google Fonts加载网络字体。您可以通过从命令行界面（CLI）、应用程序接口（API）或文档头部取消设置`webfonts`文档属性来禁用此链接。

$ asciidoctor -a webfonts! document.adoc

如果网页字体不存在，浏览器将回退到样式表中指定的备用系统字体。但这也提供了一个使用 docinfo 从不同的源载入网页字体的机会。

而不是禁用链接，您也可以使用 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的一个很好的用例。AsciiDoc中的docinfo特性允许你从一个文件中注入辅助内容到HTML输出的不同位置。在这种情况下，我们关注的是“head”位置，它会在`<head>`元素的底部注入内容。

假设你想要改变标题（以及其他类似标题的文字）的颜色，使其与段落文本的颜色相匹配。首先创建一个名为_docinfo.html_的文件（默认放置于头部位置），然后在其中用一个`<style>`元素填充必要的样式。

docinfo.html

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

现在告诉Asciidoctor使用`docinfo`属性来查找并加载docinfo文件。

$ asciidoctor -a docinfo=shared document.adoc

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

让更多元素能够通过CSS进行定位

如果你想给你的内容中特定的元素设置样式，你需要使它们能够被CSS定位。换句话说，必须能够用CSS选择器来选中它们。在AsciiDoc中有两种机制可以让你做到这一点：

身份证明: 你几乎可以给AsciiDoc中的任何元素添加一个ID，使用ID属性。AsciiDoc中的ID属性会转换为HTML中的`id`属性。然后你可以使用`#<id>`的语法在CSS中定位该元素（且只定位该元素）以修改它的样式，其中`<id>`是你指定的值。在一份文档中，每个ID只能使用一次。
角色: 你可以使用role attribute将角色添加到AsciiDoc中几乎任何元素上。AsciiDoc中的role属性转换为HTML中的`class`属性。然后，你可以使用CSS中的语法`. <role>`，其中`<role>`是你指定的值，来定位该元素（以及任何其他共享相同角色的元素），以便修改它的样式。一个角色可以在文档中多次使用。你甚至可以在样式表中通过添加元素名称（例如，span.appname）或额外的角色（例如，.varname.global）来分别定位共享相同角色的不同元素。

对于你引入的任何ID或角色，你必须为其提供自定义样式，以便它能有任何视觉效果。

扩展默认样式表

不用从头开始编写一个自定义样式表，你可以导入默认样式表，并对你想要更改的任何样式进行覆盖（利用CSS的层叠特性）。这也是使用默认样式表的好方法，但从不同的CDN加载网络字体。

让我们再次更改标题（以及其他类似标题的字体）的颜色，使其与段落文字的颜色相匹配。首先创建一个名为_my-asciidoctor.css_的样式表。接下来，添加一个`@import`声明来导入默认样式表。这里我们使用CDN直接从仓库中拉取默认样式表，但你可以放到浏览器能够访问的任何位置。然后，添加另一个`@import`声明来导入默认样式表使用的网络字体（这些字体并没有被默认样式表导入）。最后，在这些`@import`指令下方添加你的覆盖样式。以下是总体的样子。

@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
@import "{url-default-stylesheet}";

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"`链接到它，来避免这次网络调用。

要获取编译后的默认样式表，您可以从源代码库中https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@{page-component-version}/data/stylesheets/asciidoctor-default.css[下载它^]，或者您可以使用以下的`asciidoctor`命令（或等效命令）将其写入当前目录：

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

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

require 'asciidoctor'

Asciidoctor::Stylesheets.instance.write_primary_stylesheet '.'

你也可以下载https://github.com/asciidoctor/asciidoctor/blob/v{page-component-version}.x/src/stylesheets/asciidoctor.css[默认样式表的源码^]，如果你想用它作为开发自定义样式表的起点。

要了解更多关于如何应用自定义样式表的信息，请参阅 custom-stylesheet.html。

有不同的主题吗？

默认样式表不提供不同的主题。您可能对尝试由Asciidoctor Skins项目提供的主题感兴趣。这些样式表的方法是从CDN加载默认样式表，然后叠加额外的样式来生成多种主题。您还可以选择下载默认样式表的源代码，并根据需要进行自定义。

Caution

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

要了解如何应用自定义样式表，请参阅custom-stylesheet.html。