gatsby-transformer-katex

Description

The gatsby-transformer-katex plugin will process any specified text node with the Katex math typsetting library. This plugin renders any LaTeX enclosed between $ signs in “inline mode”. It is an alternative to the gatsby-remark-katex plugin since gatsby-remark-katex can process math found only in markdown, whereas gatsby-transformer-katex can process math from any source.

Dependencies

• katex
• camel-case To create the new field name that will appear in GraphiQL.
• lodash To interpret the “dot notation” path to the GraphQL text node.

How to install

npm install gatsby-transformer-katex

How to use

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-katex`,
      options: {
        process: [
          {
            type: `node__article`,
            fields: [
              `body.processed`,
              { field_with_array_of_objects: "processed" },
            ],
          },
        ],
      },
    },
  ],
};

Inspect the GraphiQL output to identify the text node that you wish to process with Katex. Consider data that could be queried with the following:

query MyQuery {
  nodeArticle {
    internal {
      type
    }
    body {
      processed
    }
    field_with_array_of_objects {
      processed
    }
  }
}

Which outputs the following:

{
  "data": {
    "nodeArticle": {
      "internal": {
        "type": "node__article"
      },
      "body": {
        "processed": "<p>Some text... then some math! $e^{i \pi} = -1$</p>\n"
      }
      field_with_array_of_objects [
        {
          rawValue: "some more text",
          processed: "some more text"
        }
      ]
    }
  },
  "extensions": {}
}

The type key in the gatsby-transformer-katex configuration is the value of the internal type of the graphQL node. In this example it is node__article. Each item in the fields array is a dot notation path to the field starting within the data node, or, if the field contains an array of objects, then the item in the fields array is an object where the key is the dot notation path to the field and the value is the property of the object that’s within the array. In this example the field is body.processed. The field can be arbitrarily nested with more dots. This example was created using the gatsby-source-drupal source plugin, but any source plugin that assigns an “internal.type” can be used.

To use the Katex processed version of body.processed, adjust the GraphQL query as follows:

query MyQuery {
  nodeArticle {
    fields {
      bodyProcessedKatex
      fieldWithArrayOfObjects
    }
  }
}

The plugin created an item within fields named with the camel case version of the dot notation path to the processed field, with Katex appended.

How to contribute

Please submit pull requests to the GitHub repository.

Tips

• Dollar signs $ can be escaped with a \ in order to be ignored by Katex. If you wish to have a $ literally appear in your text, write it as \$.
• Pay attention to the objects/arrays in the configuration. process expects an array of objects. Each object has a type and fields key. fields expects an array of dot notation paths to the fields of interest.
• There is no need to include internal { type } in your graphQL queries. That was shown above just to illustrate the value needed for the type key in the configuration.

Known limitations

• “display mode” isn’t supported. Math is always rendered in “inline” mode.
• Other delimiters are not supported. Only $ signs will work.