asciidoc-parser 0.19.0

Parser for AsciiDoc format
Documentation 
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use crate::tests::prelude::*;

track_file!("ref/asciidoc-lang/docs/modules/macros/pages/icons-font.adoc");

non_normative!(
    r#"
= Font Icons Mode
:url-fontawesome-icons: https://fontawesome.com/v4/icons/

Setting the `icons` attribute to `font` instructs the AsciiDoc processor to select icons from an icon font.

CAUTION: Not all converters support this mode.
If a converter does not support this mode, it will fall back to the xref:icons-image.adoc[image mode].

"#
);

#[test]
fn enable_font_based_icons() {
    verifies!(
        r#"
== Enable font-based icons

To enable image-based icons, you set the `icons` attribute in the document header to the value `font`.

[source]
----
= Document Title
:icons: font
----

This setting has no affect on the parsing of the AsciiDoc document.
It only influences the output generated by the converters.

"#
    );

    // Setting `icons` to `font` selects an icon-font glyph (`<i class="fa …">`)
    // for the icon macro, influencing only the converted output.
    let doc = Parser::default().parse(":icons: font\n\nicon:heart[]");
    assert_eq!(
        rendered_paragraphs(&doc).join("\n"),
        r#"<span class="icon"><i class="fa fa-heart"></i></span>"#
    );

    // The attribute has no affect on parsing: the source structure is unchanged
    // relative to a document without it (only the rendered output differs).
    let doc = Parser::default().parse("icon:heart[]");
    let block = doc.nested_blocks().next().unwrap();
    assert_eq!(block.raw_context().as_ref(), "paragraph");
}

// Everything below describes converter, stylesheet, and CSS behavior (font
// selection, recommended admonition-icon mappings, and callout styling) that is
// out of scope for this parser crate: it influences only the converted output,
// not the parsed model.
non_normative!(
    r#"
IMPORTANT: When converting to HTML, the stylesheet is required in order for the font-based icons to work.

== Default icon font

The icon font that is used by default is determined by the processor.
Asciidoctor, for example, uses the Font Awesome icon font.
You can see the available icons in Font Awesome on the {url-fontawesome-icons}[Font Awesome icons page^].
Using the Font Awesome icons in Asciidoctor requires online access by default.

== Default admonition icons

Since the names of admonitions doesn't necessarily match the names of icons in the icon font, the AsciiDoc processor must map admonition CSS classes to icon names.

When using Font Awesome as the icon set, the following mappings are recommended:

* note -> info-circle
* tip -> lightbulb-o
* warning -> warning
* caution -> fire
* important -> exclamation-circle

////
TODO: move to Asciidoctor

== Default font-based admonition icons

When font-based icons are enabled, Asciidoctor will draw the icons for the 5 built-in admonition types using Font Awesome.
To use the default font-based admonition icons for admonitions, set the value of the `icons` document attribute to `font` in the document header.

[source]
----
= Document Title
:icons: font

NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
----

// We need to explain that the default admonition icons have different names (i.e., `icon-note` instead of `fa-note`, because they're built in to the stylesheet.

Asciidoctor will emit HTML markup that selects the appropriate font character from the Font Awesome font for each admonition block.
For instance, Asciidoctor selects the Font Awesome icon `icon-note` for `NOTE` admonition blocks.

.Result: HTML output when the icons attribute is set to font
[source,html]
----
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>
----

This is how the admonition looks rendered.

NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!

The icons chosen are selected by the stylesheet.
The default stylesheet maps icons to the following 5 CSS classes:

* .admonitionblock td.icon .icon-note
* .admonitionblock td.icon .icon-tip
* .admonitionblock td.icon .icon-warning
* .admonitionblock td.icon .icon-caution
* .admonitionblock td.icon .icon-important

If you want to customize the icon or the color that is used, you'll need to provide a custom stylesheet or override the styles using a docinfo file.
Here's an example that shows how to change the icon for the note admonition to sticky note:

[source,css]
----
.admonitionblock td.icon .icon-note::before {
  content: "\f24a";
  color:black;
}
----
////

== Callout numbers and font icon mode

In the font icon mode, xref:verbatim:callouts.adoc[callout numbers] are displayed as enclosed numbers.
However, the icon font is not used to render these glyphs.
Instead, they are styled this way using CSS.
This is done to allow the range of callout numbers to be open-ended.
"#
);