Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
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": "README.md"

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.