样式表模式

HTML 转换器可以配置为将样式表的 CSS 直接嵌入到 HTML 中、链接到样式表文件，或完全禁用它。无论您使用的是默认样式表还是自定义样式表，这些模式都可用。本页介绍控制样式表应用方式的文档属性。

HTML 转换器仅在生成独立的 HTML 文档时应用样式表。这是因为样式表位于 HTML 的<head>元素内，而转换器仅为独立输出生成该元素。

嵌入样式表

当安全模式为 server 或更低时，HTML 转换器的默认行为是读取样式表文件，将其内容包含在<style>元素中，并将其直接嵌入到生成的 HTML 的<head>元素中。此默认设置使 HTML 更具可移植性，因为移动文件时不会丢失样式表。

但是，如果安全模式为 secure，转换器将链接到样式表文件。如果您在生成的 HTML 中看到一个指向样式表文件的链接，而不是您期望的嵌入式样式表，请检查您的安全模式设置。

无论您使用的是默认样式表还是自定义样式表，相同的两条规则都适用。

您已经知道，当安全模式为 secure 时，HTML 转换器会链接到样式表。但是，可以独立于安全模式启用此行为。如果您将大量 AsciiDoc 文档转换为 HTML，并希望它们共享相同的样式表，这可能很有益。它还可以使检查 HTML 更加简单。

如果设置了linkcss文档属性，转换器将链接到样式表而不是嵌入它。要链接到样式表，转换器会使用由rel="stylesheet"属性专门化的<link>元素。href属性将使用相对路径引用样式表。

linkcss文档属性必须在文档头结束之前设置才能生效。一种方法是在文档头中设置该属性：

示例 1. 在文档头中设置 linkcss 属性
= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
:linkcss:

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

您还可以使用 API 或 CLI（此处显示）设置linkcss

$ asciidoctor -a linkcss my-document.adoc

无论哪种情况，如果您检查输出文件 my-document.html 的<head>元素，您将看到 HTML 链接到样式表。

示例 2. my-document.html
<link rel="stylesheet" href="./asciidoctor.css">

由于我们没有指定样式表，转换器会链接到默认样式表。但是，这个样式表在哪里？让我们找出答案。

将样式表复制到输出目录

如果您链接到样式表文件，则该样式表文件必须在引用的路径下可用，以便浏览器可以访问它。对于简单的情况，Asciidoctor 会为您处理这个问题。

如果安全模式为 server 或更低，并且设置了linkcss文档属性，Asciidoctor 会将样式表复制到输出目录，以便 HTML 可以链接到它。使用默认样式表时，Asciidoctor 会将 CSS 写入输出目录中的 asciidoctor.css 文件。如果您指定自定义样式表，Asciidoctor 将复制该文件，保留文件名。此实用程序即使您指定了一个输出文件在不同目录于源文件的位置，也有效。

共同的责任

虽然转换器负责嵌入或链接到样式表文件，但复制样式表的任务由处理器本身（而不是转换器）处理。

如果安全模式为 secure，Asciidoctor 将不会复制样式表文件，因此到它的链接将断开（除非您单独复制该文件）。

让我们回顾一下前面的示例

$ asciidoctor -a linkcss my-document.adoc

运行此命令后，样式表文件 asciidoctor.css 将被复制到与生成的 HTML 文件 my-document.html 相同的目录中。键入ls查看目录中的文件。您应该看到一个名为 asciidoctor.css 的文件。

$ ls
asciidoctor.css  my-document.adoc  my-document.html

当您在浏览器中查看 HTML 文件时，您应该会看到应用了默认样式表。

复制还是不复制

Asciidoctor 是否将样式表复制到输出目录由copycss文档属性控制。copycss属性默认设置为，除非安全模式为 secure。

要阻止 Asciidoctor 复制样式表（独立于安全模式），请取消设置copycss文档属性。

copycss文档属性必须在文档头结束之前取消设置才能生效。一种方法是在文档头中取消设置该属性：

示例 3. 在文档头中取消设置 copycss 属性
= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
:linkcss:
:!copycss:

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

您还可以使用 API 或 CLI（此处显示）取消设置copycss

$ asciidoctor -a linkcss -a copycss! my-document.adoc

无论哪种情况，如果您检查输出目录，您将看不到样式表文件 asciidoctor.css（除非它已经存在）。

我们将在自定义样式表页面上再次看到copycss属性，作为覆盖要复制的样式表位置的一种方式。

禁用样式表

在生成嵌入式 HTML 时，样式表被有效地禁用，因为嵌入式 HTML 不包含<head>元素。如果您不希望转换器在独立的 HTML 中包含样式表，请使用 CLI 取消设置stylesheet属性。

$ asciidoctor -a stylesheet! my-document.adoc

您必须取消设置stylesheet属性的原因是它默认被设置（为一个空值）。当stylesheet属性被设置但为空时，HTML 转换器会使用默认样式表。通过取消设置此属性，我们告诉转换器根本不使用样式表。

当您查看生成的 HTML 文件 my-document.html 时，您将看到没有应用任何样式的纯 HTML，如下所示：

no stylesheet
当stylesheet属性被取消设置时，linkcss和copycss属性将被忽略。

现在您有了一个干净的开始，让我们学习如何应用您自己的自定义样式表。