SEO: heading hierarchy skips h2, recipe pages are thin content, docs only exist as hash anchors

[limonte]

Problem

Heading hierarchy skips a level

src/components/Header.tsx:163

<h1>A beautiful, responsive, customizable, accessible (WAI-ARIA) replacement for JavaScript's popup boxes</h1>
<h2>Zero dependencies</h2>

<h2> is used for a two-word tagline, and then every top-level section jumps straight to <h3>:

Component	Heading
Examples.tsx	<h3 id="examples">
Installation.tsx	<h3 id="download">, <h3 id="usage">, <h3 id="frameworks-integrations">
Themes.tsx	<h3 id="themes">
ConfigurationParams.tsx	<h3 id="configuration">
DeclarativeTemplates.tsx	<h3 id="declarative-templates">
HandlingButtons.tsx	<h3 id="handling-buttons">
HandlingDismissals.tsx	<h3 id="handling-dismissals">
Icons.tsx	<h3 id="icons">
InputTypes.tsx	<h3 id="input-types">
Methods.tsx	<h3 id="methods">
Sponsors.tsx	<h3 id="sponsors">, <h3 id="nsfw-sponsors">

So the document outline is h1 → h2(tagline) → h3 → h4, with no h2 for any actual section. Also worth noting <h4> is used for individual option/method names inside table cells (~70 of them), which makes the outline very flat and repetitive.

Fix: promote all section <h3> to <h2>, promote the in-table <h4> to <h3>, and either drop the "Zero dependencies" <h2> or make it a <p class="tagline">.

Recipe pages have almost no indexable text

recipe-gallery/colored-toasts.tsx is representative of all 21:

<Nav recipeGallery />
<Prtnr />
<h1>Colored Toasts</h1>
<Sandpack files={{ '/App.ts': src, '/styles.css': styles }} previewHeight={250} />

That's it — an <h1> plus a Sandpack editor. The code itself is pulled in via ?raw imports into the JS bundle, so it isn't crawlable HTML either. Each recipe page is a thin page: 2–4 words of unique text.

Fix: give each recipe 1–3 paragraphs — what problem it solves, when to reach for it, what the key options do, and a link to the relevant Configuration Params anchors. Also render the source code in a plain <pre><code> block (crawlable) in addition to / instead of only the Sandpack embed. This also fixes the empty meta descriptions in the meta-tags issue.

All docs live at hash anchors on one page

Every doc section is a fragment of /: /#configuration, /#methods, /#icons, /#input-types. Fragments are not separate URLs to Google — the entire documentation competes as a single result. A search for sweetalert2 inputValidator or sweetalert2 preConfirm has no dedicated page to rank.

Fix (larger, worth discussing separately): split the docs into real pages — /configuration/, /methods/, /icons/, /input-types/ — keeping the anchors as in-page deep links. The build already supports multiple entries via rolldownOptions.input.

No breadcrumbs or lateral internal links

Recipe pages link only back to /recipe-gallery/. There's no "related recipes", no links from a recipe into the relevant Configuration Params anchor, and no visible breadcrumb trail. Weak internal linking limits how PageRank flows to the 21 recipe pages.

Impact

Medium-high — the thin-recipe-pages part is the most actionable, and pairs naturally with writing real meta descriptions.

[limonte]

Closing. One part shipped; the other three are not proportionate to their value.

Shipped: breadcrumbs and internal linking

Recipe pages now carry a visible SweetAlert2 / Recipe Gallery trail matching the BreadcrumbList markup (#272, cascade bug fixed in #274). All 21 recipe pages previously linked only sideways to the gallery; they now link to the homepage too, which was the internal-linking weakness noted here.

Not doing: heading hierarchy

Scoped it properly: 163 elements across 11 files — 14 section <h3> → <h2>, 149 pill <h4> → <h3>, plus demoting the "Zero dependencies" <h2> tagline.

It cannot be a simple tag swap, because the styling is global and tag-based:

h3 { font-size: 1.75em; text-transform: uppercase; margin-top: 3em; &::before { ... } }
h4, strong { display: inline-block; background-color: #eaeaea; color: #b9316f; ... }

SweetAlert2 renders popup titles as <h2>, and this site has no swal2-title rule of its own — so promoting sections to h2 while keeping bare tag selectors would apply a 1.75em uppercase section style with a ::before decoration to every popup title on a site built almost entirely of popup demos. Doing it safely means moving both rules onto classes first.

That is the same cascade trap as #274, at 163× the surface, and there is no visual-regression tooling here to catch it. Google has also been explicit that heading order is not itself a ranking factor; the genuine benefit is screen-reader navigation, which does not justify that risk profile right now.

Not doing: thin recipe pages, and hash-only doc URLs

Both were largely arguments about making content more indexable, and #253 is closed — the docs body is not in the served HTML at all, so restructuring which URL it lives at, or adding prose around it, moves much less than it would on a prerendered site.

The recipe-intro idea is still the cheapest of the three if this is ever revisited: 1–3 paragraphs per recipe describing the problem it solves, with links into the relevant Configuration Params anchors. It helps readers regardless of crawlers, and it would also give the meta descriptions from #269 matching on-page text.