@gurupanguji

Technical Specification: Heading Hierarchy Audit & Breadcrumb Implementation (Issue #212)

Overview

This specification addresses Issue #212, which requires a clean h1 heading hierarchy across the site and semantic breadcrumbs for deeper navigation, focusing specifically on review sub-pages.

Goals

1. Ensure exactly one h1 per page. (Audit is complete; all layouts comply).
2. Fix any heading order regressions in archive templates or review subpages.
3. Implement semantic <nav aria-label="Breadcrumb"> logic on deeper content (reviews).

Non-Goals

1. Refactoring the homepage structure.
2. Adding breadcrumbs to standalone blog posts (the focus is on “review and sub-pages”).

Technical Architecture

1. Heading Regressions Fix

• Target File: reviews/camera/leica/m11-p/index.html
• Problem: In the “Technical Explorer” section (<section id="explorer-section"> with an <h2>), the .hotspot-popup elements use <h4> instead of <h3>.
• Solution: Convert all instances of <h4> to <h3> within .hotspot-popup to preserve the h2 -> h3 semantic hierarchy. No visual changes are required since there are no global CSS rules for h3 or h4 overriding the .hotspot-popup scoping.

2. Semantic Breadcrumbs Component

• CSS Styles: Add the .breadcrumbs styles to assets/css/style.css at the end of the file.

  .breadcrumbs {
    font-family: var(--font-ui);
    font-size: 0.65rem;
    text-transform: uppercase;
    letter-spacing: 3px;
    margin-bottom: 2rem;
    color: var(--text-muted);
  }
  .breadcrumbs ol {
    list-style: none;
    padding: 0;
    margin: 0;
    display: flex;
    flex-wrap: wrap;
    gap: 10px;
  }
  .breadcrumbs li {
    display: inline;
  }
  .breadcrumbs li + li::before {
    content: "//";
    color: var(--border-color);
    margin-right: 10px;
  }
  .breadcrumbs a {
    text-decoration: none;
    color: inherit;
    transition: color 0.3s ease;
  }
  .breadcrumbs a:hover {
    color: var(--leica-red);
  }
  .breadcrumbs span[aria-current="page"] {
    color: var(--text-primary);
    font-weight: 600;
  }
  

3. Breadcrumb Injection Locations

• reviews/index.html:
  • Inject inside <main> just before <h1 class="page-title">.
  • Path: Home -> Reviews
• reviews/camera/fujifilm/x100vi/index.html:
  • Inject inside <main> just before <article class="container"> or inside .container before .lede.
  • Path: Home -> Reviews -> Fujifilm X100VI
• reviews/camera/leica/m11-p/index.html:
  • Inject inside <main> just before <article class="container"> or inside .container before the first section.
  • Path: Home -> Reviews -> Leica M11-P

Testing Strategy

1. Run bundle exec jekyll build to ensure the site builds correctly.
2. Use grep or an HTML validator to confirm exactly one h1 per target page and no skipped heading levels (e.g., no <h4> under <h2>).
3. Visually confirm breadcrumb rendering on the local development server (or rely on HTML structure).