--- name: "asciidoc" section: "1" platform: "linux" package: "asciidoc" version: "10.2.1-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/asciidoc" --- # asciidoc(1) converts an AsciiDoc text file to HTML or DocBook ## NAME asciidoc - converts an AsciiDoc text file to HTML or DocBook ## SYNOPSIS **asciidoc** \[*OPTIONS*\] *FILE* ## DESCRIPTION The [asciidoc(1)](/asciidoc/1.md) command translates the AsciiDoc text file *FILE* to DocBook or HTML. If *FILE* is *-* then the standard input is used. ## OPTIONS - **-a, --attribute**=*ATTRIBUTE* Define or delete document attribute. *ATTRIBUTE* is formatted like *NAME=VALUE*. Command-line attributes take precedence over document and configuration file attributes. Alternate acceptable forms are *NAME* (the *VALUE* defaults to an empty string); *NAME!* (delete the *NAME* attribute); *NAME=VALUE@* (do not override document or configuration file attributes). Values containing spaces should be enclosed in double-quote characters. This option may be specified more than once. A special attribute named *trace* controls the output of diagnostic information. - **-b, --backend**=*BACKEND* Backend output file format: *docbook45*, *docbook5*, *xhtml11*, *html4*, *html5*, *slidy*, *wordpress* or *latex* (the *latex* backend is experimental). You can also use the backend alias names *html* (aliased to *xhtml11*) or *docbook* (aliased to *docbook45*). Defaults to *html*. The **--backend** option is also used to manage backend plugins (see **PLUGIN COMMANDS**). - **-f, --conf-file**=*CONF\_FILE* Use configuration file *CONF\_FILE*.Configuration files processed in command-line order (after implicit configuration files). This option may be specified more than once. - **--doctest** Run Python doctests in *asciidoc* module. - **-d, --doctype**=*DOCTYPE* Document type: *article*, *manpage* or *book*. The *book* document type is only supported by the *docbook* backends. Default document type is *article*. - **-c, --dump-conf** Dump configuration to stdout. - **--filter**=*FILTER* Specify the name of a filter to be loaded (used to load filters that are not auto-loaded). This option may be specified more than once. The **--filter** option is also used to manage filter plugins (see **PLUGIN COMMANDS**). - **-h, --help** \[*TOPIC*\] Print help TOPIC. **--help** *topics* will print a list of help topics, **--help** *syntax* summarizes AsciiDoc syntax, **--help** *manpage* prints the AsciiDoc manpage. - **-e, --no-conf** Exclude implicitly loaded configuration files except for those named like the input file (*infile.conf* and *infile-backend.conf*). - **-s, --no-header-footer** Suppress document header and footer output. - **-o, --out-file**=*OUT\_FILE* Write output to file *OUT\_FILE*. Defaults to the base name of input file with *backend* extension. If the input is stdin then the outfile defaults to stdout. If *OUT\_FILE* is *-* then the standard output is used. - **-n, --section-numbers** Auto-number HTML article section titles. Synonym for **--attribute numbered**. - **--safe** Enable safe mode. Safe mode is disabled by default. AsciiDoc *safe mode* skips potentially dangerous scripted sections in AsciiDoc source files. - **--theme**=*THEME* Specify a theme name. Synonym for **--attribute theme**=*THEME*. The **--theme** option is also used to manage theme plugins (see **PLUGIN COMMANDS**). - **-v, --verbose** Verbosely print processing information and configuration file checks to stderr. - **--version** Print program version number. ## PLUGIN COMMANDS The [asciidoc(1)](/asciidoc/1.md) **--filter**, **--backend** and **--theme** options are used to install, remove and list AsciiDoc filter, backend and theme plugins. Syntax: ``` asciidoc OPTION install ZIP_FILE [PLUGINS_DIR] asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR] asciidoc OPTION list asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE ``` Where: **OPTION** [asciidoc(1)](/asciidoc/1.md) **--filter**, **--backend** or **--theme** option specifying the type of plugin. **PLUGIN\_NAME** A unique plugin name containing only alphanumeric or underscore characters. **ZIP\_FILE** A Zip file containing plugin resources, the name must start with the plugin name e.g. my\_filter-1.0.zip packages filter my\_filter. **PLUGINS\_DIR** The directory containing installed plugins. Each plugin is contained in its own separate subdirectory which has the same name as the plugin. **PLUGINS\_DIR** defaults to the $HOME/.asciidoc/filters (for filter plugins) or $HOME/.asciidoc/backends (for backend plugins) or $HOME/.asciidoc/themes (for theme plugins). **PLUGIN\_SOURCE** The name of a directory containing the plugin source files or the name of a single source file. The plugin commands perform as follows: **install** Create a subdirectory in **PLUGINS\_DIR** with the same name as the plugin then extract the **ZIP\_FILE** into it. **remove** Delete the **PLUGIN\_NAME** plugin subdirectory and all its contents from the **PLUGINS\_DIR**. **list** List the names and locations of all installed filter or theme plugins (including standard plugins installed in the global configuration directory). **build** Create a plugin file named **ZIP\_FILE** containing the files and subdirectories specified by **PLUGIN\_SOURCE**. File and directory names starting with a period are skipped. ## ENVIRONMENT VARIABLES **SOURCE\_DATE\_EPOCH** If the SOURCE\_DATE\_EPOCH environment variable is set to a UNIX timestamp, then the {docdate}, {doctime}, {localdate}, and {localtime} attributes are computed in the UTC time zone, with any timestamps newer than SOURCE\_DATE\_EPOCH replaced by SOURCE\_DATE\_EPOCH. (This helps software using AsciiDoc to build reproducibly.) ## EXAMPLES asciidoc asciidoc\_file\_name.txt Simply generate an html file from the asciidoc\_file\_name.txt that is in current directory using asciidoc. asciidoc -b html5 asciidoc\_file\_name.txt Use the -b switch to use one of the proposed backend or another one you installed on your computer. asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt Use the -a switch to set attributes from command-line. AsciiDoc generated its stand-alone HTML user guide containing embedded CSS, JavaScript and images from the AsciiDoc article template with this command. asciidoc -b html5 -d manpage asciidoc.1.txt Generating the asciidoc manpage using the html5 backend. ## EXIT STATUS **0** Success **1** Failure (syntax or usage error; configuration error; document processing failure; unexpected error). ## BUGS See the AsciiDoc distribution BUGS file. ## AUTHOR AsciiDoc was originally written by Stuart Rackham. Many people have contributed to it. ## RESOURCES GitHub: https://github.com/asciidoc/asciidoc-py3/ Main web site: https://asciidoc.org/ ## SEE ALSO [a2x(1)](/a2x/1.md) ## COPYING Copyright (C) 2002-2013 Stuart Rackham. Copyright (C) 2013-2022 AsciiDoc Contributors. Free use of this software is granted under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.