Skip to content

feat(apidoc): predictable heading hierarchy enforcement (h2/h3/h4 by symbol depth) #28

Description

@webmaven

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

  • Class/function/exception headings always <h2>.
  • Method/property headings always <h3>.
  • Parameter category headings always <h4>.
  • Levels correct regardless of golem:apidoc[] placement depth.
  • WCAG 2.1 SC 1.3.1 satisfied.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions