Getting Started

Install

If you have Go installed (version 1.26 or later), you can install directly:

go install github.com/lukewilliamboswell/libasciidoc/cmd/ascii2doc@latest
go install github.com/lukewilliamboswell/libasciidoc/cmd/ascii2html@latest

This installs two commands:

  • ascii2html — converts AsciiDoc to HTML5 (default) or XHTML5

  • ascii2doc — converts AsciiDoc to DOCX (default), with HTML output also available

Build from Source

Clone the repository and build:

git clone https://github.com/lukewilliamboswell/libasciidoc.git
cd libasciidoc
go build -o ascii2html ./cmd/ascii2html
go build -o ascii2doc ./cmd/ascii2doc

Verify Installation

After installing, verify the tools are working:

ascii2html version
ascii2doc version

Quick Start

Create a file called hello.adoc with some content:

= My First Document

This is a paragraph written in https://asciidoc.org[AsciiDoc].

== A Section

* Item one
* Item two
* Item three

Convert to HTML

ascii2html hello.adoc

This creates hello.html in the current directory. Open it in your browser to see the result.

To write the output to a specific file:

ascii2html -o output.html hello.adoc

Convert to DOCX

ascii2doc hello.adoc

This creates hello.docx which you can open in Microsoft Word, LibreOffice, or Google Docs.

Common Options

Both commands share these options:

-o <file>

Write output to a specific file instead of the default.

-s or --no-header-footer

Render only the document body without the HTML header and footer. Useful when embedding the output in another page.

-b <backend>

Choose the output format: html5 (default for ascii2html), xhtml5, or docx (default for ascii2doc).

-a key=value

Set a document attribute. Can be repeated.

--css <file>

Link a CSS stylesheet (HTML output only). Can be repeated.

Next Steps

Built with ascii2html