Development Setup

Prerequisites

  • Go 1.26 or later

  • Git

Clone and Build

git clone https://github.com/lukewilliamboswell/libasciidoc.git
cd libasciidoc
go build ./…​

Build the CLI tools:

go build -o ascii2html ./cmd/ascii2html
go build -o ascii2doc ./cmd/ascii2doc

Run Tests

go test ./…​

Local CI

Before committing, run the full set of checks that mirror CI:

./minici.sh

This runs go mod tidy, build, tests with the race detector, golangci-lint, go generate freshness, govulncheck, example validation, and then builds and serves the static site locally at http://localhost:8000.

Run the Site Locally

To just preview documentation changes without running the full check suite:

go build -o ascii2html ./cmd/ascii2html
./ascii2html --static-site --css style.css -o _site www/

Then serve the directory locally:

python3 -m http.server 8000 --directory _site

Open http://localhost:8000 in your browser to preview the site.

Project Structure

See the Architecture Overview for a detailed explanation of how the packages fit together.

Modifying the Grammar

The parser is generated from a PEG grammar using pigeon. If you need to modify the grammar:

go generate ./…​

Then build as normal:

go build ./…​

Benchmarking

This project uses Ginkgo for testing but the standard Go toolchain for benchmarking. Skip normal tests when benchmarking with -run=XXX:

go test -run=XXX -bench=. -benchmem -count=10 ./…​ | tee tmp/bench-before.txt

After making changes, run the same benchmarks and compare with benchstat:

go test -run=XXX -bench=. -benchmem -count=10 ./…​ | tee tmp/bench-after.txt
benchstat tmp/bench-before.txt tmp/bench-after.txt

Benchmark output doesn’t need to be committed, but including relevant benchstat results in commit messages is helpful.

Built with ascii2html