Asciidoc-hs

Warning

This project is in its early stages. Don’t expect to be able to use it in anything relevant, yet.

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.

Table of Contents

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

Mission

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.

Features

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

Install

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

First, clone the repository:

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

Then, build using cabal:

$ cabal build

You can optionally copy the resulting executable under a location of your choice (that should be under the PATH environment variable):

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

Using Stack

First, clone the repository:

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

Then, build using stack:

$ stack build

You can optionally copy the resulting executable under a location of your choice (that should be under the PATH environment variable):

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

Use

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.

Contribute

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

AsciiDoc is an extensive language. There are plenty of features still to be implemented, with varying degrees of difficulty.

The recommended workflow is the following:

1. Check the compatibility matrix to look for unsupported features.

2. Fill an issue with the proposed feature if you cannot find it in the issue tracker, yet.

3. Go inspect files Inlines.hs or Blocks.hs and see:

   • If the current AST data types (mainly Inline and Block) support the intended feature, or need to be modified.

   • Look for a similar and already implemented feature, and see how the corresponding parser functions are written.

4. Discuss a possible implementation in the issue tracker.

5. Modify the aforementioned files.

6. Add new test cases for inlines or blocks.

7. Add the necessary new cases to functions convertInline or convertBlock in Pandoc.hs.

You don’t need to wait to complete the steps above before opening a PR. In fact, it’s better if your code can be reviewed from the beginning.

Acknowledgements

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