[felix-antora-site] branch main updated: add a section on page refs

[dj...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

djencks pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/felix-antora-site.git


The following commit(s) were added to refs/heads/main by this push:
     new bc98af3  add a section on page refs
bc98af3 is described below

commit bc98af373b0b60e225850fd8988d4f6b12ff3671
Author: David Jencks <dj...@apache.org>
AuthorDate: Fri Jul 23 11:45:01 2021 -0700

    add a section on page refs
---
 modules/ROOT/pages/development/site-how-to.adoc | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/modules/ROOT/pages/development/site-how-to.adoc b/modules/ROOT/pages/development/site-how-to.adoc
index d794e7c..dc762e2 100644
--- a/modules/ROOT/pages/development/site-how-to.adoc
+++ b/modules/ROOT/pages/development/site-how-to.adoc
@@ -62,13 +62,33 @@ To manually specify an id, precede the section line with `[#my-id]` on a separat
 * Code blocks look like this:
 [source,adoc]
 ------
-[source,java]
-----
+[source,java] <1>
+----  <2>
 class Foo {
 ...
 }
 ----
 ------
+<1> Any language you want: highlighting is available for most.
+<2> Block separator `----`
+
+=== Page links
+
+Between pages::
+Use the `xref:` inline macro:
+`+++xref:other-page.adoc[]+++`.
+
+* The path to the other page starts from the `pages` directory: it is not relative to the current page.
+* For a non-fragment reference, the default link text is the other page title.
+Custom text may be specified inside the `[]` brackets.
+* For fragment references you must specify the link text.
+
+Within a page::
+Use the form `+++<<#_fragment_name, link text>>+++`.
+For a link to a section, the default link text is the section title.
+
+NOTE: The Intellij asciidoc plugin has Antora-aware syntax checking and auto-complete, including the generated section ids.
+
 
 == Local build