Breadcrumb navigation with Schema.org markup

SeriesPart of How this blog was built — documenting every decision that shaped this site.

Breadcrumbs are one of those components that look simple but have several layers of correctness: the visual trail, the accessible markup, and the structured data for search engines. All three matter and only one of them is visible to users.

Breadcrumb.astro handles all three, and it does so with a fallback auto-generation system that derives the crumb list from the URL path when no explicit list is provided.

Breadcrumb component in two contexts — inverted on the dark post hero and default on a light surface — with annotations for aria-current, BreadcrumbList schema markup, and the SERP breadcrumb trail it produces

The component interface

2
interface Crumb {
3
  label: string;
4
  href?: string;
5
}
6

7
interface Props {
8
  crumbs: Crumb[];
9
  inverted?: boolean;
10
  noContainer?: boolean;
11
}

crumbs is an array of label/href pairs. The final crumb in the list should have no href — it represents the current page and shouldn’t be a link. The inverted prop flips the colour scheme for placement on dark backgrounds (like the post hero). The noContainer prop skips the .container wrapper, used when the breadcrumb sits inside a layout that already handles max-width constraints.

The component prepends a “Home” crumb automatically so callers don’t have to include it in every usage:

1
const allCrumbs = [{ label: "Home", href: "/" }, ...crumbs];

Auto-generation from URL path

In PageHero.astro, if no explicit crumbs prop is passed, the component falls back to deriving them from the URL:

41
function autoCrumbs(path: string): Crumb[] {
42
  const segments = path.split("/").filter(Boolean);
43
  const meaningful = segments.filter(
44
    (s) => s !== "page" && !/^\d+$/.test(s)
45
  );
46
  return meaningful.map((seg, i) => ({
47
    label: seg.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
48
    href: "/" + meaningful.slice(0, i + 1).join("/"),
49
  }));
50
}

The filter strips the literal "page" segment and any purely numeric segments — so /blog/page/2 produces crumbs for “Blog” but not “Page” or “2”. This is the right behaviour: pagination is a structural detail, not a meaningful content level.

Labels are formatted by replacing hyphens with spaces and capitalising each word. "why-astro" becomes "Why Astro". It’s not perfect for every slug — a post titled “Using MDX” with slug using-mdx would render as “Using Mdx” — but it’s good enough for this site’s naming conventions.

Schema.org BreadcrumbList

Search engines use BreadcrumbList structured data to display a breadcrumb trail in search results. The markup sits inline in the rendered HTML using itemscope and itemprop attributes:

29
<ol
30
  class="breadcrumb__list"
31
  itemscope
32
  itemtype="https://schema.org/BreadcrumbList"
33
>
34
  {items.map(({ label, href, isLast, position }) => (
35
    <li
36
      class="breadcrumb__item"
37
      itemprop="itemListElement"
38
      itemscope
39
      itemtype="https://schema.org/ListItem"
40
    >
41
      {!isLast && href ? (
42
        <a href={href} class="breadcrumb__link" itemprop="item">
43
          <span itemprop="name">{label}</span>
44
        </a>
45
      ) : (
46
        <span
47
          class="breadcrumb__current"
48
          aria-current="page"
49
          itemprop="name"
50
        >
51
          {label}
52
        </span>
53
      )}
54
      <meta itemprop="position" content={String(position)} />
55
    </li>
56
  ))}
57
</ol>

The <meta itemprop="position"> tag carries the 1-based index for each crumb. Google uses this to understand the hierarchy — it won’t infer the order from DOM order alone when using microdata.

Accessibility

The <nav> element has an aria-label="Breadcrumb" attribute to distinguish it from other navigation landmarks on the page (the main navbar also uses <nav>):

1
<nav aria-label="Breadcrumb" class="breadcrumb-nav">

The current page crumb uses aria-current="page" and is rendered as <span> rather than <a> — it’s the page the user is already on, so making it a link would be misleading. Screen readers announce aria-current="page" explicitly, giving users the context they need.

The complete component and its integration in PageHero.astro are in the sourcier.uk repository.

Full code listing

1
---
2
interface Crumb {
3
  label: string;
4
  href?: string;
5
}
6

7
interface Props {
8
  crumbs: Crumb[];
9
  inverted?: boolean;
10
  noContainer?: boolean;
11
}
12

13
const { crumbs, inverted = false, noContainer = false } = Astro.props;
14
const allCrumbs = [{ label: "Home", href: "/" }, ...crumbs];
15

