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 |
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
|
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 |
Administrator
|
In reply to this post by Ted
Ted, I'm glad you're looking forward to Antora! I'm certainly eager to hear your feedback on it. All signs point to the timing being right for this, which is exactly why we've boosted the priority on this initiative. We're still on track to making an early release by the end of this month, so you can look forward to having something to test soon. Until then, I certainly encourage you to follow the blog articles as well as the architecture guidebooks. You can find the guidebooks here: We are trying hard to do this project right and not rush it. Cheers, -Dan On Mon, Dec 4, 2017 at 10:55 AM, Ted [via Asciidoctor :: Discussion] <[hidden email]> wrote: 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. Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Administrator
|
In reply to this post by Michael_M
Thanks for your reply, Michael! Do you intend to create a separate discussion forum for Antora? Or is this the place? Great question. We hadn't thought about that yet. For now, I'd say we can discuss here, since this project is very closely connected to the Asciidoctor ecosystem. Once the project matures a bit more, we'll likely look into having a dedicated forum and chat channel. 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. What you're describing is exactly how Antora is designed to work. The current content aggregator happens to be looking for files in repository branches right now. But there's nothing preventing it from taking files from a published jar file instead (or in addition). Where content is stored depends on the workflow of the organization. Some organizations use repository branches instead of published documentation artifacts (as they consider the latter to be too much process). Others publish artifacts, as you have suggested. Neither is right or wrong. It's just what works best for each group. The cornerstone of Antora's pipeline, which will be covered in an upcoming article, is the virtual content catalog. After the content aggregation step, no subsequent component should touch the physical file system (or worry about fetching content). All the content should be in the virtual content catalog. This abstraction allows a myriad of choices as to where content is sourced. It could be a repository branch, a local file system, or the contents of a published archive. As we emphasize in the first article, content is sovereign. Antora 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. Antora is simply proposing that the generator collect content from disparate sources. Which sources, and how those sources are managed, is a choice the organization must make for themselves. Antora should support that choice, no matter what it is. We think using repository branches is the easiest and most elegant way to get started, but Antora can accommodate other arrangements too. 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/ Indeed. Thanks again for the feedback! -Dan On Sun, Dec 10, 2017 at 8:07 AM, Michael_M [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi Dan, Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
In reply to this post by mojavelinux
Hi,
I am really excited to see this documentation-site generator specifically designed for technical documentation. After having used markdown extensively, I have recently switched our whole documentation to asciidoc. Antora may help me a lot in advocating the adoption of asciidoc in my organization with which I've been struggling. The top management still favors Word docs and Sharepoint for documentation and the whole thing is a mess. In the adoption of asciidoc, Antora would be very helpful. Having said that, we are still using SVN as repository and maven etc. My questions are: Does Antora support distributed SVN repositories? If not how can I make it work with SVN repositories and also need to know if there is any plan to support SVN repos in the near future? Any tutorial to set up the whole build process with "maven/gradle" would be very helpful in the quick setup. Thanks. |
Free forum by Nabble | Edit this page |