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

Reply via email to