This is an automated email from the ASF dual-hosted git repository.
zregvart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-website.git
The following commit(s) were added to refs/heads/main by this push:
new 18f8c18 explain xrefs
18f8c18 is described below
commit 18f8c18bf09fc259e23adab336f3ff31c87dad05
Author: David Jencks <[email protected]>
AuthorDate: Wed Jul 28 20:56:33 2021 -0700
explain xrefs
---
README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 49 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 4c1198c..b65af95 100644
--- a/README.md
+++ b/README.md
@@ -313,21 +313,61 @@ repository in [antora-ui-camel](antora-ui-camel).
You need to rebuild the Antora UI theme in order to see your changes reflected
locally.
-### Changes for Camel and Camel K docs
+### Changes for Antora generated content
+
+Edits to individual pages can generally be made from the "edit this page" link
at the top left of each antora-generated page.
+However, this will not yet work for Camel component documentation pages.
+
+For more extensive changes, use of the Intellij Asciidoctor plugin is
extremely convenient as it provides extensive syntax checking and understands a
great deal of Antora-specific asciidoc syntax such as xrefs.
+The plugin works with all Intellij editors including the free IDEA CE.
+
+Consult the [Antora documentation](https://docs.antora.org/) and [Asciidoctor
documentation](https://docs.asciidoctor.org/home/) for complete information on
Antora and AsciidDoc/Asciidoctor.
The Apache Camel website includes documentation sources from other github
repositories. Content sources are defined in
[antora-playbook.yml](antora-playbook.yml).
-At the moment these are the documentation sources from
[Camel](https://github.com/apache/camel)
-and [Camel K](https://github.com/apache/camel-k). These are basically the
component reference docs and the Camel user
-manual. In case you want to change something here, please go to the respective
github repository and contribute your
-change there.
+Your changes in these repositories will automatically be included in the
website after a site rebuild.
+
+#### Links between pages in Antora content
+
+Links to other pages in Antora content are defined using the xref: inline
macro.
+This takes the form xref:<page id><optional #fragment>[<link text>].
+The default link text for non-fragment links is the target page title.
+
+Antora documentation for page ids is
[here](https://docs.antora.org/antora/3.0/page/page-id/).
+A small project showing the effect of all possible forms of page id is
[here](https://gitlab.com/djencks/simple-examples/-/tree/master/multiple-components/xrefs).
+
+The first step is to determine the component, version, and module of both the
source and target pages.
+
+To determine the component name and version of a page, look in the antora.yml
file next to the "modules" folder the page source is in.
+The "module" is the folder name under "modules".
+The "default" module is "ROOT": leaving out the module name will always take
you to the ROOT module.
+
+Several repositories and start paths in a repository can contribute to the
same component/version.
+For instance, in the main camel repository, the "components" component has
sources under docs/components (dataformats, languages, other, and ROOT
(components) modules) and core/camel-core-engine/src/main/docs (eips module).
+The easiest way to determine the current set of components and their versions
is to consult the website and look in the "drawer" at the bottom left, showing
the current component/version.
+When opened it lists the components and for each component the versions.
+The main camel repository contains both the "components" and "user manual"
Antora components.
+Other components are in the obvious repository.
+
+- To link to another page in the same component/version/module use the
absolute path from "pages": xref:path/to/page.adoc[].
+ For instance, a link from one camel component to another would be
xref:activemq-component.adoc[].
+ A link from any camel-quarkus page to a camel-quarkus extension would be
xref:reference/extensions/activemq.adoc[].
+- To link to a page in another module in the same component/version use the
module name and absolute path from "pages": xref:module:path/to/page.adoc[].
+For instance, a link from a dataformat to a language would be
xref:languages:jsonpath-language.adoc[].
+ A link from a dataformat to an eip would be xref:eips:aggregate-eip.adoc[].
+
+Xref links that do not specify the component or version stay within the same
component/version.
+If only the (Antora) component is specified, the link will be to the "latest"
version of the component.
+This is most likely what you want.
-- [Camel
components](https://github.com/apache/camel/tree/master/docs/components)
-- [Camel user
manual](https://github.com/apache/camel/tree/master/docs/user-manual)
-- [Camel K docs](https://github.com/apache/camel-k/tree/antora/docs)
+- For instance, a link from camel-quarkus to the latest version of a component
would be xref:components::activemq-component.adoc[].
+- A link from a component, eip, or other "components" module to the user
manual would be xref:manual::architecture.adoc[].
+- A link from a component, eip, etc, or the user manual to a camel-quarkus
extension would be xref:camel-quarkus::reference/extensions/activemq.adoc[].
+- Note that specifying the same component as the source page will link to the
latest version of the target page: e.g.
xref:camel-quarkus::reference/extensions/activemq.adoc[] from a version 2.0.0
camel-quarkus page will link to the latest activemq.adoc version, not the 2.0.0
version.
-Your changes in these repositories will automatically get visible on the
website after a site rebuild.
+If you need to link to a specific non-latest version of a page, specify the
version in the xref.
+- A link from anywhere to a camel-quarkus 2.0.0 page would be
xref:2.0.0@camel-quarkus::reference/extensions/activemq.adoc[].
## Build with Maven
