@yozora/gatsby-transformer
A gatsby plugin for transforming markdown files to markdown ast through Yozora Parser, Inspired by gatsby-transformer-remark.
Install
This plugin depends on Yozora Parser, as of now, you can choose @yozora/parser (Recommend) or @yozora/parser-gfm or @yozora/parser-gfm-ex.
-
npm
npm install @yozora/gatsby-transformer @yozora/parser --save-dev
-
yarn
yarn add @yozora/gatsby-transformer @yozora/parser --dev
Usage
Add configs in gatsby-config.mjs
:
// gatsby-config.mjs
import { YozoraParser } = from '@yozora/parser'
module.exports = {
plugins: [
{
resolve: '@yozora/gatsby-transformer',
options: {
parser: new YozoraParser(),
preferFootnoteReferences: true,
frontmatter: {
excerpt_separator: '<!-- more -->',
}
}
}
]
}
Options
Name | Required | Default |
---|---|---|
parser |
true |
- |
preferFootnoteReferences |
false |
false |
presetDefinitions |
false |
- |
presetFootnoteDefinitions |
false |
- |
headingIdentifierPrefix |
false |
heading- |
footnoteIdentifierPrefix |
false |
footnote- |
shouldStripChineseChars |
false |
false |
wordsPerMinute |
false |
80 |
frontmatter |
false |
- |
plugins |
false |
- |
-
parser
: A yozora parser. -
preferFootnoteReferences
: Replace footnotes into footnote references and footnote reference definitions. -
presetDefinitions
: Preset link reference definitions. -
presetFootnoteDefinitions
: Preset footnote reference definitions. -
headingIdentifierPrefix
: The identifier prefix of the headings that constitutes the toc (Table of Content). -
footnoteIdentifierPrefix
: The identifier prefix of the footnote references and footnote reference definitions. -
shouldStripChineseChars
: Whether to remove line end between two chinese characters. -
wordsPerMinute
: The number of words read per minute. -
frontmatter
: Options for gray-matter. -
plugins
: Plugins of @yozora/gatsby-transformer, similar with the plugins option of gatsby-transformer-remark./** * Api passed to the options.plugins */ export interface AstMutateApi { files: Node[] markdownNode: Node markdownAST: Root pathPrefix: string getNode(id: string): Node reporter: Reporter cache: GatsbyCache } function plugin(api: AstMutateApi, pluginOptions: any): void
-
api
: passed by @yozora/gatsby-transformer -
pluginOptions
: defined ingatsby-config.js
, such as the highlighted line in the following code (line eight)const presetDefinitions = [] const presetFootnoteDefinitions = [] { resolve: '@yozora/gatsby-transformer', options: { parser: new YozoraParser({ defaultParseOptions: { shouldReservePosition: false, presetDefinitions, presetFootnoteDefinitions, }, }), presetDefinitions, presetFootnoteDefinitions, preferFootnoteReferences: true, shouldStripChineseCharacters: true, frontmatter: { excerpt_separator: '<!-- more -->', }, plugins: [ { resolve: '@yozora/gatsby-images', options: {}, // this is the pluginOptions. }, ], }, }
-
Features
-
Code (Yozora Code node) support
sourcefile
andsourceline
meta options, for example:```cpp sourcefile="./solution.cpp" sourceline="2-8" ```
In the above code,
sourcefile
specifies the source file location, then@yozora/gatsby-transformer
will read thesolution.cpp
under that directory where the current markdown file is located. If this file (solution.cpp
) exists, it will read the contents of the file.sourceline
specifies which lines will be intercepted (in the above example, intercept lines2-8
and10
), these lines will be concat and used as the value of the Code node.
FAQ
-
How to deal with images referenced in markdown files, like gatsby-remark-images does?