AsciiDoc
AsciiDoc Home Page
Read the CHANGELOG for release highlights and a full list of all additions, changes and bug fixes. Changes are documented in the updated User Guide. See the Installation page for downloads and and installation instructions.
Stuart Rackham
Introduction
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.
AsciiDoc 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 is free software and is licenced under the terms of the GNU General Public License version 2 (GPLv2).
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 theasciidoc(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 AsciiDoc User Guide was generated by AsciiDoc from this AsciiDoc file.
Here’s the 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 chunked version.
AsciiDoc generated this stand-alone HTML file containing embedded CSS, JavaScript and images from this AsciiDoc article template with this command:
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
The same AsciiDoc article template generated 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 AsciiDoc article template produced this HTML file and this PDF file via DocBook markup generated by AsciiDoc.
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 AsciiDoc book produced this HTML file using the DocBook XSL Stylesheets.
The PDF formatted AsciiDoc User Guide was generated from
asciidoc(1)
DocBook output.The EPUB formatted AsciiDoc User Guide was generated using a2x.
This EPUB formatted book skeleton was generated using a2x.
This multi-part AsciiDoc book produced this HTML file using the DocBook XSL Stylesheets.
Example UNIX Man Pages
HTML formatted AsciiDoc man pages with stylesheets and without stylesheets were generated by AsciiDoc from this file.
This roff formatted man page was generated from asciidoc(1)
DocBook output using xsltproc(1)
and DocBook XSL Stylesheets.
Example Slideshows
The 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 slidy backend documentation slideshow and here is it’s AsciiDoc source.
An example slidy slideshow and the AsciiDoc source.
Example Web Site
The AsciiDoc website is included in the AsciiDoc distribution (in ./examples/website/
) as an example website built using AsciiDoc. See ./examples/website/README-website.txt
.
More examples
See below: Documents written using AsciiDoc.
Example Tables.
eBook Publication
The two most popular open eBook formats are EPUB and PDF. The AsciiDoc a2x toolchain wrapper makes it easy to publish EPUB and PDF eBooks with AsciiDoc. See also example books and AsciiDoc EPUB Notes).
Blogpost weblog client
Source code highlighter
AsciiDoc includes a source code highlighter filter that uses GNU source-highlight to highlight HTML outputs. You also have the option of using the Pygments highlighter.
Mathematical Formulae
You can include mathematical formulae in AsciiDoc XHTML documents using ASCIIMathML or LaTeXMathML notation.
The AsciiDoc LaTeX filter translates LaTeX source to a PNG image that is automatically inserted into the AsciiDoc output documents.
AsciiDoc also has latexmath macros for DocBook outputs — they are documented in 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 the AsciiDoc distribution (see the Vim Syntax Highlighterappendix in the AsciiDoc User Guide for details).
Syntax highlighter screenshotDag Wieers has implemented an alternative Vim syntax file for AsciiDoc which can be found herehttp://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
David Avsajanishvili has written a source highlighter for AsciiDoc files for GtkSourceView (used by 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 AsciiDoc page at the Emacs Wiki.
Christian Zuckschwerdt has written a TextMate bundle for AsciiDoc.
Try AsciiDoc on the Web
Andrew Koster has written a Web based application to interactively convert and display AsciiDoc source:http://andrewk.webfactional.com/asciidoc.php
External Resources and Applications
Here are resources that I know of, if you know of more drop me a line and I’ll add them to the list.
Check the installation page for packaged versions of AsciiDoc.
Alex Efros has written an HTML formatted AsciiDoc Cheatsheet using Asciidoc.
Thomas Berker has written an AsciiDoc Cheatsheet in Open Document and PDF formats.
The WikiMatrix website has an excellent web page that compares the various Wiki markup syntaxes. An interesting attempt at Wiki markup standardization is CREOLE.
Franck Pommereau has written Asciidoctest, a program that doctests snippets of Python code within your Asciidoc documents.
The ReMIPS project website has been built using AsciiDoc.
Here are some DocBook XSL Stylesheets Notes.
Karl Mowatt-Wilson has developed an ikiwiki plugin for AsciiDoc which he uses to render his website. The plugin is availablehere and there is some discussion of the ikiwiki integration here.
Glenn Eychaner has reworked the Asciidoc plugin for ikiwiki that was created by Karl Mowson, the source can be downloaded from http://dl.dropbox.com/u/11256359/asciidoc.pm
David Hajage has written an AsciiDoc package for the R Project (R is a free software environment for statistical computing).ascii is available on CRAN (just run
install.package("ascii")
from R). Briefly, ascii replaces R results in AsciiDoc document with AsciiDoc markup. More information and examples here: http://eusebe.github.com/ascii/.Pascal Rapaz has written a Python script to automate AsciiDoc website generation. You can find it athttp://www.rapazp.ch/opensource/tools/asciidoc.html.
Jared Henley has written 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.
Brad Adkins has written AsciiDocGen, a web site generation and deployment tool that allows you write your web site content in AsciiDoc. The AsciiDocGen web site is managed using AsciiDocGen.
Filippo Negroni has developed a set of tools to facilitate literate programming using AsciiDoc. The set of tools is called eWEB.
Ivo’s blog describes a ditaa filter for AsciiDoc which converts ASCII art into graphics.
Gollum is a git-powered wiki, it supports various formats, including AsciiDoc.
Gregory Romé has written an AsciiDoc plugin for the Redmine project management application.
Paul Hsu has started a Chinese translation of the AsciiDoc User Guide.
Dag Wieers has written UNOCONV. UNOCONV can export AsciiDoc outputs to OpenOffice export formats.
Ed Keith has written Code Extractor, it extracts code snippets from source code files and inserts them into AsciiDoc documents.
The JMI website hosts a number of extras for AsciiDoc and Slidy written by Jean-Michel Inglebert.
Ryan Tomayko has written an number of themes for AsciiDoc along with a script for combining the CSS files into single CSS theme files for AsciiDoc embedded CSS documents.
Ilya Portnov has written a document building system for AsciiDoc, here is short article in Russian describing it.
Lex Trotman has written codiicsa, a program that converts DocBook to AsciiDoc.
Qingping Hou has written an AsciiDoc backend for deck.js. deck.js is a JavaScript library for building modern HTML presentations (slideshows).
The guys from O’Reilly Media have posted an XSL Stylesheet to github that converts DocBook to AsciiDoc.
Lex Trotman has written flexndex, an index generator tool that be used with AsciiDoc.
Michael Haberler has created a blockdiag filter for Asciidoc which embeds blockdiag images in AsciiDoc documents.
Dan Allen has written a Bootstrap backend for AsciiDoc.
Steven Boscarine has written Maven wrapper for AsciiDoc.
Christian Goltz has written Shaape, an Ascii art to image converter for AsciiDoc.
Eduardo Santana has written an Asciidoc Highlight for Notepad++.
Geany 1.23 adds document structure support for AsciiDoc.
Please let me know if any of these links need updating.
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 Practical Unit Testing by Tomek Kaczanowski was written using Asciidoc.
The book Programming iOS 4 by Matt Neuburg was written using AsciiDoc. Matt has written an article describing how he used AsciiDoc and other tools to write the book.
The book Programming Scala by Dean Wampler and Alex Payne (O’Reilly) was written using Asciidoc.
The fishR website has a number of book examples written using AsciiDoc.
The Neo4j graph database project uses Asciidoc, and the output is published here: http://docs.neo4j.org/. The build process includes live tested source code snippets and is described here.
Frugalware Linux uses AsciiDoc for 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 AsciiDoc discussion group thread for details.
The Git User’s Manual.
Git Magic http://www-cs-students.stanford.edu/~blynn/gitmagic/ http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c
CouchDB: The Definitive Guide http://books.couchdb.org/relax/ http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4
Ramaze Manual http://book.ramaze.net/ http://github.com/manveru/ramaze-book/tree/master
Some documentation about git by Nico Schottelius (in German) http://nico.schotteli.us/papers/linux/git-firmen/.
The KirbyBase for Ruby database management system manual.
The *Nix Power Tools project uses AsciiDoc for documentation.
The Battle for Wesnoth project uses AsciiDoc for its Manual in a number of different languages.
Troy Hanson uses AsciiDoc to generate user guides for the tpl and uthash projects (the HTML versions have a customised contents sidebar).
Leonid Volnitsky’s site is generated using AsciiDoc and includes Leonid’s matplotlib filter.
WeeChat uses AsciiDoc for project documentation.
Clansuite uses AsciiDoc for project documentation.
The Freecell Solver program uses AsciiDoc for its distributed documentation.
Eric Raymond’s AIVDM/AIVDO protocol decoding documentation is written using AsciiDoc.
Dwight Schauer has written an LXC HOWTO in AsciiDoc.
The Free Telephony Project website is generated using AsciiDoc.
Warren Block has posted a number of articles written using AsciiDoc.
The Waf project’s Waf Book is written using AsciiDoc, there is an HTML and a PDF version.
The DiffKit project’s documentation and website have been written using Asciidoc.
The Network UPS Tools project documentation is an example of a large documentation project written using AsciiDoc.
Pacman, the 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:
The CxxTest project (unit testing for C++ language) has written its User Guide using AsciiDoc.
Please let me know if any of these links need updating.
DocBook 5.0 Backend
Shlomi Fish has begun work on a DocBook 5.0 docbook50.conf
backend configuration file, you can find it here. See also:http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9
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). Owning to to other commitments, Benjamin was unable to maintain this backend. Here’s 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 (seeGeoff’s notes).
It’s probably also worth pointing out that LaTeX output can be generated by passing AsciiDoc generated DocBook throughdblatex(1)
.
Patches and bug reports
Patches and bug reports are are encouraged, but please try to follow these guidelines:
Post bug reports and patches to the asciidoc discussion list, this keeps things transparent and gives everyone a chance to comment.
The email subject line should be a specific and concise topic summary. Commonly accepted subject line prefixes such as [ANN],[PATCH] and [SOLVED] are good.
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.
Patches
Keep patches small and atomic (one issue per patch) — no patch bombs.
If possible test your patch against the current trunk.
If your patch adds or modifies functionality include a short example that illustrates the changes.
Send patches in
diff -u
format, inline inside the mail message is usually best; if it is a very long patch then send it as an attachment.Include documentation updates if you’re up to it; otherwise insert TODO comments at relevant places in the documentation.
AsciiDoc的更多相关文章
- AsciiDoc Markup Syntax Summary
AsciiDoc Markup Syntax Summary ============================== A summary of the most commonly used ma ...
- Ubuntu 安装asciidoc时默认推荐了巨大的安装包
$ sudo apt-get install asciidocReading package lists... DoneBuilding dependency tree Reading s ...
- gradle asciidoc 使用
备注: 次文档参考github 例子 1.环境准备 node npm (yarn) java KindleGen 备注: 具体的安装可以参考网上相关文档,KindleGen 下载地址:htt ...
- AsciiDoc Text based document generation
AsciiDoc Text based document generation AsciiDoc Home Page http://asciidoc.org/ AsciiDoc is a t ...
- AsciiDoc 的相关整理
Asciidoc Book Editor based on JavaFX 8 Asciidoc FX is a book / document editor to build PDF, Epub, ...
- 轻量级标记语言Asciidoc、Markdown
Asciidoc简介 https://blog.csdn.net/u011411849/article/details/79031718 Asciidoc 比Markdown更简洁强大的文档工具 ht ...
- ABP集合贴
thead>tr>th,.table>tbody>tr>th,.table>tfoot>tr>th,.table>thead>tr>t ...
- Android应用性能优化(转)
人类大脑与眼睛对一个画面的连贯性感知其实是有一个界限的,譬如我们看电影会觉得画面很自然连贯(帧率为24fps),用手机当然也需要感知屏幕操作的连贯性(尤其是动画过度),所以Android索性就把达到这 ...
- 【OpenWRT】【RT5350】【一】OpenWrt开发环境搭建
[宿主机构建] 本人电脑配置如下: CPU: intel 酷睿 i3 3.3G 双核 内存: 金士顿 8G 硬盘:希捷 1TB 7200rpm 操作系统:win7 旗舰版 64位 OpenWrt是在 ...
随机推荐
- 李洪强iOS开发之OC面向对象—多态
OC面向对象—多态 一.基本概念 多态在代码中的体现,即为多种形态,必须要有继承,没有继承就没有多态. 在使用多态是,会进行动态检测,以调用真实的对象方法. 多态在代码中的体现即父类指针指向子类对象. ...
- 【PSR规范专题(4)】PSR-3 日志接口规范
本文转自:https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md 本文制定了日志类库的通用接口规范. ...
- Haproxy安装及配置
1.安装 # wget http://haproxy.1wt.eu/download/1.3/src/haproxy-1.3.20.tar.gz # tar zcvf haproxy-1.3.20.t ...
- linux下修改tomcat的默认目录
1.修改tomcat的默认目录.它的默认目录是webapps/ROOT,对应的conf目录下的server.xml里的内容是: 1.修改tomcat的默认目录.它的默认目录是webapps/ROOT, ...
- Java-斐波那契数
1.目标:使用非递归求斐波那契,0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ... 2.思路:观察规律得:从第3个数起,把和从为下一个数的加数,把加数作为下一个数的被加数,即三个 ...
- 《jQuery风暴》第2章 必须知道的JavaScript知识
第2章 必须知道的JavaScript知识 JavaScript是jQuery应用的基础,掌握JavaScript这门语言是使用jQuery的基础条件.本章不会全面细致的讲解JavaScript的全部 ...
- android 矩阵处理类:Matrix
在Android中,对图片的处理需要使用到Matrix类,Matrix是一个3 x 3的矩阵,他对图片的处理分为四个基本类型: 1.Translate 2.Scale 3.Rotate 4.Skew ...
- SendTextMessage如何打开记事本并显示指定内容
procedure TForm1.Button1Click(Sender: TObject); var hEdit: HWND; str: string; begin str := '准备要添加到记事 ...
- java Process的waitFor()
java Process的waitFor() 在编写Java程序时,有时候我们需要调用其他的诸如exe,shell这样的程序或脚本.在Java中提供了两种方法来启动其他程序: (1) 使用Runtim ...
- 页面关键词Meta Keywords和描述Description的优化作用
前几日有两三个童鞋们问我为什么文章目录页面没有设置关键词,我原先还以为什么关键词,后来才明白是问我为什么不添加Meta Keywords.关于这个问题我直接回应他们说目录页面Meta Keywords ...