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
|
= Convertible Contexts
When Asciidoctor converts a document, it delegates to the converter to convert each node (block or inline element) in the document as it visits each node in document order (though it's the `#content` method on a block that continues the traversal of its child nodes).
Asciidoctor then combines the result of all those calls to produce the output document.
To convert a node, Asciidoctor calls the `convert` method on the converter and passes in the node.
In some cases, it also passes in an extra transform value (e.g., `embedded`) to differentiate between different uses cases for a node of the same context.
When Asciidoctor is using a converter that extends `Asciidoctor::Converter::Base`, the converter will delegate the call to a method whose name starts with `convert_` and is followed by the context of the node (e.g., `convert_paragraph`).
The following table lists the contexts for all the built-in nodes that Asciidoctor converts, along when the name of the method the base converter will look for.
Extensions can introduce additional contexts.
.The built-in contexts of nodes that are converted by the converter
|===
|Context |Convert method on base converter
|:admonition
|convert_admonition
|:audio
|convert_audio
|:colist
|convert_colist
|:dlist
|convert_dlist
|:document
|convert_document
|:embedded
|convert_embedded
|:example
|convert_example
|:floating_title
|convert_floating_title
|:image
|convert_image
|:inline_anchor
|convert_inline_anchor
|:inline_break
|convert_inline_break
|:inline_button
|convert_inline_button
|:inline_callout
|convert_inline_callout
|:inline_footnote
|convert_inline_footnote
|:inline_image
|convert_inline_image
|:inline_indexterm
|convert_inline_indexterm
|:inline_kbd
|convert_inline_kbd
|:inline_menu
|convert_inline_menu
|:inline_quoted
|convert_inline_quoted
|:listing
|convert_listing
|:literal
|convert_literal
|:olist
|convert_olist
|:open
|convert_open
|:outline
|convert_outline
|:page_break
|convert_page_break
|:paragraph
|convert_paragraph
|:preamble
|convert_preamble
|:quote
|convert_quote
|:section
|convert_section
|:sidebar
|convert_sidebar
|:stem
|convert_stem
|:table
|convert_table
|:thematic_break
|convert_thematic_break
|:toc
|convert_toc
|:ulist
|convert_ulist
|:verse
|convert_verse
|:video
|convert_video
|===
The converter is not called to handle nodes with the `:list_item` or `:table_cell` contexts.
Instead, it's up to the converter to access these nodes from the parent node and convert them directly.
When a method to convert a block is called, the inline markup has not yet been parsed.
That parsing and subsequent conversion happens when the `#content` method is called on the node.
This is also what triggers the processor to visit the child nodes of that block.
Some methods for converting blocks have to handle the specialized behavior as indicated by the style.
For example, the `convert_listing` method also handles source blocks (listing blocks with the source style).
And `convert_dlist` handles qanda lists (dlist blocks with the qanda style).
`:embedded` is not a true context, but rather a transform of the `:document` context.
It's convert method is called instead of the one for `:document` when the document is loaded in embedded mode (i.e., the `:standalone` option on the processor is `false`).
|
