@yozora/gatsby-transformer NPM

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 in gatsby-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 and sourceline 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 the solution.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 lines 2-8 and 10), these lines will be concat and used as the value of the Code node.