Skipping heading ranks
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 465
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 27
Description
With Asciidoc, it is recommended to keep headings in order. That is to say, H4
should not follow H2, better for H3 to follow H2. If you break this it gives a
warning:
asciidoctor: WARNING: readme.adoc: line 11: section title out of sequence:
expected level 2, got level 3
i was somewhat surprised by this, but then i noticed this is an official
recommendation as well:
- https://developer.mozilla.org/Web/HTML/Element/Heading_Elements#Usage_notes
- https://w3.org/WAI/tutorials/page-structure/headings
RDoc has no restriction on header order and in fact doesnt even advise
against out of order headings:
https://ruby.github.io/rdoc/RDoc/Markup#class-RDoc::Markup-label-Headers
Contributor guide
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.
Research direction
Start by reading the RDoc Markup headers documentation linked in the issue and compare its heading-order behavior with the Asciidoctor warning shown. The issue does not name a file, test, or precise desired behavior, so the expected validation and completion criteria need clarification before implementation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100