Skip to content

a11y(blocks): render collection/markdown section titles as <h2>#3344

Open
Vidminas wants to merge 1 commit into
HugoBlox:mainfrom
Vidminas:a11y/section-title-headings
Open

a11y(blocks): render collection/markdown section titles as <h2>#3344
Vidminas wants to merge 1 commit into
HugoBlox:mainfrom
Vidminas:a11y/section-title-headings

Conversation

@Vidminas

Copy link
Copy Markdown

The collection and markdown blocks rendered their title as a styled <div class="text-3xl">, so section titles ("Recent Publications", "Recent News", …) never appeared in the document heading outline and screen-reader heading navigation skipped them (WCAG 1.3.1).

πŸš€ What type of change is this?

  • πŸ› Bug fix (A non-breaking change that fixes an issue)
  • ✨ New feature (A non-breaking change that adds functionality)
  • πŸ’… Style change (A change that only affects formatting, visuals, or styling)
  • πŸ“š Documentation update (Changes to documentation only)
  • 🧹 Refactor or chore (A code change that neither fixes a bug nor adds a feature)
  • πŸ’₯ Breaking change (A fix or feature that would cause existing functionality to not work as expected)

🎯 What is the purpose of this change?

The collection and markdown blocks render their section title as a styled
<div class="text-3xl">. So headings like "Recent Publications", "Recent News", etc. don't
appear in the document heading outline
, and screen-reader heading navigation (a primary way AT
users skim a page) skips them entirely (WCAG 1.3.1).

Fix. Render the title as <h2>, keeping the existing visual classes. This matches the
portfolio block, which already uses <h2> for its title β€” so it also makes the three blocks
consistent.

Verified on the academic-cv starter: the homepage now exposes five <h2> section headings
("πŸ“š My Research", "Featured Publications", "Recent Publications", "Recent & Upcoming Talks",
"Recent News") with no remaining title <div>s.


πŸ“Έ Screenshots or Screencast (if applicable)

Although it's primarily a semantic fix, because the title becomes an <h2> it now inherits the theme's heading font (and heading line-height/tracking) instead of the body font β€” the same font the portfolio block's title already uses. On the academic-cv starter that's Lora (heading) vs Source Serif 4 (body); see the screenshots below. The text-3xl font-bold size/weight classes are unchanged, so only the typeface shifts.

The same "Recent Publications" title rendered both ways, with the real webfonts loaded:

div (Source Serif 4) vs h2 (Lora), light theme div (Source Serif 4) vs h2 (Lora), dark theme

The effect is theme-independent; both themes are shown for completeness.


ℹ️ Documentation Check

  • No, this change does not require a documentation update.
  • Yes, I have updated the documentation accordingly (or will in a follow-up PR).

No config or API changes. Worth noting: the markdown block's own README already claims
"Accessibility First: Semantic HTML structure with proper heading hierarchy" β€” which was
inaccurate while the title rendered as a <div>. This change makes that existing claim true, so no
doc edit is needed (it's the code catching up to the docs).


πŸ“œ Contributor Agreement

Thank you for your contribution!

The collection and markdown blocks rendered their title as a styled
`<div class="text-3xl">`, so section titles ("Recent Publications", "Recent
News", …) never appeared in the document heading outline and screen-reader
heading navigation skipped them (WCAG 1.3.1).

Render the title as `<h2>` (keeping the visual classes), matching the portfolio
block, which already uses `<h2>`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@Vidminas
Vidminas requested a review from gcushen as a code owner July 12, 2026 15:27
@netlify

netlify Bot commented Jul 12, 2026

Copy link
Copy Markdown

βœ… Deploy Preview for academic-demo canceled.

Name Link
πŸ”¨ Latest commit 2429441
πŸ” Latest deploy log https://app.netlify.com/projects/academic-demo/deploys/6a53b2612517bb000862527e

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant