AsciiDoc Home Page ================== // Web page meta data. :keywords: AsciiDoc, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page :description: AsciiDoc is a text document format for writing notes, + documentation, articles, books, ebooks, slideshows, + web pages, man pages and blogs. AsciiDoc files can be + translated to many formats including HTML, PDF, EPUB, + man page. .{revdate}: AsciiDoc {revnumber} Released ************************************************************************ Read the link:CHANGELOG.html[CHANGELOG] for release highlights and a full list of all additions, changes and bug fixes. Changes are documented in the updated link:userguide.html[User Guide]. See the link:INSTALL.html[Installation page] for downloads and and installation instructions. ************************************************************************ Introduction ------------ {description} AsciiDoc.py is a legacy processor for this syntax, handling an older rendition of AsciiDoc. As such, this will not properly handle the https://projects.eclipse.org/projects/asciidoc.asciidoc-lang[current AsciiDoc specification]. It is suggested that unless you specifically require the AsciiDoc.py toolchain, you should find a processor that handles the modern AsciiDoc syntax. AsciiDoc.py is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user. AsciiDoc.py is free software and is licensed under the terms of the 'GNU General Public License version 2' (GPLv2). TIP: The pages you are reading were written using AsciiDoc, to view the corresponding AsciiDoc source click on the *Page Source* menu item in the left hand margin. Overview and Examples --------------------- You write an AsciiDoc document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc(1) command. The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and DocBook markups. DocBook can be post-processed to presentation formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript using readily available Open Source tools. Example Articles ~~~~~~~~~~~~~~~~ - This XHTML version of the link:asciidoc.css-embedded.html[AsciiDoc User Guide] was generated by AsciiDoc from link:asciidoc.txt[this AsciiDoc file]. - Here's the link:asciidoc.html[same document] created by first generating DocBook markup using AsciiDoc and then converting the DocBook markup to HTML using 'DocBook XSL Stylesheets'. - The User Guide again, this time a link:chunked/index.html[chunked version]. - AsciiDoc generated this link:article-standalone.html[stand-alone HTML file] containing embedded CSS, JavaScript and images from this link:article.txt[AsciiDoc article template] with this command: asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt - The same link:article.txt[AsciiDoc article template] generated link:article-html5-toc2.html[this HTML 5] (the 'toc2' attribute puts a table of contents in the left margin) from this command: asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt - The same link:article.txt[AsciiDoc article template] produced this link:article.html[HTML file] and this link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc. [[X7]] Example Books ~~~~~~~~~~~~~ AsciiDoc markup supports all the standard DocBook frontmatter and backmatter sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries. - This link:book.txt[AsciiDoc book] produced link:book.html[this HTML file] using the 'DocBook XSL Stylesheets'. - The link:asciidoc.pdf[PDF formatted AsciiDoc User Guide] was generated from asciidoc(1) DocBook output. - The link:asciidoc.epub[EPUB formatted AsciiDoc User Guide] was generated using link:a2x.1.html[a2x]. - This link:book.epub[EPUB formatted book skeleton] was generated using link:a2x.1.html[a2x]. - This link:book-multi.txt[multi-part AsciiDoc book] produced link:book-multi.html[this HTML file] using the 'DocBook XSL Stylesheets'. Example UNIX Man Pages ~~~~~~~~~~~~~~~~~~~~~~ HTML formatted AsciiDoc man pages link:asciidoc.1.css-embedded.html[with stylesheets] and link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc from link:asciidoc.1.txt[this file]. This link:asciidoc.1[roff formatted man page] was generated from asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL Stylesheets. [[X8]] Example Slideshows ~~~~~~~~~~~~~~~~~~ The https://www.w3.org/Talks/Tools/Slidy2/[Slidy] backend generates HTML slideshows that can be viewed in any web browser. What's nice is that you can create completely self contained slideshows including embedded images. - Here is the link:slidy.html[slidy backend documentation] slideshow and here is it's link:slidy.txt[AsciiDoc source]. - An link:slidy-example.html[example slidy slideshow] and the link:slidy-example.txt[AsciiDoc source]. Example Web Site ~~~~~~~~~~~~~~~~ The link:README-website.html[AsciiDoc website] is included in the AsciiDoc distribution (in `./website/` and `./docs/`) as an example website built using AsciiDoc. See `./website/README-website.txt`. More examples ~~~~~~~~~~~~~ - See below: <>. - Example link:newtables.html[Tables]. eBook Publication ----------------- The two most popular open eBook formats are https://en.wikipedia.org/wiki/EPUB[EPUB] and PDF. The AsciiDoc link:a2x.1.html[a2x] toolchain wrapper makes it easy to link:publishing-ebooks-with-asciidoc.html[publish EPUB and PDF eBooks with AsciiDoc]. See also <> and link:epub-notes.html[AsciiDoc EPUB Notes]). Blogpost weblog client ---------------------- https://srackham.wordpress.com/blogpost-readme/[blogpost] is a command-line weblog client for publishing AsciiDoc documents to https://wordpress.org/[WordPress] blog hosts. It creates and updates weblog posts and pages directly from AsciiDoc source documents. Source code highlighter ----------------------- AsciiDoc includes a link:source-highlight-filter.html[source code highlighter filter] that uses https://www.gnu.org/software/src-highlite/[GNU source-highlight] to highlight HTML outputs. You also have the option of using the https://pygments.org/[Pygments] highlighter. [[X3]] Mathematical Formulae --------------------- You can include mathematical formulae in AsciiDoc XHTML documents using link:asciimath.html[ASCIIMath] or link:latexmathml.html[LaTeXMathML] notation. The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX source to an image that is automatically inserted into the AsciiDoc output documents. AsciiDoc also has 'latexmath' macros for DocBook outputs -- they are documented in link:latexmath.pdf[this PDF file] and can be used in AsciiDoc documents processed by `dblatex(1)`. Editor Support -------------- - An AsciiDoc syntax highlighter for the Vim text editor is included in Vim. + .Syntax highlighter screenshot image::images/highlighter.png[height=400,caption="",link="images/highlighter.png"] - Dag Wieers has implemented an alternative Vim syntax file for AsciiDoc which can be found here https://github.com/dagwieers/asciidoc-vim. - David Avsajanishvili has written a source highlighter for AsciiDoc files for https://wiki.gnome.org/Projects/GtkSourceView[GtkSourceView] (used by https://wiki.gnome.org/Apps/Gedit[gedit] and a number of other applications). The project is hosted here: https://launchpad.net/asciidoc-gtk-highlight - AsciiDoc resources for the Emacs editor can be found on the https://www.emacswiki.org/emacs/AsciiDoc[AsciiDoc page] at the https://www.emacswiki.org/emacs/EmacsWiki[Emacs Wiki]. - Christian Zuckschwerdt has written a https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle] for AsciiDoc. Try AsciiDoc on the Web ----------------------- Thaddée Tyl has written an online live editor named https://espadrine.github.io/AsciiDocBox/[AsciiDocBox] to try AsciiDoc in your browser. You can use https://gist.asciidoctor.org/[DocGist] to preview AsciiDoc files hosted on GitHub, Dropbox, and other services. DocGist also features a real-time collaboration mode. [[X2]] External Resources and Applications ----------------------------------- Here are various useful resources, feel free to open a pull request to add additional ones: - Check the link:INSTALL.html#X2[installation page] for packaged versions of AsciiDoc. - https://asciidoctor.org/[Asciidoctor] provides a modern, compliant, and substantially faster implementation of the AsciiDoc processor written in Ruby. This implementation can also be run on the JVM (with AsciidoctorJ) or using JavaScript (with Asciidoctor.js). The Asciidoctor project now maintains the official definition of the AsciiDoc syntax. - Alex Efros has written an HTML formatted https://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using AsciiDoc. The Asciidoctor project also provides a comprehensive https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax quick reference]. However, the syntax supported by Asciidoctor differs slightly, see https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax[this page] for more details. - The http://remips.sourceforge.net/[ReMIPS] project website has been built using AsciiDoc. - Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets Notes]. - Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki] plugin for AsciiDoc which he uses to render http://mowson.org/karl[his website]. The plugin is available http://www.mowson.org/karl/colophon/[here] and there is some discussion of the ikiwiki integration http://ikiwiki.info/users/KarlMW/discussion/[here]. - Glenn Eychaner has http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked the Asciidoc plugin for ikiwiki] that was created by Karl Mowson. - David Hajage has written an AsciiDoc package for the http://www.r-project.org/[R Project] (R is a free software environment for statistical computing). 'ascii' is available on 'CRAN' (just run `install.packages("ascii")` from R). Briefly, 'ascii' replaces R results in AsciiDoc document with AsciiDoc markup. More information and examples here: https://eusebe.github.io/ascii/. - Jared Henley has written https://jared.henley.id.au/software/awb/[AsciiDoc Website Builder]. 'AsciiDoc Website Builder' (awb) is a Python program that automates the building of of a website written in AsciiDoc. All you need to write is the AsciiDoc source plus a few simple configuration files. - Filippo Negroni has developed a set of tools to facilitate 'literate programming' using AsciiDoc. The set of tools is called http://eweb.sourceforge.net/[eWEB]. - https://vanderwijk.info/[Ivo's blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for AsciiDoc which converts https://en.wikipedia.org/wiki/ASCII_art[ASCII art] into graphics. - https://github.com/gollum/gollum[Gollum] is a git-powered wiki, it supports various formats, including AsciiDoc. - Gregory Romé has written an https://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin] for the https://www.redmine.org/[Redmine] project management application. - Paul Hsu has started a https://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation of the AsciiDoc User Guide]. - Dag Wieers has written http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can export AsciiDoc outputs to OpenOffice export formats. - Ed Keith has written https://sourceforge.net/projects/codeextactor.berlios/[Code Extractor], it extracts code snippets from source code files and inserts them into AsciiDoc documents. - Ryan Tomayko has written an number of https://github.com/rtomayko/adoc-themes[themes for AsciiDoc]. - Lex Trotman has written https://github.com/elextr/codiicsa[codiicsa], a program that converts DocBook to AsciiDoc. - Qingping Hou has written https://houqp.github.io/asciidoc-deckjs/[an AsciiDoc backend for deck.js]. http://imakewebthings.com/deck.js/[deck.js] is a JavaScript library for building modern HTML presentations (slideshows). - The guys from O'Reilly Media have posted an https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to github] that converts DocBook to AsciiDoc. - Lex Trotman has written https://github.com/elextr/flexndex[flexndex], an index generator tool that be used with AsciiDoc. - Michael Haberler has created a https://code.google.com/archive/p/asciidoc-diag-filter/[blockdiag filter for AsciiDoc] which embeds http://blockdiag.com/en/[blockdiag] images in AsciiDoc documents. - Dan Allen has written a https://github.com/mojavelinux/asciidoc-bootstrap-docs-backend[Bootstrap backend] for AsciiDoc. - Steven Boscarine has written https://github.com/StevenBoscarine/JavaAsciidocWrapper[Maven wrapper for AsciiDoc]. - Christian Goltz has written https://github.com/christiangoltz/shaape[Shaape], an Ascii art to image converter for AsciiDoc. - Eduardo Santana has written an https://github.com/edusantana/asciidoc-highlight[Asciidoc Highlight for Notepad++]. - https://www.geany.org/[Geany] 1.23 adds document structure support for AsciiDoc. Please let me know if any of these links need updating. [[X6]] Documents written using AsciiDoc -------------------------------- Here are some documents I know of, if you know of more drop me a line and I'll add them to the list. - The book http://practicalunittesting.com/[Practical Unit Testing] by Tomek Kaczanowski was https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written using Asciidoc]. - The book https://www.oreilly.com/library/view/programming-ios-4/9781449397302/[Programming iOS 4] by Matt Neuburg was written using AsciiDoc. Matt has https://www.apeth.net/matt/iosbooktoolchain.html[written an article] describing how he used AsciiDoc and other tools to write the book. - The book https://www.oreilly.com/library/view/programming-scala/9780596801908/[Programming Scala] by Dean Wampler and Alex Payne (O'Reilly) was http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written using Asciidoc]. - The Neo4j graph database project uses Asciidoc, and the output is published here: https://neo4j.com/docs/. The build process includes live tested source code snippets and is described http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here]. - https://frugalware.org/[Frugalware Linux] uses AsciiDoc for https://frugalware.org/docs[documentation]. - http://www.cherokee-project.com/doc/[Cherokee documentation]. - Henrik Maier produced this professional User manual using AsciiDoc: http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf - Henrik also produced this folded single page brochure format example: http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf + See this http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc discussion group thread] for details. - The https://mirrors.edge.kernel.org/pub/software/scm/git/docs/user-manual.html[Git User's Manual]. - 'Git Magic' + http://www-cs-students.stanford.edu/~blynn/gitmagic/ + https://github.com/blynn/gitmagic - 'CouchDB: The Definitive Guide' + https://docs.couchdb.org/en/stable/ + https://groups.google.com/g/asciidoc/c/pg9ny7r4Yqo - 'Ramaze Manual' + http://book.ramaze.net/ + http://github.com/manveru/ramaze-book - The https://github.com/manveru/KirbyBase[KirbyBase for Ruby] database management system manual. - The http://xpt.sourceforge.net/[*Nix Power Tools project] uses AsciiDoc for documentation. - The http://www.wesnoth.org/[Battle for Wesnoth] project uses AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual] in a number of different languages. - Troy Hanson uses AsciiDoc to generate user guides for the https://troydhanson.github.io/tpl/index.html[tpl] and https://troydhanson.github.io/uthash/index.html[uthash] projects (the HTML versions have a customised contents sidebar). - https://weechat.org/[WeeChat] uses AsciiDoc for https://weechat.org/doc/[project documentation]. - https://github.com/Clansuite/Clansuite[Clansuite] uses AsciiDoc for project documentation. - The https://github.com/shlomif/fc-solve[Freecell Solver program] uses AsciiDoc for its https://fc-solve.shlomifish.org/[distributed documentation]. - Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO protocol decoding] documentation is written using AsciiDoc. - Warren Block has http://www.wonkity.com/~wblock/docs/[posted a number of articles written using AsciiDoc]. - The https://gitlab.com/ita1024/waf/[Waf project's] https://waf.io/book/['Waf Book'] is written using AsciiDoc. - The http://www.diffkit.org/[DiffKit] project's documentation and website have been written using Asciidoc. - The http://www.networkupstools.org[Network UPS Tools] project http://www.networkupstools.org/documentation.html[documentation] is an example of a large documentation project written using AsciiDoc. - http://www.archlinux.org/pacman/[Pacman], the http://www.archlinux.org/[Arch Linux] package manager, has been documented using AsciiDoc. - Suraj Kurapati has written a number of customized manuals for his Open Source projects using AsciiDoc: * http://snk.tuxfamily.org/lib/detest/ * http://snk.tuxfamily.org/lib/ember/ * http://snk.tuxfamily.org/lib/inochi/ * http://snk.tuxfamily.org/lib/rumai/ - The http://cxxtest.com/[CxxTest] project (unit testing for C++ language) has written its http://cxxtest.com/guide.html[User Guide] using AsciiDoc. - The https://docs.fedoraproject.org/[Fedora Docs] website is generated using AsciiDoc. [[X1]] LaTeX Backend ------------- An experimental LaTeX backend was written for AsciiDoc in 2006 by Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn't think this was doable due to AsciiDoc's SGML/XML bias). Due to other commitments, Benjamin was unable to maintain this backend. Here's link:latex-backend.html[Benjamin's original documentation]. Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX backend. In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated `latex.conf` file shipped with AsciiDoc version 8.4.4. The backend still has limitations and remains experimental (see link:latex-bugs.html[Geoff's notes]). It's probably also worth pointing out that LaTeX output can be generated by passing AsciiDoc generated DocBook through `dblatex(1)`. Patches and bug reports ----------------------- Patches and bug reports are are encouraged, but please try to follow these guidelines: - Post bug reports and PRs to the https://github.com/asciidoc/asciidoc-py3[asciidoc-py3] repository. - Post questions about using AsciiDoc or AsciiDoc syntax to the http://groups.google.com/group/asciidoc[asciidoc discussion list], this keeps things transparent and gives everyone a chance to comment. === Bug reports - When reporting problems please illustrate the problem with the smallest possible example that replicates the issue (and please test your example before posting). This technique will also help to eliminate red herrings prior to posting. - Paste the commands that you executed along with any relevant outputs. - Include the version of AsciiDoc and the platform you're running it on. - If you can program please consider writing a patch to fix the problem. === Pull Requests - Keep pull requests small and atomic (one issue per PR) -- no patch bombs. - If possible test your PR against the current master. - If your PR adds or modifies functionality include a short example that illustrates the changes. - Include documentation updates if you're up to it; otherwise insert 'TODO' comments at relevant places in the documentation.