AsciiDoc

AsciiDoc is a DocOps-oriented document encoding format which is a unique in that it embraces the tenets of authoring delight, composability, embedding and blending, and decoupled rendering as part of the core specification itself. In markdown, aligning to said tenets requires not only the use of special extensions, but also the need of funneling document files through specific parsers and renderers.

Authoring Delight

Simple formatting in AsciiDoc is similar to markdown:

= This is a level 1 heading

== This is a level 2 heading

This is text in *bold* and _italics_, and this is an external link to https://docops.guide[DocOps]. Now, some bullet points:

* Bullet point 1
* Bullet point 2
* Bullet point 3

AsciiDoc has not just a syntax reference, but a complete portal which includes user guides, tooling, comparisons with other document encoding formats, and so more.

Composability

The include directive enables composability:

This is a list of security principles:

include::principles.adoc[tag=security]

Embedding and Blending

The embedding and blending of common media types are part of the spec using directives such as video:

Watch this video to get started with this project:

video::getting_started.mp4[width=640,start=60,opts=autoplay]

Decoupled Rendering

Unlike markdown, which in most cases expects HTML as its final render target, AsciiDoc wholeheartedly embraces the tenet of decoupled rendering, and as such, it provides directives that are meaningful in paper-oriented formats, such as bibliographic references:

_The Pragmatic Programmer_ <<pp>> should be required reading for all developers. To learn all about design patterns, 
refer to the book by the "`Gang of Four`" <<gof>>. 

[bibliography] 
== References 

* [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999. * [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.