1. Welcome

adbook repository

1.1. Introduction

adbook is a tool for building book-like webpages. Notes:

  • mdBook vs adbook

    mdBook is a better choice in many ways, but adbook uses AsciiDoc as the source format.

  • asciidoctor vs adbook

    asciidoctor creates single page websites by default, while adbook creates multiple page websites.

1.2. Installation

Rust & adbook

If you have Rust, adbook is available via Crates.io:

$ cargo install adbook # -> $HOME/.cargo/bin

Ruby & Asciidoctor

You need Ruby and some package manager. I recommend RVM because programs installed with it ran faster than that were with rbenv (somehow).

Then let’s get Asciidoctor gems:

$ gem install asciidoctor
$ gem install asciidoctor-diagram

We’re ready!

2. Usage

2.1. New project

Let’s create a new book:

$ adbook init my-book
Initialized a new adbook project at my-book

And see the files in it:

$ tree my-book/ -L 2
my-book/
├── book.ron (1)
├── site (2)
└── src (3)
    ├── article.adoc
    ├── index.adoc
    ├── index.ron (4)
    └── static

3 directories, 4 files
1 book.ron is the root configuration file.
2 site is the default output directory.
3 src is the source file directory.
4 index.ron is very similar to mod.rs.

2.2. Configuration files

Configruation files are in Ron format.

  • book.ron (maps to BookRon)

    It declares books information and build configuration.

  • index.ron (maps to IndexRon)

    It lists the source files in the directory.

For details, check out the source files of this demo.

2.3. Build

Let’s get into the book directory:

$ cd my-book

We can build our book as this:

$ # Build the book (using the cached files in `.adbook-cache/`
$ adbook build

$ # Build the book, clearing all the cache.
$ # Use the `-f` option on e.g. adding new files:
$ adbook build --force

2.4. Serving the site

adbook does not have serve command (yet). Use other commands:

From one shell..

$ python3 -m http.server 8050

From another shell..

$ watchexec -e adoc,ron -w src adbook b

3. References

3.1. Asciidoctor documentations

3.2. Alternatives to adbook

  • Antora

    A modular documentation site generator. Designed for users of Asciidoctor.

  • asciidoctor-multipage

    A multipage HTML converter for Asciidoctor

  • asciidoctor-chunker

    The utility to create chunked HTML files from the single HTML generated by Asciidoctor.

  • Maybe other SSGs such as MKDocs

  • Maybe org-mode

3.3. More of AsciiDoc