AsciiDoc File Format (.adoc)

An ADOC file holds AsciiDoc, a plain-text markup Stuart Rackham designed in 2002 with structural features like admonitions, includes and cross-references built into the syntax rather than bolted on afterward.

.adocDocuments

AsciiDoc at a glance#

Full name	AsciiDoc
File extension	.adoc
Category	Documents
Developer	Stuart Rackham
First released	2002
MIME types	text/asciidoc
Other extensions	.asciidoc
Compression	Uncompressed
Specification	AsciiDoc Language Specification
FileFlip support	FileFlip reads and writes this format

What a .adoc file can hold#

These are the things a AsciiDoc file either supports or does not, and they are what decides whether a conversion keeps everything or quietly drops something.

Selectable text	Yes
Human readable	Yes
Comments	Yes

Strengths and limitations of AsciiDoc#

What AsciiDoc does well

Built-in admonition blocks (NOTE, TIP, WARNING) need no extra styling markup of their own
The include directive pulls in other files at build time, so one book can be split across chapters
Cross-references and section numbering work natively, without a plugin

Where AsciiDoc falls short

Far fewer tools render it natively than render Markdown, so most workflows go through the Asciidoctor processor first
There's more syntax to learn than Markdown before someone can write a full document
The original asciidoc.py implementation is retired, and the formal AsciiDoc Language specification meant to unify Asciidoctor with it is still in progress at the Eclipse Foundation

Choose AsciiDoc for technical documentation or a book that needs admonitions, includes and cross-references without hand-writing DocBook.

Convert AsciiDoc to Markdown when a document is moving to a tool or audience that only understands Markdown, accepting that admonitions, includes and cross-references have no Markdown equivalent.

How to open a .adoc file#

A .adoc file opens in the programs below, grouped by the platform you are on. If you would rather not install anything, FileFlip converts AsciiDoc into a format your machine already opens, and it does it in the browser tab rather than on a server.

Platform	Programs that open it
Windows	VS Code (AsciiDoc extension), IntelliJ IDEA (AsciiDoc plugin)
macOS	VS Code (AsciiDoc extension), IntelliJ IDEA (AsciiDoc plugin)
Linux	VS Code (AsciiDoc extension), vim, Asciidoctor (command line)
Web	GitHub, FileFlip

AsciiDoc questions people ask#

What's the difference between AsciiDoc and Markdown?

AsciiDoc is a plain-text markup built for technical documentation, with admonitions, file includes and cross-references defined in the syntax itself, where Markdown has none of these without an extension or raw HTML. AsciiDoc is correspondingly more to learn, and far fewer tools render it without going through a processor like Asciidoctor first.

What program opens an ADOC file?

An ADOC file is plain text, so any text editor opens it, but seeing it rendered means running it through Asciidoctor or an editor with an AsciiDoc preview plugin, such as VS Code's AsciiDoc extension or IntelliJ IDEA's AsciiDoc plugin. GitHub also renders .adoc files directly in a repository.

Does AsciiDoc convert cleanly to Markdown?

Basic AsciiDoc, headings, paragraphs, lists, emphasis, converts to Markdown with little loss. Admonition blocks, include directives and cross-references have no Markdown equivalent, so a conversion either drops them or flattens them into plain text and a broken link.

Converting AsciiDoc files#

Every conversion runs inside your browser. The file is read from your disk, the work happens on your own machine, and nothing is uploaded. How FileFlip works names the engine behind each family and how to verify that for yourself.