wso2 / wso2/api-platform

Fix heading-level increment (MD001) in widdershin-generated REST API docs

Open
#2,671 0 comments 0 reactions 1 assignee View on GitHub

@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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.