Discover the Zen of Writing with Asciidoctor

Dan Allen - @mojavelinux

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

Q: Pourquoi ?

A: Structure

  • Why Gradle?

    • Broad Platform Support

      • Java & JVM languages

      • Android’s build system

      • …​

    • Robust Dependency Management

      • Straightforward dependencies

      • …​

    • Powerful Yet Concise Logic

      • …​

Status: It’s complex

  • Yet we fabricate even more barriers.

  • Let’s fix that.

 

✗

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>
ygwyg

✓

Good

AsciiDoc, c’est bon !

= Getting Started with Java
Author Name

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`.
Then, run the compiled class file using `java`.

Docs ≠ Code ?

Docs = Code !

AsciiDoc

syntax

Asciidoctor

parser + tools

edit

read

version

share

convert

Syntax tour

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>`

[role]#custom#

bold

italic

<code>

custom

“Fenced” blocks

--

open

----, ```

listing, source

....

literal

====

example, admonition

****

sidebar

____, ""

quote

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.

Admonitions

NOTE: For your info.

IMPORTANT: Don't forget!

Multimedia

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

Macros

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

Limit the markup you have to type,
not the markup you can type.

Extend it!

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

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

  • AST transforms

Tools

GitHub

+
gists
+
gitbook.io

 
 
 
 

Editing & live preview

 
 

Build automation

build.gradle

buildscript {
  repositories {
    jcenter()
  }

  dependencies {
    classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.2'
  }
}

apply plugin: 'org.asciidoctor.convert'

asciidoctor {
  attributes toc: 'left', icons: 'font'
}

issue:<id>[]

asciidoctor {
  extensions {
    inlinemacro (name: 'issue') { parent, target, attrs ->
      options = [
        type: ':link',
        target: "http://issues/browse/${target}".toString()
      ]
      createInline(parent, 'anchor',
        target, attrs, options).render()
    }
  }
}

Zen techniques

#1: Sentence per line

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

#2: Comment it

// ignore this line

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

#3: Couch read

couch read

#4: “Curl your quotes”

#5: DRY, use attributes…​

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

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

and include fragments

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

Authors ❤ Asciidoctor

I find going back to Markdown akin to trading in utensils and eating with my hands.
— Greg Turnquist, author of Learning Spring Boot
I can do truly amazing things with my AsciiDoc source book
…​this has very serious and interesting implications for the publishing industry as a whole.
— Scott Chacon, author of Pro Git

Illustration cred

Sarah White (@carbonfray)