asciidoc-hs is a parser for the lightweight markup language AsciiDoc that can be used as a Pandoc front-end. It draws on commonmark-hs and is written in pure Haskell.

• Mission
• Features
• Install
  • Using Cabal
  • Using Stack
• Use
• Contribute
  • Implement a new AsciiDoc feature
• Acknowledgements

The main goal of this project is to become a reasonably complete implementation of the AsciiDoc language and to allow Pandoc to read AsciiDoc documents.

We want to read AsciiDoc as it’s used today (mainly in its Asciidoctor variant), and also support the AsciiDoc Standard when it arrives. We’re following the standardization process closely and we’ll try to contribute to it if we see the opportunity.

There have been former attempts at a Pandoc Reader for AsciiDoc, but they have been abandoned. If you want to feed Pandoc with an AsciiDoc source, your best option at the moment is probably to first convert to Docbook using Asciidoctor.

Secondary goals of the project are (but don’t expect any roadmap or timeline at the moment):

• Be used as infrastructure for building advanced editor and IDE features (e.g., linters and live previewers). This means to be able to track precise source mapping information, among others.

• Be scriptable in a similar way to Pandoc, but using and AST/DOM that is specific to AsciiDoc and fully supports its semantic richness.

• Enable source-to-source transformations, including exact-print for those parts not explicitly modified by the scripts (a.k.a. lossless transformation).

• End up being distributed together with Pandoc, as a regular Pandoc Reader.

The supported features can be found in our compatibility matrix, currently based on Asciidoctor’s feature list.

You’ll need to build from source for the time being. We expect to upload the package to Hackage soon.

If you don’t have Haskell installed in your system, try install GHC and Cabal with ghcup, and follow instructions for Cabal below.

asciidoc-hs has been tested with GHC 8.8 and 8.10, and Cabal 3.4.

Using Cabal

$ git clone https://github.com/gmarpons/asciidoc-hs.git
$ cd asciidoc-hs

$ cabal build

$ cp "$(cabal exec --verbose=0 --offline sh -- -c 'command -v asciidoc-hs')" ~/.local/bin/asciidoc-hs

Using Stack

$ git clone https://github.com/gmarpons/asciidoc-hs.git
$ cd asciidoc-hs

$ stack build

$ cp "$(stack path --local-install-root)/bin/asciidoc-hs" ~/.local/bin/asciidoc-hs

In the examples directory of this repository you can find some example AsciiDoc files and its various conversions.

The commands used to get the converted files are:

• Convert to HTML using Asciidoctor:

  $ asciidoctor -a "sectids!" -a "showtitle" -a "linkcss" -a "stylesheet=https://cdn.jsdelivr.net/gh/asciidoctor/[email protected]/data/stylesheets/asciidoctor-default.css" -a "webfonts!" ⟨FILENAME⟩.adoc -o - > ⟨FILENAME⟩-asciidoctor.html

• Convert to HTML using asciidoc-hs + Pandoc:

  $ cat ⟨FILENAME⟩.adoc | asciidoc-hs | pandoc -f json -t html5 --standalone --css="https://cdn.jsdelivr.net/gh/asciidoctor/[email protected]/data/stylesheets/asciidoctor-default.css" --css="./asciidoc-hs.css" > ⟨FILENAME⟩-pandoc.html

• Convert to ODT using asciidoc-hs + Pandoc:

  $ cat ⟨FILENAME⟩.adoc | asciidoc-hs | pandoc -f json -t odt > ⟨FILENAME⟩-pandoc.odt

• Convert to Markdown using asciidoc-hs + Pandoc:

  $ cat ⟨FILENAME⟩.adoc | asciidoc-hs | pandoc -f json -t markdown_strict > ⟨FILENAME⟩-pandoc.md

File asciidoctor-article-template.adoc presents a variety of AsciiDoc features. Those not yet supported by asciidoc-hs are commented out.

Contributions are Welcome!

For any of:

• reporting a bug,

• filling a feature request,

• opening a PR,

we’ll try to stick to the workflow and guidelines set in Kowainik contributing guidelines, with the difference that we use ormolu instead of stylish-haskell.

Implement a new AsciiDoc feature

This work has been supported by a Tweag Open Source Fellowship.