Re: [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
|

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

mojavelinux
Administrator
I'm very happy to see a growing commitment to create AsciiDoc parsers in other languages. I'll write here what I shared with the Rust implementation.

I support the initiative to bring support for the AsciiDoc format to other languages. That's a key reason why I (along with the Asciidoctor community) have embarked on the journey to create a specification for the language. In doing so, we hope to encourage new, compliant implementations. We invite those interested in creating a Go implementation to join us on that journey. See the following resources for more information:

* https://www.eclipse.org/org/workinggroups/asciidoc-charter.php

Please note that there's no such thing as the Asciidoctor format. Asciidoctor is a processor implementation of the AsciiDoc format. (see https://docs.asciidoctor.org/asciidoctor/latest/#relationship-to-asciidoc) Also note that AsciiDoc is a registered trademark of the Eclipse Foundation, stewarded by the AsciiDoc Working Group. It will be necessary to self-certify using the forthcoming TCK for an implementation to claim to be compliant with AsciiDoc (and, in turn, to use the AsciiDoc name in the description). If you participate now, you can have influence in how that TCK is defined.

One of the primary goals of the spec is to allow the AsciiDoc format to stand alone, independent of Asciidoctor or any other implementation. We want it to be both consistent and ubiquitous.

I wholeheartedly welcome those involved in this endeavor to participate in the working group (https://accounts.eclipse.org/mailing-list/asciidoc-wg) or the language project (https://accounts.eclipse.org/mailing-list/asciidoc-lang-dev). But please understand this is merely an invitation, not a requirement or mandate. This is a community effort and just like with all community efforts, it is at will.

Best Regards and Best of Luck,

-Dan

On Wed, Jan 20, 2021 at 12:16 PM shulhan [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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!


Regards,

Shulhan

--
[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/


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/ANN-asciidoctor-go-native-Go-module-to-parse-the-asciidoc-markup-language-tp8449.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux