mdn / mdn/fred

Sectioning algorithm doesn’t take into account neighbouring headings

Open
#1,113 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

a11y
Dominant language
JavaScript
Stars
233
Forks
61
Avg merge
1d 1h
Merged PRs (30d)
82

Description

Description

While working on a fix for https://github.com/mdn/fred/issues/690 and testing how adjacent headings are rendered, I discovered an issue when h2 is always split into its own section.

Example

GLSL shaders

## Final code

### HTML

<!-- Content -->

Becomes two separate sections:

<section class="content-section" aria-labelledby="final_code">
  <h2 id="final_code" class="heading">
    <a class="heading-anchor" href="#final_code">Final code</a>
  </h2>
</section>
<section class="content-section" aria-labelledby="html">
  <h3 id="html" class="heading">
    <a class="heading-anchor" href="#html">HTML</a>
  </h3>
  <!-- Content -->
</section>

More details

It’s all fine when there’s content between headings:

## Heading level two

I'm baby kale chips slow-carb cardigan gochujang.

### Heading level three

Subway tile DSA kinfolk cray meggings.

But it starts failing when headings are adjacent:

## Heading level two

### Heading level three

Subway tile DSA kinfolk cray meggings.

…which creates two separate sections: one with just h2. Which doesn’t make sense.

<section class="content-section" aria-labelledby="heading_level_two_2">
  <h2 id="heading_level_two_2" class="heading">
    <a class="heading-anchor" href="#heading_level_two_2">
      Heading level two
    </a>
  </h2>
</section>

<section class="content-section" aria-labelledby="heading_level_three_2">
  <h3 id="heading_level_three_2" class="heading">
    <a class="heading-anchor" href="#heading_level_three_2">
      Heading level three
    </a>
  </h3>
  <p>Subway tile DSA kinfolk cray meggings.</p>
</section>

Unlike when h3 is followed by h4.

### Heading level three

#### Heading level four

That gives proper section with adjacent headings:

<section class="content-section" aria-labelledby="heading_level_three_3">
  <h3 id="heading_level_three_3" class="heading">
    <a class="heading-anchor" href="#heading_level_three_3">
      Heading level three
    </a>
  </h3>
  <h4 id="heading_level_four_2">
    Heading level four
  </h4>
</section>
Full Markdown content structure for testing 
## Heading level two

I'm baby kale chips slow-carb cardigan gochujang, godard austin selvage master cleanse. Same four dollar toast af kinfolk, neutral milk hotel JOMO shabby chic sustainable hashtag ethical DSA raclette farm-to-table. Salvia chillwave vaporware Brooklyn. Gastropub DIY vinyl ascot stumptown williamsburg helvetica polaroid pitchfork tilde jawn kogi schlitz. Fam fanny pack glossier shoreditch occupy direct trade skateboard williamsburg godard scenester edison bulb salvia. Food truck viral meggings aesthetic, vaporware artisan organic twee before they sold out fingerstache mumblecore.

### Heading level three

Subway tile DSA kinfolk cray meggings. Cupping beard skateboard, iPhone praxis grailed lyft. Fit butcher narwhal, brunch farm-to-table intelligentsia hell of grailed four dollar toast tofu. Biodiesel iceland stumptown lyft. La croix 8-bit flexitarian offal, before they sold out master cleanse mumblecore bicycle rights artisan ascot franzen. Tonx health goth adaptogen enamel pin vinyl farm-to-table normcore flexitarian put a bird on it swag.

#### Heading level four

Gatekeep cardigan marfa sus cred, glossier aesthetic chia palo santo four loko poutine. Flannel venmo narwhal, chicharrones wolf distillery kale chips man braid post-ironic bespoke tilde gorpcore church-key. Fingerstache gastropub bruh, food truck next level activated charcoal gorpcore viral. Hoodie intelligentsia tonx skateboard green juice, mumblecore affogato pok pok. Keffiyeh jianbing tofu, williamsburg vaporware distillery neutra cred seitan.

##### Heading level five

VHS schlitz art party neutra letterpress. Small batch franzen typewriter big mood. Meditation stumptown disrupt, iceland kale chips paleo fit trust fund prism banh mi vice cronut vaporware schlitz raw denim. Cronut sartorial PBR&B listicle celiac farm-to-table kale chips pour-over vice pop-up leggings ascot tumblr. 8-bit man braid slow-carb banh mi organic, jawn helvetica lumbersexual fixie. Direct trade gentrify chambray typewriter single-origin coffee wolf fam synth photo booth jean shorts hashtag man braid narwhal shaman. Woke etsy fixie hot chicken chia crucifix man bun mixtape.

###### Heading level six

Deep v seitan DSA, venmo yes plz big mood palo santo heirloom fingerstache craft beer cred normcore woke food truck chillwave. Godard tbh kickstarter, shabby chic ethical subway tile butcher coloring book pork belly. Skateboard authentic praxis wolf activated charcoal small batch hella pour-over big mood jean shorts brunch everyday carry pabst single-origin coffee. Marfa flannel thundercats yr, distillery JOMO hot chicken ethical.

## Heading level two

### Heading level three

I'm baby kale chips slow-carb cardigan gochujang, godard austin selvage master cleanse. Same four dollar toast af kinfolk, neutral milk hotel JOMO shabby chic sustainable hashtag ethical DSA raclette farm-to-table. Salvia chillwave vaporware Brooklyn. Gastropub DIY vinyl ascot stumptown williamsburg helvetica polaroid pitchfork tilde jawn kogi schlitz. Fam fanny pack glossier shoreditch occupy direct trade skateboard williamsburg godard scenester edison bulb salvia. Food truck viral meggings aesthetic, vaporware artisan organic twee before they sold out fingerstache mumblecore.

### Heading level three

#### Heading level four

I'm baby kale chips slow-carb cardigan gochujang, godard austin selvage master cleanse. Same four dollar toast af kinfolk, neutral milk hotel JOMO shabby chic sustainable hashtag ethical DSA raclette farm-to-table. Salvia chillwave vaporware Brooklyn. Gastropub DIY vinyl ascot stumptown williamsburg helvetica polaroid pitchfork tilde jawn kogi schlitz. Fam fanny pack glossier shoreditch occupy direct trade skateboard williamsburg godard scenester edison bulb salvia. Food truck viral meggings aesthetic, vaporware artisan organic twee before they sold out fingerstache mumblecore.

#### Heading level four

##### Heading level five

I'm baby kale chips slow-carb cardigan gochujang, godard austin selvage master cleanse. Same four dollar toast af kinfolk, neutral milk hotel JOMO shabby chic sustainable hashtag ethical DSA raclette farm-to-table. Salvia chillwave vaporware Brooklyn. Gastropub DIY vinyl ascot stumptown williamsburg helvetica polaroid pitchfork tilde jawn kogi schlitz. Fam fanny pack glossier shoreditch occupy direct trade skateboard williamsburg godard scenester edison bulb salvia. Food truck viral meggings aesthetic, vaporware artisan organic twee before they sold out fingerstache mumblecore.

##### Heading level five

###### Heading level six

I'm baby kale chips slow-carb cardigan gochujang, godard austin selvage master cleanse. Same four dollar toast af kinfolk, neutral milk hotel JOMO shabby chic sustainable hashtag ethical DSA raclette farm-to-table. Salvia chillwave vaporware Brooklyn. Gastropub DIY vinyl ascot stumptown williamsburg helvetica polaroid pitchfork tilde jawn kogi schlitz. Fam fanny pack glossier shoreditch occupy direct trade skateboard williamsburg godard scenester edison bulb salvia. Food truck viral meggings aesthetic, vaporware artisan organic twee before they sold out fingerstache mumblecore.

Contributor guide

Open the contributing guide

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.

Research direction

Start by reproducing the adjacent-heading examples in the sectioning algorithm, including the h2 followed immediately by h3 and the h3 followed by h4. Trace how headings are grouped into content sections and verify the result against the expected HTML shown in the issue. Done means an h2 is not emitted as an empty section when a neighbouring lower-level heading follows it.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
40/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.