(maven-doxia-site) branch master updated: Correct the heading levels and anchor behaviour for 2.0

[sl...@apache.org]

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

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 2360388  Correct the heading levels and anchor behaviour for 2.0
2360388 is described below

commit 23603886e3002d4105177037ee92e68ed67fa687
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Sun Aug 16 14:20:44 2026 +0200

    Correct the heading levels and anchor behaviour for 2.0
    
    Two claims on these pages predate 2.0 and now point writers the wrong way.
    
    Sections were documented as producing h2 and h3. Since 2.0 they start at h1:
    Xhtml5BaseSink maps SECTION_LEVEL_1 to H1, and XdocParser opens <section> at
    level 1 and <subsection> at level 2. The sample sub-heading moves from h4 to
    h3 so it no longer skips a level.
    
    Section titles were documented as never becoming anchors, telling readers to
    write every anchor by hand. DefaultSiteRenderer calls
    setEmitAnchorsForIndexableEntries(true), so AbstractParser adds
    CreateAnchorsForIndexEntriesFactory and every title gets an anchor built from
    its text. The same note appeared for APT in two other pages.
    
    That also retires the "two shortcomings" passage: IndexingSink suffixes a
    counter onto repeated ids, so identical titles no longer collide, and
    UniqueAnchorNamesValidator warns when one name is reused.
    
    What is worth keeping is the point underneath, now stated directly: a
    generated anchor tracks the wording, so a reworded title silently breaks
    inbound links, and an explicit anchor still wins.
    
    Verified: mvn clean site -> faq.html emits <a id="Frequently_Asked_Questions">
    for a heading that carries no anchor in the Markdown source
---
 content/markdown/macros/index.md           |  2 +-
 content/markdown/references/doxia-apt.md   |  2 +-
 content/markdown/references/xdoc-format.md | 18 +++++++-----------
 3 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/content/markdown/macros/index.md b/content/markdown/macros/index.md
index 4b8e4c7..daf9ffa 100644
--- a/content/markdown/macros/index.md
+++ b/content/markdown/macros/index.md
@@ -144,7 +144,7 @@ The _TOC_ macro prints a Table Of Content of a document. It is useful if you hav
 
 This displays a TOC for the second section in the document, including all subsections (depth 2) and sub-subsections (depth 3).
 
-**Note** that in Doxia, apt section titles are not implicit anchors (see [Enhancements to the APT format](../references/doxia-apt.html)), so you need to insert explicit anchors for links to work!
+**Note** that when a site is rendered, Doxia anchors each section title for you, so the entries this macro emits resolve without further work. Define an anchor explicitly (see [Enhancements to the APT format](../references/doxia-apt.html)) where a link has to survive the title being reworded.
 
 In a xdoc file, it will be:
 
diff --git a/content/markdown/references/doxia-apt.md b/content/markdown/references/doxia-apt.md
index 8638f80..ada1e83 100644
--- a/content/markdown/references/doxia-apt.md
+++ b/content/markdown/references/doxia-apt.md
@@ -105,7 +105,7 @@ produces:
 <!--~~~~~~~~~~~~~~~~~~~-->
 ### <a id="Anchors_for_section_titles"></a>Anchors for section titles
 
-Contrary to the original APT format, section titles are **not** implicitly defined anchors. If you want an anchor for a section title you need to define it explicitly as such:
+When a document is rendered as part of a Maven site, Doxia gives every section title an anchor of its own, built from the title text by the rules below. Because that name follows the wording, rewording a title moves the anchor and breaks links aimed at it. Define the anchor explicitly where a reference has to hold:
 
 ```unknown
 * {Anchors for section titles}
diff --git a/content/markdown/references/xdoc-format.md b/content/markdown/references/xdoc-format.md
index 76e00fa..9d660d0 100644
--- a/content/markdown/references/xdoc-format.md
+++ b/content/markdown/references/xdoc-format.md
@@ -106,20 +106,22 @@ code line 2
 <a id="Additional_sectioning"></a> 
 ## Additional sectioning
 
-Doxia will produce `<h2>` and `<h3>` headings for `<section>` and `<subsection>` elements, respectively. It is therefore perfectly valid to put some sub-headings (`<h4>`, `<h5>`, `<h6>`) inside a subsection. For instance, 
+Since Doxia 2\.0, `<section>` and `<subsection>` elements produce `<h1>` and `<h2>` headings respectively; before 2\.0 they started at `<h2>`. It is therefore perfectly valid to put some sub-headings (`<h3>` to `<h6>`) inside a subsection. For instance, 
 
 ```unknown
-<h4>A subsubsection</h4>
+<h3>A subsubsection</h3>
 ```
 
 will produce: 
 
-#### A subsubsection
+### A subsubsection
 
 <a id="Referencing_sections_and_subsections"></a> 
 ## Referencing sections and subsections
 
-The core doxia modules do **not** construct anchors from section/subsection names. If you want to reference a section, you should either provide an explicit anchor: 
+When a document is rendered as part of a Maven site, Doxia creates an anchor for every section and subsection title by itself, deriving the name from the title text and making it unique within the document. A title that is reworded therefore gets a different anchor, which silently breaks links pointing at it. 
+
+For a reference that has to survive editing, name the anchor yourself. Either provide an explicit anchor: 
 
 ```unknown
 <a name="Section1"/>
@@ -143,13 +145,7 @@ or use an `id` attribute for section and subsections (note that `id`&apos;s have
 </section>
 ```
 
-**Note** that this differs from previous behavior, where anchors were constructed from section/subsection names, replacing special characters by underscores. This behavior presents two shortcomings: 
-
-- If two sections or subsections have identical names (within one source document), you will get an ambiguity when referencing them. Also the resulting html document will not be valid XHTML. For other output formats (eg pdf), it might even be impossible to generate the target document. 
-
-- For long section titles, this leads to rather cumbersome anchor names. 
-
-If automatic anchor generation is desired for a particular output format, it should be implemented / overridden by the corresponding low-level Sink. 
+An anchor you write yourself always wins: Doxia only generates one where the title does not already carry it. Two sections sharing a title no longer collide, because generated names are numbered to keep them unique, and Doxia warns when the same anchor name is used more than once in a document. 
 
 ## Validation