= Asciidoctor Server

This is an attempt to have asciidoctor run as a server. This is useful for programs that use asciidoctor's cli, like static site generators (that aren't written in ruby). Spawning a ruby process for every file is https://discourse.gohugo.io/t/asciidoc-hugo-performance/10637/14[very wasteful] and squanders https://docs.asciidoctor.org/asciidoctor/latest/features/#impressive-performance-and-strong-security[asciidoctor's speed].

== Installation

TIP: Use https://direnv.net/[direnv] (or many similar tools) to create an environment for your website. Install the client within this environment.

Make sure the client and server version agree. Check the list of git tags. We are at semver 0 and so regularly make breaking changes.

=== Client

cargo install asciidoctor-client

=== Server

Use one of the following options. Feel free to also add specific versions of asciidoctor and its extensions / optional dependencies. The server will load them on request.

• bundle add asciidoctor-server
• Add the following to your Gemfile

[source,ruby]

gem "asciidoctor-server", "$VERSION"

• gem install asciidoctor-server

=== Shim Script

Add the following shim to your path under the name asciidoctor

.asciidoctor [source,shell]

#!/bin/bash

exec asciidoctor-client-go -addr $ADDRESS "$@"

== Usage

WARNING: I haven't yet setup an easy way to stop/start the server or have the client discover the server. Also there's no security so don't use in prod.

CAUTION: Extensions cannot be loaded / unloaded on demand. Once loaded, they are enabled for all subsequent requests. This is not a problem for hugo, which passes the same cli args (ie, extensions) on every invocation. It might be a problem for other setups

Pick an address for the server to bind to, maybe something like $PROJECT_ROOT/.asciidoctor-server.sock

. Start the server with bundle exec, ie bundle exec asciidoctor-server -addr $ADDRESS. You'll probably need to use job control or a separate shell to have this run in the background. . Build your website (that's hugo for me). If your shim was setup correctly, your static site generator will use it. You can test this by adding print statement to the shim script.

== Implementation

The client is written in go to minimize startup overhead, though it could have been any compiled language.

The server is written in ruby.

The two communicate in grpc, with the client mapping its cli arguments to the asciidoctor api. Only a small subset of asciidoctor's arguments are supported. If unsupported args are passed, the client should error.

== Development

You'll need the protobuf compiler, protoc, version 3. This is included in the nix flake for this repo.

=== Client

. Install the go protobuf compiler plugins + [source,shell]

go install google.golang.org/protobuf/cmd/[email protected] $ go install google.golang.org/grpc/cmd/[email protected]

. Update your PATH so that the protoc compiler can find the plugins. This is not necessary if you're using direnv. + [source,shell]

export PATH="$PATH:$(go env GOPATH)/bin"

=== Server

Do the following under server-rb

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

== TODO

• Rust client using tonic?