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.

FAQ

• How to deal with images referenced in markdown files, like gatsby-remark-images does?

  See @yozora/gatsby-images.

Related

• @yozora/gatsby-images
• @yozora/ast
• @yozora/parser
• @yozora/parser-gfm
• @yozora/parser-gfm-ex
• gatsby-transformer-remark
• gray-matter