@stebrech/notion2eleventy

v0.3.0

Published

5 months ago

Eleventy plugin which downloads data from Notion to your 11ty project.

0High
0Medium
0Low

stebrech

11ty eleventy eleventy-plugin Notion markdown

notion2eleventy

notion2eleventy is an Eleventy plugin which downloads content from Notion depending on a defined status. It fetches the content via Notions’s API and the the node package @notionhq/client. The content will be converted to md with the help of the lovely node package notion-to-md.

[!IMPORTANT] Breaking changes in v0.3.0:
Eleventy v3 is required. The plugin now uses the newer JavaScript standard ESM (ECMAScript Modules).
The new Notion API version 2025-09-03 is used and requires a data_source_id. However, if you not provide the id, the first one of the database will be used.

🚀 Features

Downloads Notion content and assets to your Eleventy project.
Status driven workflow:
- It fetches only posts in a specific status you‘ll define.
- At the end it updates the status.
The assets will be downloaded to the directory of choice and renamed.
The notion properties can be setup and added to the Markdown frontmatter (written in camel case).
Multiple databases can be used and allows to create different post types.
The cover image in Notion will be copied to the frontmatter by default.

[!NOTE] As from v0.2.0 you need to configure notion2eleventy via the standard eleventy.config.js.

Install the npm package

npm install @stebrech/notion2eleventy

Configure the plugin

Environment variables

Add a .env file to the root folder and add the following variables:

NOTION_KEY=
CHECKSTATUS=
CHECKSTATUS2=
UPDATESTATUS=
NOTION_DB_POSTS=

Add your API Key you created on www.notion.so/my-integrations.
The name of the status value to take into account. Posts with other status will not be downloaded.
Maybe you need another status to check. If not just use the same name as CHECKSTATUS.
Which status should the posts get after downloading it.
The ID of the Notion database, see Retrieve a database

Configure the plugin in `eleventy.config.js`

The minimal configuration within the eleventy.config.js (or .eleventy.js) file looks like this:

ESM

import notion2eleventy from "@stebrech/notion2eleventy";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(notion2eleventy);
}

CommonJS

module.exports = async (eleventyConfig) => {
  const { default: notion2eleventy } = await import("@stebrech/notion2eleventy");
  eleventyConfig.addPlugin(notion2eleventy);
};

Overwrite defaults

The example above uses the default values. To customize it you need to write them within an object (curly brackets).

Example:

import notion2eleventy from "@stebrech/notion2eleventy";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(notion2eleventy, {
    dbId: process.env.NOTION_DB_BLOG,
    dsId: process.env.NOTION_BLOG_DATASOURCE,
    postType: "blog",
    requiredMetadata: {
      statusFieldType: "select",
    },
    optionalMetadata: {
      textFields: ["Description"],
      multiSelectFields: ["Tags"],
    },
    permalink: {
      includesYear: true,
      includesMonth: true,
      publishPermalink: true,
    },
    downloadPaths: {
      md: "src/blog/",
      mdAddDatePrefix: false,
    },
    markdownPaths: {
      img: "src/assets/img/",
    },
  });
};

All Config Options

Required Notion metadata (database properties)

// Defaults
requiredMetadata: {
  status: "Status",
  statusFieldType: "status",
  title: "Name",
},

Optional Notion metadata (database properties)

// Defaults
optionalMetadata: {
  layout: "",
  date: "",
  textFields: [],
  multiSelectFields: [],
  selectFields: [],
  dateFields: [],
  checkboxFields: [],
  urlFields: [],
  numberFields: [],
  personFields: [],
  relationFields: [],
  formulaStringFields: [],
  formulaNumberFields: [],
},

Permalink settings

// Defaults
permalink: {
  addPermalink: true,
  includesPostType: true,
  includesYear: false,
  includesMonth: false,
  includesDay: false,
  slug: "",
  publishPermalink: false,
}

Download paths

// Defaults
downloadPaths: {
  md: "src/posts/",
  mdAddDatePrefix: false,
  img: "src/assets/img/",
  imgAddDatePrefix: false,
  movie: "src/assets/movie/",
  movieAddDatePrefix: false,
  pdf: "src/assets/pdf/",
  pdfAddDatePrefix: false,
}

Markdown paths

// Defaults
markdownPaths: {
  img: "/assets/img/",
  movie: "/assets/movie/",
  pdf: "/assets/pdf/",
}

Copy assets to output directory

// Defaults
copyAssetsToOutputFolder: {
  img: true,
  movie: true,
  pdf: true,
}

Use multiple Notion databases

For creating multiple post types in Eleventy, you can create multiple Notion databases. Therefore you’ll call the plugin multiple times in your eleventy.config.js.

Example:

const notion2eleventy = require("@stebrech/notion2eleventy");

module.exports = function (eleventyConfig) {
  // Posts
  eleventyConfig.addPlugin(notion2eleventy, {
    requiredMetadata: {
      title: "Title",
    }
  });

  // Pages
  eleventyConfig.addPlugin(notion2eleventy, {
    dbId: process.env.NOTION_DB_PAGES,
    postType: "pages",
    requiredMetadata: {
      title: "Title",
    },
    optionalMetadata: {
      textFields: ["Description"],
    },
    downloadPaths: {
      md: "src/pages/",
    }
  });
}

Extend scripts

~~Add the node script in your package.json like:~~

[!NOTE] This is no longer necessary as of version v0.2.0

Feedback / Contribution

Please give me feedback dropping me a mail or reach out to me on the Mastodon.

If you find a bug or want to send a feature request please raise an issue on Github. You have a concrete solution – even better. I’m happy to receive your pull request on a separate branch.