Notion Markdown CMS

Build markdown-based static sites with Notion.

1. Use Notion to write and organize pages
2. notion-markdown-cms sync to build a markdown repository
3. run your favourite static site generator (VuePress, Docusaurus, Gatsby, ...)

Success! 🚀

Features

• uses the official Notion API only
• written in typescript/javascript
• renders page properties to frontmatter
• recursively traverses the Notion Block graph to include database pages, child pages
• renders an index file of all your pages so you can easily build Navs/Sidebars

Supported Blocks

The following Notion API block object types are supported:

Support for other block types can be considered once they are available on the official Notion API.

Supported Rich Text Formatting

The following Notion API rich text types are supported

The following annotations (and any combination thereof) are supported:

Supported Page Property Types

The following Notion API page property types are supported

Usage

At the moment notion-markdown-cms is meant to be consumed via its node.js API from build scripts wrapping your favourite static site generator tool. You can install it from npm

npm add "@meshcloud/notion-markdown-cms"

You can find an example build script using the node.js API below. Consult the SyncConfig reference for documentation of available configuration options.

A CLI tool could be made available later.

import { SyncConfig, sync } from "notion-markdown-cms";

const config: SyncConfig = {
  cmsDatabaseId: "8f1de8c578fb4590ad6fbb0dbe283338",
  outDir: "docs/",
  indexPath: "docs/.vuepress/index.ts",
  databases: {
    "fe9836a9-6557-4f17-8adb-a93d2584f35f": {
      parentCategory: "cfmm/",
      sorts: [
        {
          property: "Scope",
          direction: "ascending",
        },
        {
          property: "Cluster",
          direction: "ascending",
        },
      ],
      properties: {
        category: "scope",
        include: ["Name", "Scope", "Cluster", "Journey Stage", "Summary"],
      },
    },
  },
};

async function main() {
  const notionApiToken = process.env.NOTION_API_TOKEN;
  if (!notionApiToken) {
    throw new Error(
      "Required NOTION_API_TOKEN environment variable not provided."
    );
  }

  await sync(notionApiToken, config);
}

main();

Credits, Related Projects and Inspiration

There are quite a few alternatives out there already, so why did we build notion-markdown-cms? Below table, albeit subjective, tries to answer this.

Development

For convenient development you can use

• nix-shell to set up a development environemnt
• You'll need a Notion database for testing. You can e.g. copy one of these to your own Notion Workspace
  • Notion Kit Test Suite
  • Narkdown's Test Suite
• A Notion API Token

As this project is still in its very early stages, notion-markdown-cms does not come with its own demo, example or test cases yet.