Add API docs for `eleventyConfig` object passed into `.eleventy.js`

[e111077]

Hello!

I often have issues with discoverability of eleventy's features because I simply don't know what is available to me. Often I figure that the thing that I need is in eleventyConfig, but since this is not a TS project, I don't know how to nicely discover what is inside the eleventyConfig object and don't know what to google for in the docs.

I think it would be helpful to have the API of eleventyConfig in the docs with (optional) links to the relevant expanded docs for the APIs.

[pdehaan]

@e111077 Curious if there is something specifically you weren't finding in the docs. I usually just scan https://www.11ty.dev/docs/config/, but agree that it can be difficult to search for things you don't know the names of.

Regardless, we have had a few requests for type definition files in the issues before, let me see if I can dig up a list of links (and shout out to @Ryuno-Ki and @chriskrycho who are our resident type file experts):

• Add JSDoc Comments for Config and TemplateConfig. Adjust references #720
• Provide API docs and specify public API #814
• Include TypeScript types for configuration files #1459
• Explain how to use JSDoc with 11ty config file #2033
• feat: declare "types" in package.json to make consuming types easier #2091

[e111077]

Specifically, I am in a plugin context and I want to see if it's possible to access the page's frontmatter data. In this context I only have the filename, the text, and eleventyConfig. I know it's not in the first two, but I don't have any idea if it's in the last scope that is available to me.

Going to the data section in the docs doesn't mention plugins and the plugins section of the docs don't mention data. From here I'm having doubts that it's possible, but I'd know for sure if I could just explore the eleventyConfig object which console.log(eleventyConfig) does not seem to print out all the methods and properties available to it and the project i'm working on has such a complex build that it's very difficult to run a vscode node debugger only on the 11ty portion of the build.

[pdehaan]

I don't know that LiquidJS has access to front-matter, but it looks like Nunjucks might…
At least per my quick test. Here's my ./plugins/foo.js file:

// ./plugins/foo.js
const { inspect } = require("node:util");

module.exports = (eleventyConfig, pluginConfig = {}) => {
  eleventyConfig.addShortcode("inspect", function (name) {
    const _this = { ...this };
    // I had to delete the `this.ctx.collections` object since it was causing some
    // infinite loop errors when trying to JSON stringify it (although `util.inspect()`
    // probably could have handled it).
    delete _this.ctx?.collections;

    const data = { name, pluginConfig, this: _this };

    return inspect(data, { sorted: true, depth: 5 });
    // return JSON.stringify(data, null, 2);
  });
};

const fooPlugin = require("./plugins/foo");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(fooPlugin, { name: "MyFooPluginValue" });

  return {
    dir: {
      input: "src",
      output: "www",
    },
  };
};

My ./src/nunjucks.njk and ./src/liquid.liquid templates look like this:

---
title: nunjucks
matter: front
---

{% inspect title %}
{% inspect %}

The generated ./www/liquid/index.html file looks like this (there are 2 JSON objects since one has a name attribute and the second one didn't):

// ./www/liquid/index.html
{
  name: 'liquidjs',
  pluginConfig: { name: 'MyFooPluginValue' },
  this: {
    page: {
      date: 2022-04-11T20:57:11.291Z,
      filePathStem: '/liquid',
      fileSlug: 'liquid',
      inputPath: './src/liquid.liquid',
      outputFileExtension: 'html',
      outputPath: 'www/liquid/index.html',
      url: '/liquid/'
    }
  }
}

{
  name: undefined,
  pluginConfig: { name: 'MyFooPluginValue' },
  this: {
    page: {
      date: 2022-04-11T20:57:11.291Z,
      filePathStem: '/liquid',
      fileSlug: 'liquid',
      inputPath: './src/liquid.liquid',
      outputFileExtension: 'html',
      outputPath: 'www/liquid/index.html',
      url: '/liquid/'
    }
  }
}

Now, the ./src/nunjucks.njk has an extra ctx object which includes a bunch of extra context info on the current page (at least in our short code example).

// ./www/nunjucks/index.html
{
  name: 'nunjucks',
  pluginConfig: { name: 'MyFooPluginValue' },
  this: {
    ctx: {
      eleventy: {
        env: {
          config: '/private/tmp/11ty-plugin-context/.eleventy.js',
          root: '/private/tmp/11ty-plugin-context',
          source: 'cli'
        }
      },
      matter: 'front',
      page: {
        date: 2022-04-11T20:57:11.291Z,
        filePathStem: '/nunjucks',
        fileSlug: 'nunjucks',
        inputPath: './src/nunjucks.njk',
        outputFileExtension: 'html',
        outputPath: 'www/nunjucks/index.html',
        url: '/nunjucks/'
      },
      pkg: {
        author: 'Peter deHaan <peter@deseloper.com>',
        description: '',
        devDependencies: { '@11ty/eleventy': '^1.0.0' },
        keywords: [],
        license: 'MPL-2.0',
        main: '.eleventy.js',
        name: '11ty-plugin-context',
        scripts: {
          build: 'eleventy',
          test: 'echo "Error: no test specified" && exit 1'
        },
        version: '1.0.0'
      },
      title: 'nunjucks'
    },
    page: {
      date: 2022-04-11T20:57:11.291Z,
      filePathStem: '/nunjucks',
      fileSlug: 'nunjucks',
      inputPath: './src/nunjucks.njk',
      outputFileExtension: 'html',
      outputPath: 'www/nunjucks/index.html',
      url: '/nunjucks/'
    }
  }
}

{
  name: '',
  pluginConfig: { name: 'MyFooPluginValue' },
  this: {
    ctx: {
      eleventy: {
        env: {
          config: '/private/tmp/11ty-plugin-context/.eleventy.js',
          root: '/private/tmp/11ty-plugin-context',
          source: 'cli'
        }
      },
      matter: 'front',
      page: {
        date: 2022-04-11T20:57:11.291Z,
        filePathStem: '/nunjucks',
        fileSlug: 'nunjucks',
        inputPath: './src/nunjucks.njk',
        outputFileExtension: 'html',
        outputPath: 'www/nunjucks/index.html',
        url: '/nunjucks/'
      },
      pkg: {
        author: 'Peter deHaan <peter@deseloper.com>',
        description: '',
        devDependencies: { '@11ty/eleventy': '^1.0.0' },
        keywords: [],
        license: 'MPL-2.0',
        main: '.eleventy.js',
        name: '11ty-plugin-context',
        scripts: {
          build: 'eleventy',
          test: 'echo "Error: no test specified" && exit 1'
        },
        version: '1.0.0'
      },
      title: 'nunjucks'
    },
    page: {
      date: 2022-04-11T20:57:11.291Z,
      filePathStem: '/nunjucks',
      fileSlug: 'nunjucks',
      inputPath: './src/nunjucks.njk',
      outputFileExtension: 'html',
      outputPath: 'www/nunjucks/index.html',
      url: '/nunjucks/'
    }
  }
}

So I don't think a plugin itself has knowledge of the current page's context or front matter, there might be a workaround for Nunjucks templates by inspecting the ctx and/or looking at the various this.ctx.collections object.

It might be different for filters and transforms and other stuff.

Otherwise, if you want your plugin to be front matter aware, you probably need to pass the front matter data to your filter/shortcode.

[zachleat]

Related: a very first PR for types will ship with 2.0.0-canary.19 #2091

[e111077]

Yes @zachleat, famed Typescript super-stan 😆

[zachleat]

now I am typecast too!! 😇