[ANN] asciidoctor-go: native Go module to parse the asciidoc markup language

Previous Topic Next Topic
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

[ANN] asciidoctor-go: native Go module to parse the asciidoc markup language

Hello fellow AsciiDoc fans,

As a supporter of AsciiDoc markup language and Go, I have been struggling to integrate the power of AsciiDoc into my workflows.  There is one Go module out there that provide parser for AsciiDoc but the latest changes break my program (and their code is hard to hack).  So, I decide to try to write my own parser and call it asciidoctor-go [1].

If you want to use asciidoc markup in your Go program, you can try it by importing asciidoctor-go [2], Open the file or Parse the raw string, and convert it to HTML.  The code is not perfect and clean, there are some missing features and maybe some bugs, but at least it works, usable for me.  The list of supported and unsupported syntax are available in the README file.

The asciidoctor-go module is used by ciigo [3] as backend, think of it like static website generator but use AsciiDoc files as input with more simple APIs.

Several use cases that I use asciidoctor-go and ciigo are,

* https://kilabit.info , my personal website [4]

* https://golang-id.org , The Indonesian Go community website [5]

* Internal documentation in my works environment. We collaborate the documentation using version control and let the CI/CD push the static Go program and deploy it to server where everyone can access internally.

* Public API documentation. We embed the generated HTML and serve them to users.

I am quite happy with current functionalities, so probably there will be no long time update, unless I found some bugs or have more free times.

Happy documenting with Go!



[1] https://sr.ht/~shulhan/asciidoctor-go/
[2] https://pkg.go.dev/git.sr.ht/~shulhan/asciidoctor-go
[3] https://sr.ht/~shulhan/ciigo/
[4] https://git.sr.ht/~shulhan/kilabit.info
[5] https://github.com/golang-id/web/