Skip to content

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

Description

@coderabbitai

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions