Ready, Set, Go!

Give someone a fish and she is hungry again in an hour, teach someone how to fish and she has food for a lifetime.

— (presumably) Anne Isabella Thackeray Ritchie (1885)

Get Started… Quickly

There are several ways to getting started with the Docs-as-Code approach.

We’ll show you how to create and render a simple AsciiDoc document:

[Zero-Dependency Approach]
try it out without installing anything using an online-editor
The Editor Approach
The Build Tool Approach: Integrate Docs-As-Code into your build process.

The Zero-Dependencies Approach

You just want to give AsciiDoc a try without installing anything?

Go to AsciiDocLIVE to try an online editor with preview.

The Editor Approach

If you are willing to install an editor or a plugin for your favorite IDE, you can install one of the following:

AsciiDocFX, a full blown AsciiDoc editor.
Atom editor with AsciiDoc plugin.
Visual Studio Code with AsciiDoc support.
IntelliJ with AsciiDoc support.
Eclipse with AsciiDoc support.

⇒ see also our (German) article about Tools for AsciiDoc

The Build-Tool Approach

"You are standing in an open field west of a white house, with a boarded front door."^[1]

There is a Maven, a Gradle and a Command-Line-Tool nearby.

What will you choose?

Command-Line

Maven

Gradle

> use Command-Line-Tool

You install asciidoctorj via sdkman and write your first simple AsciiDoc document

test.adoc

== Headline

first paragraph

second paragraph

=== second level headline

a link: https://docs-as-co.de[docs-as-co.de]

You then convert it via

asciidoctorj test.adoc

> use Maven

You are likely to be eaten by a grue.

You install Maven via sdkman and write your first simple AsciiDoc document

test.adoc

== Headline

first paragraph

second paragraph

=== second level headline

a link: https://docs-as-co.de[docs-as-co.de]

You then download the build file from github, because it is too big to be just typed in:

maven.pom ^[2]

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>docs-as-co.de</groupId>
    <artifactId>asciidocTest</artifactId>
    <version>0.1</version>

    <build>
        <defaultGoal>generate-resources</defaultGoal>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <backend>html5</backend>
                </configuration>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

…and convert your document via

mvn

> use Gradle

Good choice! A fairy appears and grants you a wish. You wish for a very simple build file and the following line of text appears:

gradle.build

plugins { id "org.asciidoctor.convert" version "1.5.3" }

you write your very first AsciiDoc document and put it in /src/docs/asciidoc/

test.adoc

== Headline

first paragraph

second paragraph

=== second level headline

a link: https://docs-as-co.de[docs-as-co.de]

You install Gradle via sdkman and convert the file with

gradle asciidoc

a nicely styled html file appears in /build/asciidoc/html5/.

1. If you are born after 1980 - this is a famous quote from Zork-1, a text adventure created by Infocom

2. taken from https://raw.githubusercontent.com/asciidoctor/asciidoctor-maven-examples/master/asciidoc-to-html-example/pom.xml

Ready, Set, Go!

Get Started…​ Quickly

The Zero-Dependencies Approach

The Editor Approach

The Build-Tool Approach

Get Started… Quickly