1ASCIIDOCTOR(1) Asciidoctor Manual ASCIIDOCTOR(1)
2
6 asciidoctor - converts AsciiDoc source files to HTML, DocBook and other
7 formats
8
10 asciidoctor [OPTION]... FILE...
11
13 The asciidoctor(1) command converts the AsciiDoc source file(s) FILE to
14 HTML5, DocBook 5, DocBook 4.5, man(ual) page and other custom output
15 formats.
16 If FILE is - then the AsciiDoc source is read from standard input.
18
20 Security Settings
21 -B, --base-dir=DIR
22 Base directory containing the document and resources. Defaults to
23 the directory containing the source file, or the working directory
24 if the source is read from a stream. When combined with the safe
25 mode setting, can be used to chroot the execution of the program.
26 -S, --safe-mode=SAFE_MODE
28 Set safe mode level: unsafe, safe, server or secure. Disables
29 potentially dangerous macros in source files, such as include::[].
30 If not set, the safe mode level defaults to unsafe when Asciidoctor
31 is invoked using this script.
32 --safe
34 Set safe mode level to safe. Enables include directives, but
35 prevents access to ancestor paths of source file. Provided for
36 compatibility with the asciidoc command. If not set, the safe mode
37 level defaults to unsafe when Asciidoctor is invoked using this
38 script.
39 Document Settings
41 -a, --attribute=ATTRIBUTE
42 Define, override or delete a document attribute. Command-line
43 attributes take precedence over attributes defined in the source
44 file unless the value ends with @.
45 ATTRIBUTE is normally formatted as a key-value pair, in the form
47 NAME=VALUE. Alternate acceptable forms are NAME (where the VALUE
48 defaults to an empty string), NAME! (unassigns the NAME attribute)
49 and NAME=VALUE@ (where VALUE does not override value of NAME
50 attribute if it’s already defined in the source document). Values
51 containing spaces should be enclosed in quotes.
52 This option may be specified more than once.
54 -b, --backend=BACKEND
56 Backend output file format: html5, docbook5, docbook45 and manpage
57 are supported out of the box. You can also use the backend alias
58 names html (aliased to html5) or docbook (aliased to docbook5).
59 Other values can be passed, but if Asciidoctor cannot resolve the
60 backend to a converter, it will fail. Defaults to html5.
61 -d, --doctype=DOCTYPE
63 Document type: article, book, manpage or inline. Sets the root
64 element when using the docbook backend and the style class on the
65 HTML body element when using the html backend. The book document
66 type allows multiple level-0 section titles in a single document.
67 The manpage document type enables parsing of metadata necessary to
68 produce a man page. The inline document type allows the content of
69 a single paragraph to be formatted and returned without wrapping it
70 in a containing element. Defaults to article.
71 Rendering Control
73 -C, --compact
74 Compact the output by removing blank lines. (No longer in use).
75 -D, --destination-dir=DIR
77 Destination output directory. Defaults to the directory containing
78 the source file, or the working directory if the source is read
79 from a stream. If specified, the directory is resolved relative to
80 the working directory.
81 -E, --template-engine=NAME
83 Template engine to use for the custom converter templates. The gem
84 with the same name as the engine will be loaded automatically. This
85 name is also used to build the full path to the custom converter
86 templates. If a template engine is not specified, it will be
87 auto-detected based on the file extension of the custom converter
88 templates found.
89 -e, --eruby
91 Specifies the eRuby implementation to use for executing the custom
92 converter templates written in ERB. Supported values are erb and
93 erubis. Defaults to erb.
94 -I, --load-path=DIRECTORY
96 Add the specified directory to the load path, so that -r can load
97 extensions from outside the default Ruby load path. This option may
98 be specified more than once.
99 -n, --section-numbers
101 Auto-number section titles. Synonym for --attribute numbered.
102 -o, --out-file=OUT_FILE
104 Write output to file OUT_FILE. Defaults to the base name of the
105 input file suffixed with backend extension. The file is resolved
106 relative to the working directory. If the input is read from
107 standard input or a named pipe (fifo), then the output file
108 defaults to stdout. If OUT_FILE is -, then the output file is
109 written to standard output.
110 -r, --require=LIBRARY
112 Require the specified library before executing the processor, using
113 the standard Ruby require. This option may be specified more than
114 once.
115 -s, --no-header-footer
117 Suppress the document header and footer in the output.
118 -T, --template-dir=DIR
120 A directory containing custom converter templates that override one
121 or more templates from the built-in set. (requires tilt gem)
122 If there is a subfolder that matches the engine name (if
124 specified), that folder is appended to the template directory path.
125 Similarly, if there is a subfolder in the resulting template
126 directory that matches the name of the backend, that folder is
127 appended to the template directory path.
128 This option may be specified more than once. Matching templates
130 found in subsequent directories override ones previously
131 discovered.
132 Processing Information
134 -q, --quiet
135 Silence warnings.
136 --trace
138 Include backtrace information on errors. Not enabled by default.
139 -v, --verbose
141 Verbosely print processing information and configuration file
142 checks to stderr.
143 -t, --timings
145 Display timings information (time to read, parse and convert).
146 Program Information
148 -h, --help [TOPIC]
149 Print the help message. Show the command usage if TOPIC is not
150 specified (or not recognized). Dump the Asciidoctor man page (in
151 troff/groff format) if TOPIC is manpage.
152 -V, --version
154 Print program version number.
155 -v can also be used if no other flags or arguments are present.
157
159 Asciidoctor honors the SOURCE_DATE_EPOCH environment variable. If this
160 variable is assigned an integer value, that value is used as the epoch
161 of all input documents and as the local date and time. See <https://
162 reproducible-builds.org/specs/source-date-epoch/> for more information
163 about this environment variable.
164
166 0
167 Success.
168 1
170 Failure (syntax or usage error; configuration error; document
171 processing failure; unexpected error).
172
174 Refer to the Asciidoctor issue tracker at <https://github.com/
175 asciidoctor/asciidoctor/issues?q=is%3Aopen>.
176
178 Asciidoctor was written by Dan Allen, Ryan Waldron, Jason Porter, Nick
179 Hengeveld and other contributors.
180 AsciiDoc was written by Stuart Rackham and has received contributions
182 from many other individuals.
183
185 Project web site: <http://asciidoctor.org>
186 Git source repository on GitHub: <https://github.com/asciidoctor/
188 asciidoctor>
189 GitHub organization: <https://github.com/asciidoctor>
191 Discussion list / forum: <http://discuss.asciidoctor.org>
193
195 Copyright (C) 2012-2017 Dan Allen, Ryan Waldron and the Asciidoctor
196 Project. Free use of this software is granted under the terms of the
197 MIT License.
198
200 Dan Allen, Sarah White, Ryan Waldron
201 Author(s).
202Asciidoctor 1.5.6.1 2017-07-23 ASCIIDOCTOR(1)