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
|
= Generate HTML from AsciiDoc
:navtitle: Generate HTML
== HTML 5 converter
Asciidoctor's default output format is HTML.
`html`:: The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
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.
== Generate HTML using the html5 converter
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
`xhtml`:: The XHTML variant of the HTML 5 converter.
To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
.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`.
****
|
