{"id":15933,"date":"2018-08-14T10:09:05","date_gmt":"2018-08-14T08:09:05","guid":{"rendered":"https:\/\/owncloud.com\/?p=15933"},"modified":"2021-02-16T18:06:49","modified_gmt":"2021-02-16T18:06:49","slug":"owncloud-docs-migrating-antora-pt-1-2","status":"publish","type":"post","link":"https:\/\/owncloud.com\/de\/blogs\/owncloud-docs-migrating-antora-pt-1-2\/","title":{"rendered":"The ownCloud Docs are Migrating to Antora! (Pt. 1\/2)"},"content":{"rendered":"<p>After quite some time using the veteran <a href=\"http:\/\/www.sphinx-doc.org\/en\/master\/\" target=\"_blank\" rel=\"noopener noreferrer\">Sphinx-Doc platform<\/a> to manage <a href=\"https:\/\/doc.owncloud.org\/\" target=\"_blank\" rel=\"noopener noreferrer\">ownCloud\u2019s documentation<\/a>, we\u2019ve decided to migrate to <a href=\"https:\/\/antora.org\/\" target=\"_blank\" rel=\"noopener noreferrer\">Antora<\/a>.<br \/>\nWe\u2019re excited about the move and think you will be too; here\u2019s why.<\/p>\n<p>Developers and other community members have told us that while Sphinx-Doc is very capable and feature-rich it was frustrating for them to contribute to the documentation. Whether they were trying to document an app or other code contribution, or trying to correct a mistake or add missing information to the documentation, they\u2019ve been reluctant to contribute.<\/p>\n<p>They told us that this is for two reasons:<\/p>\n<ol>\n<li>Sphinx-Doc\u2019s file format (reStructuredText) along with Sphinx-Doc\u2019s extensions is too cumbersome.<\/li>\n<li>Sphinx-Doc is challenging to set up.<\/li>\n<\/ol>\n<p>As a result, they feel it\u2019s too much hassle even to make a small change. That\u2019s something we\u2019re determined to change \u2014 especially as ownCloud is an open-source platform. We want it to be <strong>as easy as possible for anyone to contribute<\/strong> to the documentation.<\/p>\n<p>So, after lots of research and experimentation, we decided to find an alternative documentation platform, one that has the following characteristics:<\/p>\n<ul>\n<li>As quick and painless as possible to contribute \u2014 no matter the size of the contribution.<\/li>\n<li>Uses a file format that\u2019s as similar to Markdown as possible.<\/li>\n<li>Makes it trivial to navigate through the documentation \u2014 regardless of version.<\/li>\n<li>Makes it easier to release documentation changes \u2014 no matter how big or small.<\/li>\n<\/ul>\n<p>After considering a number of alternatives, we found one that meets all these criteria \u2014 <a href=\"https:\/\/antora.org\/\" target=\"_blank\" rel=\"noopener noreferrer\">it\u2019s called Antora<\/a>. Antora is self-described as:<\/p>\n<p>&nbsp;<\/p>\n<p style=\"text-align: center;\"><span style=\"font-size: 18pt;\"><strong>The multi-repository documentation site generator for tech writers who \u2764\ufe0f writing in AsciiDoc.<\/strong><\/span><\/p>\n<p>&nbsp;<\/p>\n<p>While relatively new (<em>at the time of writing at release 1.0.2<\/em>), it\u2019s already an extremely capable tool; one I expect will make developers\u2019 lives much more comfortable and lead to a significant increase in documentation contributions.<\/p>\n<p>This is because Antora is:<\/p>\n<ul>\n<li>Based around <a href=\"https:\/\/asciidoctor.org\/docs\/asciidoc-syntax-quick-reference\/\" target=\"_blank\" rel=\"noopener noreferrer\">the AsciiDoc format<\/a>, a format far more akin to Markdown. Its syntax is <em>readable<\/em>, <em>concise<\/em>, <em>comprehensive<\/em>, +extensible+, and, above all, <em>easy to learn<\/em>.<\/li>\n<li>Provides a logical and structured way of organizing technical documentation.<\/li>\n<li>Enforces a clear and logical separation of text content and supporting assets (such as <em>images<\/em>, <em>videos<\/em>, and <em>code<\/em>).<\/li>\n<li>Uses a small set of tools, ones that are commonly available in developer toolsets, such as <em>Node<\/em> and <em>Git<\/em>.<\/li>\n<li>Provides very flexible project navigation.<\/li>\n<li>Natively links to different documentation versions within the UI;<\/li>\n<li><em>Plus so much more!<\/em><\/li>\n<\/ul>\n<h2>What\u2019s Been Achieved So Far?<\/h2>\n<p>The migration to Antora\u2019s not finished yet, but we\u2019re excited to share the progress we\u2019ve made with you. In the screenshot below, you can see what the new implementation looks like.<\/p>\n<div id=\"attachment_15941\" style=\"width: 1382px\" class=\"wp-caption aligncenter\"><img loading=\"lazy\" decoding=\"async\" aria-describedby=\"caption-attachment-15941\" class=\"wp-image-15941 size-full\" src=\"https:\/\/owncloud.com\/wp-content\/uploads\/2018\/08\/ownCloud-documentation-migration-to-antora-ui-anotated.png\" alt=\"ownCloud documentation migration to Antora - UI anotated\" width=\"1372\" height=\"802\" \/><p id=\"caption-attachment-15941\" class=\"wp-caption-text\">The new Antora based documentation UI of ownCloud<\/p><\/div>\n<p>You can see it has:<\/p>\n<ul>\n<li>The standard main navigation at the top (1).<\/li>\n<li>The secondary navigation down the left-hand side (2).<\/li>\n<li>Breadcrumb navigation above the main content (3).<\/li>\n<li>The main content in the large pain on the right (4).<\/li>\n<\/ul>\n<p>While not revolutionary, the layout uses well-recognized and understood navigation conventions. However, it has a sweet navigational feature. Notice the link right at the bottom (5). If you click it, it opens up a sub-navigation menu.<\/p>\n<p>&nbsp;<\/p>\n<div id=\"attachment_15942\" style=\"width: 366px\" class=\"wp-caption alignleft\"><img loading=\"lazy\" decoding=\"async\" aria-describedby=\"caption-attachment-15942\" class=\"wp-image-15942 size-full\" src=\"https:\/\/owncloud.com\/wp-content\/uploads\/2018\/08\/ownCloud-documentation-migration-to-antora-version-navigation.png\" alt=\"ownCloud documentation migration to Antora - version navigation\" width=\"356\" height=\"188\" \/><p id=\"caption-attachment-15942\" class=\"wp-caption-text\">Version control in Antora<\/p><\/div>\n<p>This is an excellent, time-saving feature that allows for direct navigation between different documentation versions (git branches).<\/p>\n<p>In the current documentation, an extra page exists to link to the various versions of the documentation, such as for version <em>8.2<\/em>, <em>9.x<\/em>, and <em>10.x.<\/em><br \/>\nHowever, by taking advantage of this feature in Antora, that\u2019s not necessary, thanks to this innovative feature.<\/p>\n<p>I expect that it will make users lives so much easier, as they\u2019ll be able to navigate quickly to the version of the documentation that matches their ownCloud installation.<\/p>\n<h2>What Does This Mean For You?<\/h2>\n<p>Despite all this change, if you\u2019re an existing contributor to the ownCloud docs \u2014 or if you\u2019re keen to be in the future \u2014 not a lot is (effectively) changing for you. That said, you will only need to do three things:<\/p>\n<ol>\n<li>Learn the basics of <a href=\"https:\/\/asciidoctor.org\/docs\/asciidoc-syntax-quick-reference\/\" target=\"_blank\" rel=\"noopener noreferrer\">the AsciiDoc file format<\/a>.<\/li>\n<li>Update your toolset so that it supports AsciiDoc and Antora.<\/li>\n<li>Start contributing to <a href=\"https:\/\/github.com\/owncloud\/docs\" target=\"_blank\" rel=\"noopener noreferrer\">the new documentation repository<\/a>.<\/li>\n<\/ol>\n<p>The first two points are outside the scope of this blog post. However, we\u2019ll have follow-up posts shortly, stepping you through both of them. The key thing to bear in mind is that <strong>contributing to the docs is becoming a lot simpler<\/strong> than it is now.<\/p>\n<h2>We Want Your Contributions<\/h2>\n<p>That\u2019s just an overview of why we\u2019re migrating to Antora and what it means for you. It\u2019s been a fun journey so far, and things are just getting started.<\/p>\n<p>I hope that you\u2019re excited by what\u2019s coming, the Antora platform, and being able to contribute to the documentation in a way that\u2019s <em>far<\/em> easier than it is now. If you have any questions, let us know; whether in the comments or on social media.<\/p>\n<p>Stay tuned for the second part in which I will explain the basic steps how to work with Antora and directly contribute to the documentation system.<\/p>\n<p>&nbsp;<\/p>\n<p style=\"text-align: center;\">\n  <div class=\"button-block button-block--center\">\n    <a href=\"https:\/\/github.com\/owncloud\/docs\" class=\"button button--bright-blue\" target=\"_blank\" rel=\"noopener noreferrer\">\n              <i class=\"fa-book\">&nbsp;&nbsp;<\/i>\n            Visit the Repository    <\/a>\n  <\/div>\n\n  <\/p>\n","protected":false},"excerpt":{"rendered":"<p>Minimal Markup, Maximum Functionality: The ownCloud documentation is migrating to Antora, the most modern AsciiDoc based documentation site generator.<\/p>\n","protected":false},"author":7,"featured_media":15958,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_et_pb_use_builder":"","_et_pb_old_content":"","_et_gb_content_width":"","inline_featured_image":false,"footnotes":""},"categories":[48],"tags":[],"class_list":["post-15933","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-news"],"acf":[],"_links":{"self":[{"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/posts\/15933","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/comments?post=15933"}],"version-history":[{"count":1,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/posts\/15933\/revisions"}],"predecessor-version":[{"id":59159,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/posts\/15933\/revisions\/59159"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/media\/15958"}],"wp:attachment":[{"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/media?parent=15933"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/categories?post=15933"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/owncloud.com\/de\/wp-json\/wp\/v2\/tags?post=15933"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}