1ASCIIDOC(1)                                                        ASCIIDOC(1)
2
3
4

NAME

6       asciidoc - converts an AsciiDoc text file to HTML or DocBook
7

SYNOPSIS

9       asciidoc [OPTIONS] FILE
10

DESCRIPTION

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

OPTIONS

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
27       -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
35       -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
40       --doctest
41           Run Python doctests in asciidoc module.
42
43       -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
48       -c, --dump-conf
49           Dump configuration to stdout.
50
51       --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
57       -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
62       -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
66       -s, --no-header-footer
67           Suppress document header and footer output.
68
69       -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
75       -n, --section-numbers
76           Auto-number HTML article section titles. Synonym for --attribute
77           numbered.
78
79       --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
84       --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
89       -v, --verbose
90           Verbosely print processing information and configuration file
91           checks to stderr.
92
93       --version
94           Print program version number.
95

PLUGIN COMMANDS

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
101           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
106       Where:
107
108       OPTION
109           asciidoc(1) --filter, --backend or --theme option specifying the
110           type of plugin.
111
112       PLUGIN_NAME
113           A unique plugin name containing only alphanumeric or underscore
114           characters.
115
116       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
120       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
127       PLUGIN_SOURCE
128           The name of a directory containing the plugin source files or the
129           name of a single source file.
130
131       The plugin commands perform as follows:
132
133       install
134           Create a subdirectory in PLUGINS_DIR with the same name as the
135           plugin then extract the ZIP_FILE into it.
136
137       remove
138           Delete the PLUGIN_NAME plugin subdirectory and all its contents
139           from the PLUGINS_DIR.
140
141       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
146       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

ENVIRONMENT VARIABLES

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

EXAMPLES

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
165       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
169       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
175       asciidoc -b html5 -d manpage asciidoc.1.txt
176           Generating the asciidoc manpage using the html5 backend.
177

EXIT STATUS

179       0
180           Success
181
182       1
183           Failure (syntax or usage error; configuration error; document
184           processing failure; unexpected error).
185

BUGS

187       See the AsciiDoc distribution BUGS file.
188

AUTHOR

190       AsciiDoc was originally written by Stuart Rackham. Many people have
191       contributed to it.
192

RESOURCES

194       GitHub: https://github.com/asciidoc/asciidoc-py3/
195
196       Main web site: https://asciidoc.org/
197

SEE ALSO

199       a2x(1)
200

COPYING

202       Copyright (C) 2002-2013 Stuart Rackham.
203
204       Copyright (C) 2013-2020 AsciiDoc Contributors.
205
206       Free use of this software is granted under the terms of the GNU General
207       Public License version 2 (GPLv2).
208
209
210
211                                  01/18/2023                       ASCIIDOC(1)
Impressum