slachiewicz opened a new pull request, #77: URL: https://github.com/apache/maven-doxia-site/pull/77
Two claims on these pages predate 2.0 and now send writers the wrong way. **Heading levels.** `<section>` and `<subsection>` were documented as producing `<h2>` and `<h3>`. Since 2.0 they start at `<h1>`: `Xhtml5BaseSink.onSectionTitle` 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 stops skipping a level. **Anchors.** Section titles were documented as never becoming anchors, so the pages told readers to write every one by hand. `DefaultSiteRenderer` calls `setEmitAnchorsForIndexableEntries(true)`, which makes `AbstractParser` add `CreateAnchorsForIndexEntriesFactory`, so every title gets an anchor derived from its text. This is not xdoc-specific — the flag lives on `AbstractParser`, so the same note in the APT enhancements page and the TOC macro section was wrong too, and all three are corrected together. That also retires the "two shortcomings" passage: `IndexingSink.getUniqueId` suffixes a counter onto repeated ids, so identical titles no longer collide, and `UniqueAnchorNamesValidator` warns when a name is reused. The point worth keeping is the one underneath, now stated directly: a generated anchor follows the wording, so rewording a title silently breaks links aimed at it, and an explicit anchor still wins — `CreateAnchorsForIndexEntries` only fills in where the title has none. Verified: `mvn clean site` → `faq.html` emits `<a id="Frequently_Asked_Questions">` for a heading that carries no anchor in the Markdown source. Touches `macros/index.md`, which #75 also edits, but on different lines — I checked the two merge cleanly. *This change was created with AI assistance.* -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
