Announcing Antora

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Announcing Antora

mojavelinux
Administrator
I've been talking for a long time about one day creating a documentation site generator designed specifically for Asciidoctor. Something akin to a Sphinx for AsciiDoc (but better, of course). Well, now is that time.

A few months ago, my company started working on Antora. The idea with Antora is to create a tool exclusively designed for building documentation sites written in AsciiDoc and processed with Asciidoctor (Asciidoctor.js).

Over the last few years, I've had a chance to work with a lot of different site generators (Jekyll, Middleman, Awestruct, Hugo, Metalsmith). While those are great tools, they aren't focused specifically on building documentation sites, and aren't designed first for AsciiDoc. As a result, you end up having to hack together solutions to deal with requirements such product versioning, navigation, page references, and API docs integration. So we decided to create something new that's focused exclusively on documentation and will leverage Asciidoctor to its fullest extent.

In short, Antora aims to be the documentation site generator for the Asciidoctor ecosystem.

Rather than give a half-introduction here, I encourage you to read the blog series Sarah and I have been working on titled "Architecting Antora". The series lays out the key reasons why we decided to build Antora, what we've identified as its requirements, and how we think it should work.

* https://opendevise.com/blog/hello/
* https://opendevise.com/blog/tag/architecting-antora/ (read from oldest to newest)

Antora isn't yet ready for general purpose usage. The implementation is about halfway complete, though it's based on a working prototype we had built earlier in the year. We're hoping to have Antora ready for early adopters to try by the end of the year. If you want to get involved in the architecture discussions, now's certainly the time.

* https://gitlab.com/antora/antora
* https://gitlab.com/antora/antora-ui-default

I'm interested to hear your thoughts about Antora. I hope you're as excited about it as we are!

Cheers,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Ted
Reply | Threaded
Open this post in threaded view
|

Re: Announcing Antora

Ted
Dan, I am really looking forward to using Antora. I believe this is the main thing that documentarians have been missing: a tool for building a documentation website.

I will test it out. It is perfect timing for me because next month our company is meeting to discuss the best way to present company documentation on our intranet.
- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
|

Re: Announcing Antora

Michael_M
In reply to this post by mojavelinux
Hi Dan,

I'm glad to see your Antora initiative. I'm sure this will also promote Asciidoc adoption.
Do you intend to create a separate discussion forum for Antora? Or is this the place?

I read the blog posts with the following use-case in mind: Creating user manuals for products which are built out of shared components. The components own their own documentation. A product is built out of specific versions of the components.

The software assembly requires a dependency management system (Maven, Gradle). It is not quite clear to me, why the document assembly would be different.
See this thread http://discuss.asciidoctor.org/Asciidoc-and-dependency-management-td3751.html, and the neo4j reference in it.

As a use of a dependency management system is familiar to most readers, maybe you could draw the parallel (and point out the differences) in a future blog post?
One difference I am reading, is that in software development, the component is responsible for building (publishing) its re-usable artifacts. Antara is proposing that the generator goes into the components repository and fetches what is needed. I feel that this blurs the demarcation of responsibilities, although is saves the need for an artifactory of some kind. Could you share your reasons for making this choice?

I love the idea of a standard project structure for documentation. I hope this also results in guidelines to address issues like https://github.com/asciidoctor/asciidoctor/issues/894

Thanks,
Michael