1ASCIIDOC(1) ASCIIDOC(1)
2
6 asciidoc - converts an AsciiDoc text file to HTML or DocBook
7
9 asciidoc [OPTIONS] FILE
10
12 The asciidoc(1) command translates the AsciiDoc text file FILE to
13 DocBook or HTML. If FILE is - then the standard input is used.
14
16 -a, --attribute=ATTRIBUTE
17 Define or delete document attribute. ATTRIBUTE is formatted like
18 NAME=VALUE. Command-line attributes take precedence over document
19 and configuration file attributes. Alternate acceptable forms are
20 NAME (the VALUE defaults to an empty string); NAME! (delete the
21 NAME attribute); NAME=VALUE@ (do not override document or
22 configuration file attributes). Values containing spaces should be
23 enclosed in double-quote characters. This option may be specified
24 more than once. A special attribute named trace controls the output
25 of diagnostic information.
26 -b, --backend=BACKEND
28 Backend output file format: docbook45, docbook5, xhtml11, html4,
29 html5, slidy, wordpress or latex (the latex backend is
30 experimental). You can also use the backend alias names html
31 (aliased to xhtml11) or docbook (aliased to docbook45). Defaults to
32 html. The --backend option is also used to manage backend plugins
33 (see PLUGIN COMMANDS).
34 -f, --conf-file=CONF_FILE
36 Use configuration file CONF_FILE.Configuration files processed in
37 command-line order (after implicit configuration files). This
38 option may be specified more than once.
39 --doctest
41 Run Python doctests in asciidoc module.
42 -d, --doctype=DOCTYPE
44 Document type: article, manpage or book. The book document type is
45 only supported by the docbook backends. Default document type is
46 article.
47 -c, --dump-conf
49 Dump configuration to stdout.
50 --filter=FILTER
52 Specify the name of a filter to be loaded (used to load filters
53 that are not auto-loaded). This option may be specified more than
54 once. The --filter option is also used to manage filter plugins
55 (see PLUGIN COMMANDS).
56 -h, --help [TOPIC]
58 Print help TOPIC. --help topics will print a list of help topics,
59 --help syntax summarizes AsciiDoc syntax, --help manpage prints the
60 AsciiDoc manpage.
61 -e, --no-conf
63 Exclude implicitly loaded configuration files except for those
64 named like the input file (infile.conf and infile-backend.conf).
65 -s, --no-header-footer
67 Suppress document header and footer output.
68 -o, --out-file=OUT_FILE
70 Write output to file OUT_FILE. Defaults to the base name of input
71 file with backend extension. If the input is stdin then the outfile
72 defaults to stdout. If OUT_FILE is - then the standard output is
73 used.
74 -n, --section-numbers
76 Auto-number HTML article section titles. Synonym for --attribute
77 numbered.
78 --safe
80 Enable safe mode. Safe mode is disabled by default. AsciiDoc safe
81 mode skips potentially dangerous scripted sections in AsciiDoc
82 source files.
83 --theme=THEME
85 Specify a theme name. Synonym for --attribute theme=THEME. The
86 --theme option is also used to manage theme plugins (see PLUGIN
87 COMMANDS).
88 -v, --verbose
90 Verbosely print processing information and configuration file
91 checks to stderr.
92 --version
94 Print program version number.
95
97 The asciidoc(1) --filter, --backend and --theme options are used to
98 install, remove and list AsciiDoc filter, backend and theme plugins.
99 Syntax:
100 asciidoc OPTION install ZIP_FILE [PLUGINS_DIR]
102 asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR]
103 asciidoc OPTION list
104 asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE
105 Where:
107 OPTION
109 asciidoc(1) --filter, --backend or --theme option specifying the
110 type of plugin.
111 PLUGIN_NAME
113 A unique plugin name containing only alphanumeric or underscore
114 characters.
115 ZIP_FILE
117 A Zip file containing plugin resources, the name must start with
118 the plugin name e.g. my_filter-1.0.zip packages filter my_filter.
119 PLUGINS_DIR
121 The directory containing installed plugins. Each plugin is
122 contained in its own separate subdirectory which has the same name
123 as the plugin. PLUGINS_DIR defaults to the $HOME/.asciidoc/filters
124 (for filter plugins) or $HOME/.asciidoc/backends (for backend
125 plugins) or $HOME/.asciidoc/themes (for theme plugins).
126 PLUGIN_SOURCE
128 The name of a directory containing the plugin source files or the
129 name of a single source file.
130 The plugin commands perform as follows:
132 install
134 Create a subdirectory in PLUGINS_DIR with the same name as the
135 plugin then extract the ZIP_FILE into it.
136 remove
138 Delete the PLUGIN_NAME plugin subdirectory and all its contents
139 from the PLUGINS_DIR.
140 list
142 List the names and locations of all installed filter or theme
143 plugins (including standard plugins installed in the global
144 configuration directory).
145 build
147 Create a plugin file named ZIP_FILE containing the files and
148 subdirectories specified by PLUGIN_SOURCE. File and directory names
149 starting with a period are skipped.
150
152 SOURCE_DATE_EPOCH
153 If the SOURCE_DATE_EPOCH environment variable is set to a UNIX
154 timestamp, then the {docdate}, {doctime}, {localdate}, and
155 {localtime} attributes are computed in the UTC time zone, with any
156 timestamps newer than SOURCE_DATE_EPOCH replaced by
157 SOURCE_DATE_EPOCH. (This helps software using AsciiDoc to build
158 reproducibly.)
159
161 asciidoc asciidoc_file_name.txt
162 Simply generate an html file from the asciidoc_file_name.txt that
163 is in current directory using asciidoc.
164 asciidoc -b html5 asciidoc_file_name.txt
166 Use the -b switch to use one of the proposed backend or another one
167 you installed on your computer.
168 asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
170 Use the -a switch to set attributes from command-line. AsciiDoc
171 generated its stand-alone HTML user guide containing embedded CSS,
172 JavaScript and images from the AsciiDoc article template with this
173 command.
174 asciidoc -b html5 -d manpage asciidoc.1.txt
176 Generating the asciidoc manpage using the html5 backend.
177
179 0
180 Success
181 1
183 Failure (syntax or usage error; configuration error; document
184 processing failure; unexpected error).
185
187 See the AsciiDoc distribution BUGS file.
188
190 AsciiDoc was originally written by Stuart Rackham. Many people have
191 contributed to it.
192
194 GitHub: https://github.com/asciidoc/asciidoc-py3/
195 Main web site: https://asciidoc.org/
197
199 a2x(1)
200
202 Copyright (C) 2002-2013 Stuart Rackham.
203 Copyright (C) 2013-2020 AsciiDoc Contributors.
205 Free use of this software is granted under the terms of the GNU General
207 Public License version 2 (GPLv2).
208 01/18/2023 ASCIIDOC(1)