Chapter 7. HTML5 and XHTML 1.1

The xhtml11 and html5 backends embed or link CSS and JavaScript files in their outputs, there is also a themes plugin framework.

If the AsciiDoc linkcss attribute is defined then CSS and JavaScript files are linked to the output document, otherwise they are embedded (the default behavior).
The default locations for CSS and JavaScript files can be changed by setting the AsciiDoc stylesdir and scriptsdir attributes respectively.
The default locations for embedded and linked files differ and are calculated at different times — embedded files are loaded when asciidoc(1) generates the output document, linked files are loaded by the browser when the user views the output document.
Embedded files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files from AsciiDoc configuration directories to the correct location relative to the output document.

Table 7.1. Stylesheet file locations

stylesdir attribute	Linked location (linkcss attribute defined)	Embedded location (linkcss attribute undefined)
Undefined (default).	Same directory as the output document.	`stylesheets` subdirectory in the AsciiDoc configuration directory (the directory containing the backend conf file).
Absolute or relative directory name.	Absolute or relative to the output document.	Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file).

Table 7.2. JavaScript file locations

scriptsdir attribute	Linked location (linkcss attribute defined)	Embedded location (linkcss attribute undefined)
Undefined (default).	Same directory as the output document.	`javascripts` subdirectory in the AsciiDoc configuration directory (the directory containing the backend conf file).
Absolute or relative directory name.	Absolute or relative to the output document.	Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file).

7.1. Themes

The AsciiDoc theme attribute is used to select an alternative CSS stylesheet and to optionally include additional JavaScript code.

Theme files reside in an AsciiDoc configuration directory named themes/<theme>/ (where <theme> is the the theme name set by the theme attribute). asciidoc(1) sets the themedir attribute to the theme directory path name.
The theme attribute can also be set using the asciidoc(1) --theme option, the --theme option can also be used to manage theme plugins.
AsciiDoc ships with two themes: flask and volnitsky.
The <theme>.css file replaces the default asciidoc.css CSS file.
The <theme>.js file is included in addition to the default asciidoc.js JavaScript file.
If the data-uri attribute is defined then icons are loaded from the theme icons sub-directory if it exists (i.e. the iconsdir attribute is set to theme icons sub-directory path).
Embedded theme files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files to the location of the output documents.
Linked CSS and JavaScript theme files are linked to the same linked locations as other CSS and JavaScript files.

For example, the command-line option --theme foo (or --attribute theme=foo) will cause asciidoc(1) to search configuration file locations 1 for a sub-directory called themes/foo containing the stylesheet foo.css and optionally a JavaScript file name foo.js.