Unverified Commit c08ce2cf authored by Thomas Bouffard's avatar Thomas Bouffard Committed by GitHub
Browse files

documentation: reference the Antora 3 documentation (#359)

Remove remaining links to Antora 2.3 except for the Mardown to AsciiDoc migration as it applies to this Antora version.
To simplify future maintenance, use an AsciiDoc attribute to avoid duplicating the version.
Some links that were redirected to renamed pages have been updated.
parent ec5be86f
......@@ -9,6 +9,7 @@ ifdef::env-github[]
endif::[]
// External URIs:
:url-antora: https://antora.org
:url-antora-docs: https://docs.antora.org/antora/3.0
:url-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
......@@ -68,7 +69,7 @@ This includes building the documentation using:
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
* a set of branches of various components. It lets validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* a set of branches of various components. It lets validate {url-antora-docs}/page/page-links/[references between pages that belong to different docs components and/or versions]
* ....
To know all available options, run
......@@ -104,7 +105,7 @@ In the following, we use both scripts indifferently.
==== Preview support overview
The documentation is built by passing a playbook file to the Antora CLI. For more details, see
https://docs.antora.org/antora/2.3/cli/options/[Antora CLI documentation].
{url-antora-docs}/cli/options/[Antora CLI documentation].
For the preview support, we generate a dedicated Antora playbook based on the production playbook store in the repository
and options passed to the `build-preview.bash`. +
......@@ -114,7 +115,7 @@ Then, this custom playbook is passed to the Antora CLI along with specific optio
[[local-content]]
===== Using local documentation content repositories
This activates the https://docs.antora.org/antora/2.3/playbook/author-mode/[Antora author mode]. +
This activates the {url-antora-docs}/playbook/author-mode/[Antora author mode]. +
Antora uses the locally cloned repositories as they are on your local machine instead of cloning them from their remote location.
This provides a fast feedback loop as you don't need to push nor commit sources content. This also makes developments easier when working offline.
......@@ -174,7 +175,7 @@ This provides a fast feedback loop as you don't need to build copy the UI bundle
a build command: everything can be done by running a single command once the push nor commit content as the current work.
Remember that the theme repository provides a preview with mock content that make development easier. But sometimes, integration
tests are required to ensure everything is ok, especially when dealing with https://docs.antora.org/antora/2.3/playbook/site-keys/[site keys].
tests are required to ensure everything is ok, especially when dealing with {url-antora-docs}/playbook/site-keys/[site keys].
[NOTE]
.Repositories location
......@@ -216,7 +217,7 @@ This can be achieved by running
----
If you want to ensure you use the latest version of the bundle pass `--default-ui-bundle snapshot`. Otherwise, a cache
version is used. For more details, see the https://docs.antora.org/antora/2.3/playbook/ui-bundle-url/#snapshot[Antora Documentation]
version is used. For more details, see the {url-antora-docs}/playbook/ui-bundle-url/#snapshot[Antora Documentation]
===== Quick fix and experiment Antora UI changes directly in the documentation site
......@@ -224,7 +225,7 @@ version is used. For more details, see the https://docs.antora.org/antora/2.3/pl
If you need/want to experiment changes without rebuilding the theme, especially if the changes only involve the template,
you can directly put the files in the documentation site.
See the https://docs.antora.org/antora/3.0/playbook/ui-supplemental-files/[Antora supplemental UI] for a complete explanation.
See the {url-antora-docs}/playbook/ui-supplemental-files/[Antora supplemental UI] for a complete explanation.
==== http dev server
......@@ -265,7 +266,7 @@ WARNING: This is probably something you won't often do as the site is not fully
[CAUTION]
====
The following command https://docs.antora.org/antora/2.3/playbook/runtime-fetch/[fetch the documentation content repositories] each time it runs. +
The following command {url-antora-docs}/playbook/runtime-fetch/[fetch the documentation content repositories] each time it runs. +
See <<non-production-build>> for alternatives.
====
......
......@@ -7,6 +7,7 @@ ifdef::env-github[]
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
:url-antora-docs: https://docs.antora.org/antora/3.0
== Configuration files
......@@ -16,7 +17,7 @@ See the https://docs.netlify.com/routing/redirects/#syntax-for-the-netlify-confi
for more details about the how to configure the redirects.
Antora is configured to generate a Netlify `_redirects` file to manage aliases. The file is generated in `build/site`.
See https://docs.antora.org/antora/2.3/playbook/urls-redirect-facility/#generated-redirect-configuration-for-netlify[Antora] and
See {url-antora-docs}/playbook/urls-redirect-facility/#generated-redirect-configuration-for-netlify[Antora] and
https://docs.netlify.com/routing/redirects/[Netlify] documentation for more details.
Be aware of the https://docs.netlify.com/routing/redirects/#rule-processing-order[Netlify rule processing order] for rules
......
......@@ -9,10 +9,11 @@ ifdef::env-github[]
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
:url-antora-docs: https://docs.antora.org/antora/3.0
We are pleased to receive any kind of contribution (issues, pull requests, suggestions ...).
=== Theme online example
== Theme online example
A https://bonitasoft.github.io/bonita-documentation-theme/index.html[website] is available to show you what is possible with our Bonita theme.
......@@ -111,7 +112,7 @@ It is also possible to configure substitution globally for the block (see the do
=== Antora modules
You can use Antora modules to clarify content (for instance, getting-started guides, how-to articles). +
See https://docs.antora.org/antora/2.3/module-directories/#module.
See {url-antora-docs}/module-directories/#module.
[quote]
____
......@@ -128,7 +129,7 @@ IMPORTANT: Impact on SEO
See
* https://docs.antora.org/antora/2.3/page/page-aliases
* {url-antora-docs}/page/page-aliases
* https://github.com/bonitasoft/bonita-labs-doc/pull/123 for an example applied to our documentation
=== Adding link between two components or between versions of the same component
......@@ -140,8 +141,8 @@ For instance
To avoid introducing hard coded url, follow the Antora documentation (see https://opendevise.com/blog/referencing-pages/ for rationale)
* https://docs.antora.org/antora/2.3/page/page-id/
* https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/
* {url-antora-docs}/page/page-id/
* {url-antora-docs}/page/version-and-component-xrefs/
[WARNING]
====
......@@ -156,17 +157,17 @@ target component versions. See https://github.com/bonitasoft/bonita-documentatio
==== Examples
The `examples` directory can be used to store source code which can then easily be integrated in the documentation. +
See https://docs.antora.org/antora/2.3/examples-directory/
See {url-antora-docs}/examples-directory/
This allows user to download the source as attachments by providing a link directly for the code (no duplication between the actual examples and the documentation)
==== Attachments
Attachments are also possible: https://docs.antora.org/antora/2.3/attachments-directory/
The syntax is described in https://docs.antora.org/antora/2.3/navigation/reference-resources/ (it uses the `link` macro)
Attachments are also possible: {url-antora-docs}/attachments-directory/
The syntax is described in {url-antora-docs}/navigation/reference-resources/ (it uses the `link` macro)
[TIP]
====
Antora 3 provides a new syntax for referencing attachments. See https://docs.antora.org/antora/3.0/navigation/reference-resources/ +
Antora 3 provides a new syntax for referencing attachments. See {url-antora-docs}/navigation/reference-resources/ +
Please prefer this syntax when Antora 3 will be used to build the site: it allows detecting broken references because it uses the `xref` macro.
====
......@@ -7,6 +7,7 @@ ifdef::env-github[]
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
:url-antora-docs: https://docs.antora.org/antora/3.0
CAUTION: this is a work in progress
......@@ -44,7 +45,7 @@ GA release (actions to be performed detailed later in this document):
=== Don't use Antora component without version
No version Antora component: https://docs.antora.org/antora/2.3/component-with-no-version/
No version Antora component: {url-antora-docs}/component-with-no-version/
The documentation site search crawling and widget we have setup, require a component and a version. In case of version less
components, there is no version token in the url, so this defeats the mechanism in place.
......@@ -62,7 +63,7 @@ The configuration is available in the https://crawler.algolia.com/admin/crawlers
=== How to integrate a new component
To add a new component, you first need to create a GitHub repository which will contain the asciidoc sources of this component
(i.e. the documentation content). This repository must be organized according to the https://docs.antora.org/antora/2.3/organize-content-files/[Antora recommendations].
(i.e. the documentation content). This repository must be organized according to the {url-antora-docs}/organize-content-files/[Antora recommendations].
You can check existing repositories for working examples.
At minimum, it will contain an `antora.yml` file at its root
......@@ -181,7 +182,7 @@ Additional actions
apply to beta and RC versions
See https://docs.antora.org/antora/2.3/component-prerelease/ to know how to
See {url-antora-docs}/component-prerelease/ to know how to
* mark a prerelease version
* display beta/rc additional information in the version
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment