gatsby-plugin-universal-menus
v0.1.7
Published
Gatsby plugin universal menus. Unlimited nested menus. source from local markdown files or source from anywhere
Downloads
11
Maintainers
Readme
gatsby-plugin-universal-menus
A menu plugin for Gatsby that allows for infinitely nested menus. Can also be extended to load menus from any source.
Full support for extracting menus defined in markdown from soiurce-filesystem.
:Martin Andersen [email protected] (@webmaistro)
Install
`npm install --save gatsby-plugin-universal-menus`
How to use
In your gatsby-config.js
// gatsby-config.js
plugins: [
{
resolve: 'gatsby-plugin-universal-menus',
options: {
// static definition of menu items (optional)
menus: {
main: // identifier of menu container
[ // array of contained children menu items
{
identifier: 'myId', // identifier for this item (optional)
title: 'Title for page',
url: '/page-1/',
weight: 1
}
]
},
// Gatsby node types from which we extract menus (optional, see "Advanced usage")
sourceNodeType: 'MarkdownRemark',
// the relative node path where we can find the 'menus' container (optional)
sourceDataPath: 'frontmatter',
// the relative node path where we can find the page's URL (required)
sourceUrlPath: 'fields.url',
// custom menu loading function (optional)
menuLoader: customLoaderFunction,
// the property to use for injecting to the page context (optional, see "Advanced usage")
pageContextProperty: 'menus',
},
},
],
In your Markdown pages
By default, all Markdown pages can define which menus contain them.
See Advanced usage to learn how to extract menus from other sources.
There are several supported ways to add a page to a menu:
- Single menu container:
---
title: Lorem Ipsum
menus: main # identifier of menu container
---
- Multiple menu containers:
---
title: Lorem Ipsum
menus:
- main
- footer
---
- Overriding menu item values:
---
title: Lorem Ipsum
menus:
main:
identifier: myId # identifier for this item (optional)
title: Go to Lorem Ipsum # override title for this item
weight: 1
---
How to query
A sample GraphQL query to get menus:
{
menus {
main {
identifier
title
url
items {
identifier
title
url
}
}
footer {
identifier
title
url
}
}
}
The field items
contains the sub-menu items if available. The query should nest to accommodate the maximum hierarchy needed.
Menu order
Items within a menu are first ordered by their defined weight
(both from static and page menu items). If weights are equal, then menu items defined in the plugin options (static) are placed first by their appearance order, followed by page menu items ordered by their page's creation time (birthTime).
Advanced usage
Source options
The plugin defines the following options to customize where menu information is extracted from:
sourceNodeType
- The Gatsby node type we want to extract menus from (default: MarkdownRemark)sourceDataPath
- The relative path in the node where we expect to find themenus
item which contains menu information. In case there is no explicit title defined for the menu item, we attempt to find the default title under${sourceDataPath}.title
. (default: frontmatter)
sourceUrlPath
- The relative path in the node where we expect to find the page's URL. This option is always required.
If more flexibility is needed for deciding how menus are loaded, a custom function should be defined.
Custom loader
It is possible to override the default behavior of extracting menu items from Markdown pages by providing your own custom loader function.
- Provide custom function in the plugin options:
// gatsby-config.js
plugins: [
{
resolve: 'gatsby-plugin-universal-menus',
options: {
...// custom menu loading function (optional)
menuLoader: customLoaderFunction,
},
},
],
- Implement custom loader function:
customLoaderFunction = (loaderActions) => {
const { getNodesByType, getNode } = loaderActions
...
return {
main: [
{
identifier: 'myId',
title: 'Title for page',
url: '/page-1/',
weight: 1,
data: {
... // custom data that will be made available via graphql
}
}
]
}
}
Accessing frontmatter
Menu items created from Markdown pages expose additional information about the page they were generated from. We can use that information to include other information that was defined in the Markdown page's frontmatter.
- Markdown page:
---
title: Lorem Ipsum
moreInfo: Additional pieces of information
menus: main
---
- GraphQL query:
{
menus {
main {
identifier
title
url
page {
frontmatter {
moreInfo
}
}
}
}
}
Page context
The plugin can be used to inject the menus structure directly into the context of your Gatsby pages.
To enable this, set the pageContextProperty
option:
// gatsby-config.js
pageContextProperty: 'menus'
And the menus will be available in the page's context:
this.props.pageContext.menus