Fix heading-level increment (MD001) in widdershin-generated REST API docs
@Piumal1999 is already working on this.
Since Jul 14, 2026.
- Dominant language
- Go
- Stars
- 71
- Forks
- 111
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 110
Description
Summary
Generated REST API documentation under docs/rest-apis/devportal/** uses a #### Enumerated Values (h4) heading immediately following an <h3> section (e.g., <h3 id="get-a-theme-asset-responseschema">Response Schema</h3>). This skips a heading level and triggers markdownlint's MD001 (heading-increment) rule.
Rationale
Consistent heading hierarchy improves accessibility and passes markdown lint checks. Since these docs are generated from a shared widdershin template, hand-editing the generated Markdown files is not a durable fix and would be overwritten on regeneration.
Affected areas
- The widdershin template (or generator configuration) responsible for producing
docs/rest-apis/devportal/*.md. - All generated files under
docs/rest-apis/devportal/that include a "Response Schema" section followed by an "Enumerated Values" subsection (e.g.,docs/rest-apis/devportal/organization-content.md), since the same pattern is likely repeated across the whole set.
Required changes
- Update the heading-level logic in the widdershin template so "Enumerated Values" is emitted as
###(matching the sibling h3 "Response Schema" sections) instead of####, or otherwise adjust the surrounding heading hierarchy so levels increment by one. - Regenerate all affected docs under
docs/rest-apis/devportal/to confirm the fix applies consistently across files.
Acceptance criteria
- markdownlint no longer reports MD001 (heading-increment) warnings for "Enumerated Values" sections in generated REST API docs.
- No other heading-level regressions are introduced across the regenerated docs.
References
- PR: https://github.com/wso2/api-platform/pull/2660
- Review comment: https://github.com/wso2/api-platform/pull/2660#discussion_r3580945396
- Reported by: @Piumal1999
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.