16
const items = allCrumbs.map((crumb, index) => ({
17
  ...crumb,
18
  isLast: index === allCrumbs.length - 1,
19
  position: index + 1,
20
}));
21
---
22

23
<nav
24
  aria-label="Breadcrumb"
25
  class:list={["breadcrumb-nav", { "breadcrumb-nav--inverted": inverted }]}
26
>
27
  {
28
    noContainer ? (
29
      <ol
30
        class="breadcrumb__list"
31
        itemscope
32
        itemtype="https://schema.org/BreadcrumbList"
33
      >
34
        {items.map(({ label, href, isLast, position }) => (
35
          <li
36
            class="breadcrumb__item"
37
            itemprop="itemListElement"
38
            itemscope
39
            itemtype="https://schema.org/ListItem"
40
          >
41
            {!isLast && href ? (
42
              <a href={href} class="breadcrumb__link" itemprop="item">
43
                <span itemprop="name">{label}</span>
44
              </a>
45
            ) : (
46
              <span
47
                class="breadcrumb__current"
48
                aria-current="page"
49
                itemprop="name"
50
              >
51
                {label}
52
              </span>
53
            )}
54
            <meta itemprop="position" content={String(position)} />
55
          </li>
56
        ))}
57
      </ol>
58
    ) : (
59
      <div class="container is-max-desktop">
60
        <ol
61
          class="breadcrumb__list"
62
          itemscope
63
          itemtype="https://schema.org/BreadcrumbList"
64
        >
65
          {items.map(({ label, href, isLast, position }) => (
66
            <li
67
              class="breadcrumb__item"
68
              itemprop="itemListElement"
69
              itemscope
70
              itemtype="https://schema.org/ListItem"
71
            >
72
              {!isLast && href ? (
73
                <a href={href} class="breadcrumb__link" itemprop="item">
74
                  <span itemprop="name">{label}</span>
75
                </a>
76
              ) : (
77
                <span
78
                  class="breadcrumb__current"
79
                  aria-current="page"
80
                  itemprop="name"
81
                >
82
                  {label}
83
                </span>
84
              )}
85
              <meta itemprop="position" content={String(position)} />
86
            </li>
87
          ))}
88
        </ol>
89
      </div>
90
    )
91
  }
92
</nav>
93

94
<style lang="scss">
95
  .breadcrumb-nav {
96
    padding: 0.6rem 1.5rem;
97
    background-color: var(--surface-elevated);
98
    border-bottom: 1px solid var(--border-subtle);
99

100
    &--inverted {
101
      padding: 0;
102
      background-color: transparent;
103
      border-bottom: none;
104
      margin-bottom: 1.25rem;
105

106
      .breadcrumb__link {
107
        color: var(--text-on-strong-alpha-45);
108

109
        &:hover,
110
        &:focus-visible {
111
          color: var(--accent-primary);
112
        }
113
      }
114

115
      .breadcrumb__current {
116
        color: var(--text-on-strong-alpha-75);
117
      }
118

119
      .breadcrumb__item:not(:last-child)::after {
120
        color: var(--text-on-strong-alpha-25);
121
      }
122
    }
123
  }
124

125
  .breadcrumb__list {
126
    display: flex;
127
    flex-wrap: wrap;
128
    align-items: center;
129
    gap: 0;
130
    list-style: none;
131
    margin: 0;
132
    padding: 0;
133

134
    font-family: "Barlow Condensed", sans-serif;
135
    font-size: 0.8rem;
136
    font-weight: 600;
137
    text-transform: uppercase;
138
    letter-spacing: 0.06em;
139
  }
140

141
  .breadcrumb__item {
142
    display: flex;
143
    align-items: center;
144

145
    &:not(:last-child)::after {
146
      content: "›";
147
      margin: 0 0.4em;
148
      color: var(--text-muted);
149
      font-weight: 400;
150
    }
151
  }
152

153
  .breadcrumb__link {
154
    color: var(--text-muted);
155
    text-decoration: none;
156
    transition: color 0.15s ease;
157

158
    &:hover,
159
    &:focus-visible {
160
      color: var(--accent-primary);
161
    }
162
  }
163

164
  .breadcrumb__current {
165
    color: var(--text-primary);
166
  }
167
</style>

Breadcrumb navigation with Schema.org markup

The component interface

Auto-generation from URL path

Schema.org BreadcrumbList

Accessibility

Full code listing

Need help raising the bar?

Comments

Leave a comment

Get practical engineering notes