astro-navigation
A plugin for creating hierarchical navigation in Astro projects. Supports breadcrumbs too!
Full docs coming soon!
Basic usage
This packages adds two components useful for building hierarchical navigation in Astro.
Just use Astro.glob() to find your local Markdown and MDX pages, pass them to the <Navigation /> component and you're all set!
component
This is the main component, building the HTML for a sorted navigation menu. Include a bit of frontmatter on each .md or .mdx page and the component will handle sorting and nesting pages automatically.
In your layout or page, use Astro.glob() to find all Markdown or MDX pages that should be included in the navigation menu. The <Navigation> component will build the list itself but leaves rendering a <nav> element to your app.
---
import Navigation from 'astro-navigation'
import type { PageFrontmatter } from 'astro-navigation'
const pages = await Astro.glob<PageFrontmatter>('../content/**/*.md')
---
<nav aria-label="Navigation menu" id="navigation">
<Navigation pages={pages} />
</nav>
<style is:global>
#navigation ol {
padding: 0;
}
#navigation li {
line-height: 2;
}
<style>
Each markdown or MDX file should include navigation.order in its frontmatter. This order is used to sort sibling pages. Nesting is based on the url provided by Astro.glob() and can be overridden with a permalink frontmatter property, if needed.
---
title: Example site # text used in the menu, if `navigation.title` is not provided
permalink: /post-1 # URL for the page, if `url` is not provided by `Astro.glob()`
navigation:
order: 1 # used to sort sibling pages
title: My Awesome page # (optional) overrides the `title` frontmatter used above
---
# My awesome page
component
The API surface for breadcrumbs is very similar. Astro.glob() your pages and pass them to the component, it will automatically generate a list of breadcrumbs for the current page. Again, this doesn't render the <nav> element since the specific use case varies between sites.
The <Breadcrumbs> component will automatically include ld+json structured data for your breadcrumbs! This information is often used by search engines to add breadcrumbs to search results.
---
import { Breadcrumbs } from 'astro-navigation'
import type { PageFrontmatter } from 'astro-navigation'
const pages = await Astro.glob<PageFrontmatter>('../content/**/*.md')
---
<nav aria-label="Breadcrumbs" id="breadcrumbs">
<!-- `<ul>` is used by default, this can be overridden with the "as" prop -->
<Breadcrumbs pages={pages} as="ol" />
</nav>
<style is:global>
#breadcrumbs ol {
list-style: none;
display: flex;
column-gap: 2ch;
}
#breadcrumbs a {
text-decoration: none;
}
#breadcrumbs a:is(:hover, :focus-visible) {
text-decoration: underline;
}
</style>
![[ci] release](https://avatars.githubusercontent.com/in/15368?v=4)
2 Feb 16, 2021
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
22 Dec 30, 2022
2 Jan 27, 2022
252 Dec 15, 2022
8k Dec 29, 2022
11 Dec 25, 2022
2 Mar 10, 2022
2 Mar 26, 2022
59 Dec 18, 2022
6 Nov 5, 2022
14 Sep 6, 2022
11 Dec 12, 2022
17 Nov 21, 2022
36 Dec 16, 2022
26 Jan 2, 2023
33 Dec 11, 2022