= Default Stylesheet :url-default-stylesheet: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@{page-component-version}/data/stylesheets/asciidoctor-default.css :url-default-stylesheet-source: https://github.com/asciidoctor/asciidoctor/blob/v{page-component-version}.x/src/stylesheets/asciidoctor.css When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to ensure the HTML looks presentable right out of the box. This feature gets you up and running quickly by giving you a result you can preview or publish without having to do any additional work. This page covers why the default is necessary, how to apply it, and how to build on it so you don't have to create a stylesheet from scratch. NOTE: The default stylesheet that Asciidoctor provides is just that, _a default_. If you prefer a different style, you can customize it, extend it, or replace it with an entirely different one. When replacing the default stylesheet, it's important to understand that it does provide support for numerous features in AsciiDoc, as covered in the next section. You'll need to include these required styles when developing your own stylesheet if you want these features to continue to work. // TODO: we probably need a page to defines what styles any stylesheet must provide to be fully compatible with AsciiDoc == Why provide a default? Asciidoctor includes a default stylesheet to provide a nice out-of-the-box experience when generating HTML from AsciiDoc. But there's more to it. There are elements of AsciiDoc that require stylesheet support. One example is to honor *built-in roles*, such as `text-center`. In order for a role to take effect, it needs a companion CSS class in the stylesheet. To satisfy the expectations of a built-in role, a stylesheet is required. You may have noticed the floating anchors next to section titles when you hover over them. Although the HTML to make them is there, it's the stylesheet that brings them to life. Another example is to implement *list marker styles*. AsciiDoc allows you to specify the marker for a list using a block style (e.g., `loweralpha`). However, HTML does not apply these markers by default. Rather, it's something that the stylesheet provides. The default stylesheet also applies *borders and shading to table cells* to support all combinations of the frame, grid, and stripes attributes. Yet another example is the *TOC position*. To position the TOC on the left or right requires help from the stylesheet to change the layout of the page so the TOC appears as a sidebar. It's the stylesheet that handles that task. In order for the AsciiDoc experience to be complete when generating HTML, a stylesheet is required. The default stylesheet not only completes this experience, but also serves as a reference for the styles a custom stylesheet must provide. === Web fonts The default stylesheet ensures that the same fonts are selected across all platforms. By default, the browser relies on system fonts. But system fonts vary widely by platform, so users end up getting a very different experience. That's where web fonts come in. When the default stylesheet is used, the converter adds additional HTML to load open source fonts from Google Fonts. The default stylesheet, in turn, specifies a preference for these fonts. The web fonts used by the default stylesheet are as follows: Noto Serif:: body text (default) Open Sans:: headings Droid Sans Mono:: monospaced phrases and verbatim blocks Loading and preferring these web fonts ensures everyone sees the same result. == Usage When generating HTML, there's nothing special you need to do to apply the default stylesheet. Asciidoctor automatically embeds the default stylesheet into the `` of the generated HTML when you run the `asciidoctor` command. $ asciidoctor document.adoc Since no stylesheet is specified, Asciidoctor uses the default stylesheet (which is located at [.path]_data/stylesheets/asciidoctor.css_ inside the installed gem). When you view the generated HTML file, [.path]_document.html_, you'll see styled HTML, as shown here: image::default-stylesheet.png[] If you want Asciidoctor to generate HTML that links to the default stylesheet instead of embedding it in the HTML, you can instruct it to do so by setting the `linkcss` and `copycss` attributes as follows: $ asciidoctor -a linkcss -a copycss document.adoc When using the API, Asciidoctor already links to the stylesheet by default instead of embedding it (due to the default safe mode). However, Asciidoctor does not copy the stylesheet to the output directory. You would have to put it there yourself. Otherwise, the browser will not be able to find the stylesheet. To solve this problem, set the safe mode to server or lower (e.g., server, safe, or unsafe) and Asciidoctor will embed the default stylesheet, like when using the `asciidoctor` command. [,ruby] ---- require 'asciidoctor' Asciidoctor.convert_file 'document.adoc', safe: :safe ---- == Disable or modify the web fonts When the default stylesheet is used, the converter adds a `` element specialized by the attribute `rel="stylesheet"` to load web fonts from Google Fonts. You can disable this link by unsetting the `webfonts` document attribute from the CLI, API, or document header. $ asciidoctor -a webfonts! document.adoc With the web fonts absent, the browser will drop back to the fallback system fonts specified in the stylesheet. But this also provides an opportunity to use <> to load the web fonts from a different source. Rather than disabling the link, you can also use the `webfonts` attribute to change which fonts are loaded. When set, the value of the `webfonts` attribute is used as the value of the `family` query string parameter in the font-loader URL. Let's say you want to use Ubuntu Mono instead of Droid Sans Mono for monospaced text. You would set the `webfonts` attribute as follows: $ asciidoctor \ -a webfonts="Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CUbuntu+Mono:400" \ document.adoc In this case, you would still need to use <> to instruct the stylesheet to use the new font. == Customize the default stylesheet What if the default stylesheet is not exactly to your liking, but you don't want to go off and create a custom stylesheet from scratch? Can you customize it? Indeed, you can. There are at least two ways to customize the default stylesheet. One way is to add auxiliary styles using docinfo. Another way is to create a custom stylesheet, but import the default stylesheet as a starting point. [#customize-docinfo] === Auxiliary styles with docinfo Adding auxiliary styles is a great use case for xref:ROOT:docinfo.adoc[docinfo]. The docinfo feature in AsciiDoc allows you to inject auxiliary content from a file into various places in the HTML output. In this case, we're interested in the "head" position, which injects content at the bottom of the `` element. Let's say you want to change the color of headings (and other heading-like titles) to match the color of paragraph text. Start by creating a file named [.path]_docinfo.html_ (head is the default location) and populate it with a ` ---- Now tell Asciidoctor to look for and load the docinfo file using the `docinfo` attribute: $ asciidoctor -a docinfo=shared document.adoc The `