Gatsby is joining Netlify: Read the announcement post

ContactSign Up for Free
Community Plugin
View plugin on GitHub


Uses leasot to parse select source files for TODO:, FIXME: and custom comments. Written in Typescript.


// FIXME(Reference): improve example
// TODO: you can add a reference like this as well /Reference
// TODO: example without reference
const comeBackToImprove = () => console.log('Please improve me')

will be transformed to

  "todo": {
    "ref": "Reference",
    "line": 7,
    "value": "improve example",
    "file": {
      "relativePath": ""

file will be a File reference, so you can query anything gatsby-source-filesystem provides

Live Example


yarn add -D gatsby-transformer-leasot
# or
npm i -D gatsby-transformer-leasot

REQUIRES: gatsby-source-filesystem
You can use gatsby-theme-leasot for convenience.
Alternatively, since v1.2.0, you can bring your own source plugin and set the internalType accordingly.


  resolve: `gatsby-source-filesystem`,
  options: {
    path: __dirname,
    // has to match `sourceInstanceName` field in gatsby-transformer-leasot
    name: `leasot`,
    ignore: [
      // can be customized, it's just what works for me at the moment

// without options

// with options
  resolve: `gatsby-transformer-leasot`,
  options: {
    sourceInstanceName: `leasot`,
    // parse `NOTE:` in addition to `TODO:` & `FIXME:`
    customTags: [`NOTE`],
    mode: 'mdx',

For mdx to work you have to wrap the value in MDXRenderer provided by gatsby-plugin-mdx


  sort: { fields: [todo___modifiedTime], order: DESC }
) {
  group(field: todo___tag) {
    nodes {
      todo {
        modifiedTime(formatString: "YYYY-MM-DD H:mm")
        file {

Note: The name allLeasot depends on the provided sourceInstanceName in the configs. So when you change it you have to change the name option of gatsby-source-filesystem accordingly, lets say todo then you query for allTodo or todo if you just want a single one.

All config options

name type default description
sourceInstanceName string “leasot” Has to match the name prop of gatsby-source-filesystem.
customTags array [] Other tags to look for (besides todos and fixmes). Tags are case-insensitive and are strict matching, i.e PROD tag will match PROD but not PRODUCTS. More in Leasot’s Docs
mode string “text” Supports one of: text, mdx, html.
truncateLinks int|object {length: 32,style: “smart”} Provide int to change the length only. style can be one of: smart, middle, end.
associateParser object {} Associate the filetypes with parsers. This allows adding support for new filetypes. More in Leasot’s Docs
customParsers object {} Extend the parsers by parserName, for example override the defaultParser or add a new parser. Leasot’s Docs
(since v1.2.0)
string “File” Has to match node.internal.type

modifiedTime works only locally as file time will be the same on CI

A table showing the Supported Languages & the comment format spec by Leasot in their readme.

Provides its own Schema

That means if your sourced files don’t contain anything for gatsby-transformer-leasot to parse it won’t crash as Gatsby will be prepared. Also congratulations for finishing off all notes, fixmes & todos 🥳


  • v1.1.0 - add he to entity encode the comments




© 2023 Gatsby, Inc.