Nov 18, 2024

Generate Breadcrumbs from Astro URL

A breadcrumb list shows a webpage’s position a website’s page hierarchy. Each breadcrumb links to a page in the hierarchy, allowing users to more easily navigate a website. Google can display breadcrumbs directly in search results.

Breadcrumb visual example

We use structured metadata in the head of a webpage to tell search engines what our breadcrumb list is. With Astro’s url object, we can generate this metadata automatically at build-time.

Recipe

Create a Head component to hold your breadcrumb structured data.

1
<head>
2
  <title>Page Title</title>
3
  <meta name="description" content="Description of the page." />
4
</head>

Retrieve the Astro.url of the current page in your Head component. Astro.url.origin is the base url for the website. Astro.url.pathname is the relative path to the current page.

1
---
2
const origin = Astro.url.origin;
3
const path = Astro.url.pathname;
4
---
5

6
<head>
7
  <title>Page Title</title>
8
  <meta name="description" content="Description of the page." />
9
</head>

Split the path into a list of route names.

1
---
2
const { origin, pathname } = Astro.url;
3
let currentPath = origin + "/";
4
const breadcrumbData = pathname
5
  .split("/")
6
  .filter((s) => s.length > 0)
7
  .map((pathname, index) => {
8
    currentPath += index == 0 ? pathname : "/" + pathname;
9
    return {
10
      "@type": "ListItem",
11
      position: index + 1,
12
      name: pathname,
13
      item: currentPath,
14
    };
15
});
16
---
17

18
<head>
19
  <title>Page Title</title>
20
  <meta name="description" content="Description of the page." />
21
</head>

Filter out any empty strings created by leading and trailing slashes.

1
---
2
const { origin, pathname } = Astro.url;
3
let currentPath = origin + "/";
4
const breadcrumbData = pathname
5
  .split("/")
6
  .filter((s) => s.length > 0)
7
  .map((pathname, index) => {
8
    currentPath += index == 0 ? pathname : "/" + pathname;
9
    return {
10
      "@type": "ListItem",
11
      position: index + 1,
12
      name: pathname,
13
      item: currentPath,
14
    };
15
});
16
---
17

18
<head>
19
  <title>Page Title</title>
20
  <meta name="description" content="Description of the page." />
21
</head>

The breadcrumb metadata requires a list of objects representing each level in the path. Always set @type to "ListItem". Position is the index of the object starting at 1. The name field will be displayed in the generated breadcrumb menu. The item field holds the URL for each level of the path.

Generate an array of ListItem objects from pathname using the map function.

1
---
2
const { origin, pathname } = Astro.url;
3
let currentPath = origin + "/";
4
const breadcrumbData = pathname
5
  .split("/")
6
  .filter((s) => s.length > 0)
7
  .map((pathname, index) => {
8
    currentPath += index == 0 ? pathname : "/" + pathname;
9
    return {
10
      "@type": "ListItem",
11
      position: index + 1,
12
      name: pathname,
13
      item: currentPath,
14
    };
15
});
16
---
17

18
<head>
19
  <title>Page Title</title>
20
  <meta name="description" content="Description of the page." />
21
</head>

The final structured data must have three fields: @context, @schema, and itemListElement. The first two fields are constants, and the third field holds the breadcrumbData list we created.

We create the data object structuredData, stringify it, and use Astro’s set:html function to render it in our Head component. Our structured data will be added with a script tag of type application/ld+json, which Google recommends.

1
---
2
const { origin, pathname } = Astro.url;
3
let currentPath = origin + "/";
4
const breadcrumbData = pathname
5
  .split("/")
6
  .filter((s) => s.length > 0)
7
  .map((pathname, index) => {
8
    currentPath += index == 0 ? pathname : "/" + pathname;
9
    return {
10
      "@type": "ListItem",
11
      position: index + 1,
12
      name: pathname,
13
      item: currentPath,
14
    };
15
});
16

17
const structuredData = {
18
    "@context": "https://schema.org",
19
    "@type": "BreadcrumbList",
20
    itemListElement: breadcrumbData
21
};
22
---
23

24
<head>
25
  <title>Page Title</title>
26
  <meta name="description" content="Description of the page." />
27
  <script type="application/ld+json" set:html={JSON.stringify(structuredData)} />
28
</head>

Call your Head component in your layout or page.

1
---
2
import Head from "@components/Head.astro";
3
---
4

5
<!doctype html>
6
<html>
7
  <Head />
8
  <body>
9
    <main>
10
      <slot />
11
    </main>
12
  </body>
13
</html>