1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
= Generate HTML from AsciiDoc
:navtitle: Generate HTML
Asciidoctor's default output format is HTML (specifically HTML 5).
That means when you run Asciidoctor without any parameters, it will produce HTML.
This page explains how to use Asciidoctor to convert AsciiDoc to HTML.
== Backend and converter
Asciidoctor's built-in HTML converter is registered for the `html` and `html5` backends.
The HTML converter generates HTML 5 that's styled with CSS3.
It may include JavaScript to support additional integrations, such as client-side syntax highlighting.
[horizontal]
Backend names:: `html`, `html5`
Converter class:: `Asciidoctor::Converter::Html5Converter`
Output format:: HTML
Output file extension:: .html
WARNING: A standalone HTML document generated by the built-in HTML converter loads web fonts from Google Fonts, which are then referenced by the default stylesheet.
The xref:default-stylesheet.adoc[default stylesheet] makes use of web fonts to ensure the document renders consistently across platforms.
Concerns have been raised that Google Fonts do not comply with GDPR.
If this presents a problem, you can xref:default-stylesheet.adoc#disable-or-modify-the-web-fonts[opt out of the use of Google Fonts].
When this is done, the default stylesheet reverts to using generic font families (e.g., sans-serif), which are mapped to system fonts by your browser.
The consequence is that the appearance of the document will be different and system dependent due to a reliance on system fonts.
If the backend name is prefixed with `x` (e.g., `xhtml`), the converter will <<xhtml,generate XHTML>>, the XML variant of HTML.
== Generate HTML
In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
=== Create and save an AsciiDoc document
. To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plaintext file.
+
.my-document.adoc
[#ex-my-doc,asciidoc]
----
include::example$my-document.adoc[tags=title;body]
----
. Make sure to save the file with the _.adoc_ file extension.
=== Convert an AsciiDoc document to HTML
To convert [.path]_my-document.adoc_ to HTML from the command line:
. Open a terminal.
. Switch to the directory that contains the [.path]_my-document.adoc_ document
. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document.
+
--
$ asciidoctor my-document.adoc
Remember, Asciidoctor's default converter is html5, so it isn't necessary to specify it with the `-b` command.
--
. You won't see any messages printed to the console.
Type `ls` to view the files in the directory or navigate to the directory in a file manager.
You should see a new file named [.path]_my-document.html_.
+
--
$ ls
my-document.adoc my-document.html
Asciidoctor derives the name of the output document from the name of the input document.
--
. Open [.path]_my-document.html_ in your web browser.
Your document should look like the image below.
+
--
image::my-document.png[]
The document's text, titles, and link are styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
As a result, you could save [.path]_my-document.html_ to any computer and it will look the same.
--
. If you want to preview the HTML in the terminal, you can use this command instead:
$ asciidoctor my-document.adoc -o - | w3m - -T text/html
[#xhtml]
== Generate XHTML
[horizontal]
Backend names:: `xhtml`, `xhtml5`
Converter class:: `Asciidoctor::Converter::Html5Converter`
Output format:: XML variant of HTML
Output file extension:: .html
.Produce XHTML using the xhtml5 backend option
$ asciidoctor -b xhtml5 my-document.adoc
To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option:
.Produce XHTML using custom templates
$ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc
.Black Box Decoded: XHTML and htmlsyntax
****
XHTML output is a special mode of the built-in HTML5 converter.
It is activated by prefixing the backend value with `x` (e.g., `xhtml` or `xhtml5`).
This hint implicitly assigns the `htmlsyntax` attribute to the value `xml`, which normally has the value `html`.
For all other converters, the `htmlsyntax` attribute is not set explicitly.
If you want a converter template that's written in Slim or Haml to output XHTML instead of the default HTML, you need to set the `htmlsyntax` attribute to `xml` explicitly.
Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the `:format` option to `:html5`.
****
|
