Hi Tadayoshi, this is only for when you want to link from one document to the next, for within document links using the <<..>> style is fine.
Take a look at the Antora documentation[1] for a better explanation. zoran [1] https://docs.antora.org/antora/2.0/asciidoc/in-page-xref/ On Wed, Jul 24, 2019 at 4:47 AM Tadayoshi Sato <sato.tadayo...@gmail.com> wrote: > > And if I'm not mistaken, are the header IDs [[...]] such as: > https://raw.githubusercontent.com/apache/camel/master/core/camel-core/src/main/docs/eips/aggregate-eip.adoc > ----- > [[aggregate-eip]] > == Aggregate EIP > ... > ----- > not necessary any longer as they are used only for <<...>> style of > cross-referencing? > > Best regards, > Tadayoshi > > On Wed, Jul 24, 2019 at 11:41 AM Tadayoshi Sato <sato.tadayo...@gmail.com> > wrote: > > > Great job Zoran and Nayananga! > > > > Just to make sure, is now the <<xxxxx,XXXXX>> type of cross-referencing > > all deprecated and should be rewritten to xref link? Looks like there are > > still a few leftovers that still use the <<xxxxx,XXXXX>> style. > > > > Thank you, > > Tadayoshi > > > > On Wed, Jul 24, 2019 at 3:11 AM Zoran Regvart <zo...@regvart.com> wrote: > > > >> Hi Cameleers, > >> I've added a `xref-validator`[1] to the `docs` module[2], this will > >> fail the build if there's a `xref` link in the asciidoc files (.adoc) > >> that cannot be resolved -- colloquially: broken link. > >> > >> There's been a great effort by Nayananga our GSoC student helping with > >> the website on getting all the links pointing to the right places and > >> it's really easy to mistype a `xref` link, so that's why I've added it > >> as a part of the CAMEL-13589[3]. > >> > >> Now, you might be wondering what are `xref` links and how to prevent > >> them from becoming broken. For Antora, the tool that converts the > >> asciidoc files to html, we need to specify all links between asciidoc > >> files as `xref:` links, previously you might have seen `link:` being > >> used. > >> > >> There's a good explanation of this concept of page ID in the Antora > >> documentation[4] and how to link between two pages using `xref:` > >> links[5]. > >> > >> For now remember that if you're pointing to the documentation within > >> the same Antora component, and we have two such components `manual`[6] > >> and `components`[7], use the form `xref:document.adoc`; and between > >> two Antora components use the form `xref:component::document.adoc`. > >> > >> For example, the cdi.adoc is within the `components` component and > >> when it needs to link to a `camel-maven-archetypes.adoc` in the > >> `manual` component the xref needs to look like: > >> > >> xref:manual::camel-maven-archetypes.adoc[Maven archetypes] > >> > >> Have a look at the example[8] in the git repository. > >> > >> So to test if the xrefs are valid you can run: > >> > >> $ ./mvnw -f docs verify > >> > >> It only takes about 1 minute or so to run. > >> > >> Feel free to reach out to me if you have any questions on this. > >> > >> zoran > >> > >> [1] https://gitlab.com/antora/xref-validator > >> [2] > >> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96 > >> [3] https://issues.apache.org/jira/browse/CAMEL-13589 > >> [4] https://docs.antora.org/antora/2.0/page/page-id/ > >> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/ > >> [6] > >> https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages > >> [7] > >> https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages > >> [8] > >> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071 > >> -- > >> Zoran Regvart > >> > > -- Zoran Regvart