Overview
API reference pages must emit headings at fixed absolute HTML levels
regardless of where golem:apidoc[] appears in a document.
Currently injected headings shift relative to nesting depth, breaking
screen reader navigation and WCAG 2.1 SC 1.3.1.
Required Mapping
| HTML level |
Meaning |
<h1> |
Module title |
<h2> |
Top-level exported symbol (Class, Function, Exception) |
<h3> |
Method, property, class variable |
<h4> |
Parameter category, nested type attribute |
Implementation Approach
The apidoc Chameleon templates (in the plugin's own template directory per
webmaven/asciidoctype#7) render headings as literal <h2>/<h3>/<h4>
HTML, bypassing AsciiDoctrine's heading-level normaliser entirely.
A cleaner long-term alternative is webmaven/asciidoctrine#128
(absolute-level ASG node attribute). If that lands first, the
NodeTransformer in #10 can set absolute-level on injected headings instead.
Dependencies
Requires:
Enabled by (makes this cleaner):
Acceptance Criteria
Overview
API reference pages must emit headings at fixed absolute HTML levels
regardless of where
golem:apidoc[]appears in a document.Currently injected headings shift relative to nesting depth, breaking
screen reader navigation and WCAG 2.1 SC 1.3.1.
Required Mapping
<h1><h2><h3><h4>Implementation Approach
The apidoc Chameleon templates (in the plugin's own template directory per
webmaven/asciidoctype#7) render headings as literal
<h2>/<h3>/<h4>HTML, bypassing AsciiDoctrine's heading-level normaliser entirely.
A cleaner long-term alternative is webmaven/asciidoctrine#128
(
absolute-levelASG node attribute). If that lands first, theNodeTransformer in #10 can set
absolute-levelon injected headings instead.Dependencies
Requires:
Enabled by (makes this cleaner):
absolute-levelheading attributeAcceptance Criteria
<h2>.<h3>.<h4>.golem:apidoc[]placement depth.