Day 18: “Giving pages a clear shape by using headings” / Steve Barnett #203
+81
−21
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ZoeBijl
changed the title
matuzo
reviewed
Nov 4, 2025
hell/adventcalendar/2025/18/index.md
Outdated
| Some text. Some text. | ||
|
|
||
| ## Heading | ||
| We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet, jump around using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone. |
There was a problem hiding this comment.
use an extension or bookmarklet
To do what?
jump around
For people not knowing how screen readers work that could be confusing. Can we say "navigate" instead?
| ## Text *should not* be a heading | ||
|
|
||
| Some text. | ||
| Ah, this one's a real classic! When we have some big and bold text, for Design Reasons, we sometimes take a bit of a shortcut and mark it up as a heading. Let's say an `<h2>`, because it seems about the right size, or that’s what it says in the design file. But here's the thing: this text doesn't introduce or describe the content that follows. It just "needs" to be big for the look of it. |
There was a problem hiding this comment.
An example would be great, maybe in form of an outline!?
h1: Fruits
h2: Apples
h2: Pears
h2: [BAD HEADING] <-- you would have to come up with something. I'm not creative enough at the moment. :)
h2: Oranges
|
|
||
| This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. Excellent. | ||
|
|
||
| ### How to fix it |
There was a problem hiding this comment.
Again, a before/after example would be great.
Co-authored-by: Manuel Matuzovic <[email protected]>
Co-authored-by: Manuel Matuzovic <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.