Write in AsciiDoc, Publish Everywhere

Dan Allen

 
 
 
 
What's happening?
 
Martijn Dashorst
Writing is a #$%@! ordeal.
— Martijn Dashorst, author of Wicket in Action

Pourquoi ?

 

✗

Bad

<class accessibility="public"
    name="HelloWorld">
  <annonymousBlock>
    <method type="static"
        accessibility="public"
        inheritability="final"
        name="main">
      <arguments>
        <variableArguments name="args"
            type="java.lang.String"/>
      </arguments>
      <annonymousBlock>
         <methodCall method="println"
             object="java.lang.System.out">
             <argument value="Hello World!"
                 type="java.lang.String"/>
         </methodCall>
      </annonymousBlock>
    </method>
  </annonymousBlock>
</class>

✓

Good

Docs = Code !

AsciiDoc

syntax

Asciidoctor

parser + tools

read

edit

version

share

convert

 

Syntax

AsciiDoc, c’est bon !

= Getting Started with Java
Author Name <author@example.org>

Here's your first Java application.

.HelloWorld.java
[source,java]
----
public class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello, world!"); <1>
  }
}
----
<1> Prints "Hello, world!" to the console.

Compile this source to a class file using `javac`.
Finally, run the compiled class file using `java`.

AsciiDoc, c’est bon !

asciidoc sample

  • Concise

  • Consistent

  • Semantic

Paragraphs

No special markup is required.
A paragraph is just consecutive lines of text.

To start a paragraph, offset it by a blank line.

Headings

= Document Title

== Section Level 1

=== Section Level 2

==== Section Level 3

===== Section Level 4

====== Section Level 5

= Section Level 0 (book doctype only)

Lists

Unordered
* item 1
** sub-item
* item 2
* item 3
Ordered
. item 1
.. sub-item
. item 2
. item 3

Inline formatting

*bold*

_italic_

`<code>`

[delete]#custom#

bold

italic

<code>

custom

“Fenced” blocks

--

open

----, ```, ....

listing, source, literal

====

example, admonition

****

sidebar

____, ""

quote

////

comment

Source code

:source-highlighter: coderay

[source,java]
----
public class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello, world!"); <1>
  }
}
----
<1> Prints "Hello, world!" to the console.

Notes

NOTE: For your info.

WARNING: I wouldn't do that.

IMPORTANT: Don't forget!

Macros

Inline
<name>:<target>[<attributes>]
Block
<name>::<target>[<attributes>]

Multimedia

Image
image::tux.png[Tux,265,314]
Icon
icon:heart[2x]
Video
video::SCZF6I-Rc4I[youtube,853,480]

Extend!

  • Custom converters (PDF, reveal.js, …​)

  • Custom syntax (issue:<id>[])

  • AST transforms

Extension example

issue:<id>[]
asciidoctor {
  extensions {
    inline_macro (name: 'issue') { parent, id, attrs ->
      issues_uri = parent.getAttr('uri-issues')
      options = [
        type: ':link',
        target: "${issues_uri}/${id}".toString()
      ]
      createInline(parent, 'anchor',
          target, attrs, options).render()
    }
  }
}

Tools

AsciiDoc GitHub

 
 
 
 
 
 
 

Zen writing techniques

#1: Sentence per line

⁃⁃⁃⁃⁃⁃⁃⁃⁃⁃⁃⁃.
⁃⁃⁃⁃⁃⁃.
⁃⁃⁃⁃⁃⁃⁃⁃⁃.

#2: Comments

// ignore this line

////
drop
this
whole
section
////

#3: Couch read

 

#4: D.R.Y. Attributes

:uri-project: http://example.org

Find out more about {uri-project}[project name].

and includes

Shared content
include::{uri-macros}/how_to_complete_this_guide.adoc[]
Testable source code
[source,groovy]
----
include::build.gradle[tag=repositories]
----

#5: Answer a question

What does it do?

Authors Asciidoctor

Scott Chacon
I can do truly amazing things with my AsciiDoc source.
— Scott Chacon, author of Pro Git
 

Illustrations by

Sarah White (@carbonfray)