Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/weirdpattern/gatsby-remark-series
Gatsby remark table of content generator for series
https://github.com/weirdpattern/gatsby-remark-series
gatsby gatsby-plugin gatsby-remark gatsbyjs plugin remark series table-of-contents toc
Last synced: 3 months ago
JSON representation
Gatsby remark table of content generator for series
- Host: GitHub
- URL: https://github.com/weirdpattern/gatsby-remark-series
- Owner: weirdpattern
- License: mit
- Created: 2019-03-21T05:16:12.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T18:16:58.000Z (about 2 years ago)
- Last Synced: 2024-10-09T12:42:44.279Z (4 months ago)
- Topics: gatsby, gatsby-plugin, gatsby-remark, gatsbyjs, plugin, remark, series, table-of-contents, toc
- Language: JavaScript
- Size: 2.01 MB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# gatsby-remark-series
This plugin dynamically creates and updates table of content (toc) for all
articles in a series.
## Installation
`yarn add gatsby-remark-series`
## Usage
In your gatsby-config.js file
```javascript
{
resolve: "gatsby-transformer-remark",
options: {
plugins: [
{
resolve: "gatsby-remark-series",
options: {
render: {
// The location where the toc should be rendered.
// Default: bottom
// Optional
placeholder: "both" | "top" | "bottom" | string,
// Provides a way to customize the output of the toc.
// Default: check utils/DefaultTemplate for details
// Optional
template: (templateContext) => string,
// Indicates a landing page is required.
// This will render the toc using template and will generate
// a landing page for the series with all articles listed.
// Default: false
// Optional
useLandingPage: boolean,
// This can only be used in conjunction with useLandingPage=true.
// Provides a way to specify a prefix for the slug of the series.
// This prefix is independent of the pathPrefix provided by gatsby.
// Default: null
// Optional
landingPagePathPrefix: string,
// This can only be used in conjunction with useLandingPage=true.
// Provides the path to the template layout (react component)
// to be used to render the external toc.
// This component receives the series articles in the pageContext.
// For more information please refer to examples/series.jsx
// Defaults: null
// Required!
landingPageComponent: string
},
resolvers: {
// Locates and resolves the slug on the node.
// Default: node.frontmatter.slug
// Returns: string
// Optional
slug: (markdownNode) => string,
// Locates and resolves the date on the node.
// Default: node.frontmatter.date
// Returns: string
// Optional
date: (markdownNode) => string,
// Locates and resolves the draft flag on the node.
// Indicates the post is a draft, default behavior is to show the title,
// but without a link to the post. This can be overridden with a new template.
// Default: node.frontmatter.draft
// Returns: boolean
// Optional
draft: (markdownNode) => boolean,
// Locates and resolves the order on the node.
// Indicates the position of the post in the series.
// Default: node.frontmatter.order
// Returns: number
// Optional
order: (markdownNode) => number,
// Locates and resolves the name of the series on the node.
// Default: node.frontmatter.series
// Returns: string
// Optional
series: (markdownNode) => string,
// Takes a string and converts it to a slug representation.
// This is used to calculate the path for the external landing page.
// In theory, should match the algorithm you are using to generate
// your urls.
// Default: converts the string to kebab-case using lodash.kebabCase.
toSlug: (markdownNode) => string
}
}
}
]
}
}
```
In your markdown files
```markdown
---
title: **article title**
series: **series name**
order: **number**
draft: **true | false**
---
```
Notes:
1. **series** is required to identify the articles.
2. **order** and **draft** are optional, just in case you want to reorder things
or make people aware there are more articles coming.
3. A `` is only required when the `render.placeholder` setting
has a value other than both, top or bottom. In those case, the placeholder has to
be expressed as a comment in the code using ``.
## Examples
Given the following configuration
```javascript
{
resolve: "gatsby-transformer-remark",
options: {
plugins: [
{
resolve: "gatsby-remark-series",
render: {
placeholder: "toc"
}
}
]
}
}
```
Will turn this
```markdown
---
title: My Title
series: CSS and HTML tricks
---
# My Title
Content
```
Into this (approximately)
```html
My Title
Content
```
## Notes
1. The plugin does not provide any default styling for the toc.
2. The plugin does not provide a default layout for series landing pages, but
it provides a concrete example in examples/series.jsx
## License
MIT, by Patricio Trevino