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:

| Block Type | Supported | Notes | | ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | | Paragraph | ✅ Yes | | | Heading1-3 | ✅ Yes | | | Callout | ✅ Yes | | | Quote | ✅ Yes | | | Bulleted List | ✅ Yes | | | Numbered List | ✅ Yes | | | To do | ✅ Yes | | | Toggle | ✅ (Yes) | Toggle content is included, however the toggle header is not | | Code | ✅ Yes | An html block starting with <!--notion-markdown-cms:raw--> is rendered as raw HTML and not as a fenced block | | Child Pages | ❌ not planned | avoid, they don't mix well with clear site navigation | | Child Databases | ✅ Yes | renders as table + including child pages, inline-only tables planned | | Embed | ❌ Missing | unclear, might be undesireable for static sites | | Image | ✅ (Yes) | captions not supported yet | | Video | ❌ Missing | | | File | ❌ Missing | | | PDF | ❌ Missing | | | Bookmark | ✅ Yes | use a caption as a link name | | | Equation | ❌ Missing | | | Divider | ✅ Yes | | | Table Of Contents | ❌ not planned | static site generators have their own ToC implementations | | Breadcrumb | ❌ not planned | static site generators have their own nav implementations | | Synced Block | ✅ Yes | renders all children blocks |

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

| Rich Text Type | Supported | Notes | | -------------- | ----------- | ------------------------------------------------ | | Text | ✅ Yes | | | Mention | ✅ partially | Page mentions only, mentioned pages are included | | Equation | ❌ Missing | |

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

| Annotation | Supported | Notes | | ------------- | ------------- | ------------------------- | | bold | ✅ Yes | | | italic | ✅ Yes | | | strikethrough | ✅ Yes | | | underline | ✅ Yes | | | code | ✅ Yes | | | color | ❌ not planned | not available in markdown |

Supported Page Property Types

The following Notion API page property types are supported

| Propety type | Supported | Notes | | ---------------- | --------- | ----------------------------- | | Rich text | ✅ Yes | rendered as plaintext string | | Number | ✅ Yes | | | Select | ✅ Yes | rendered as name | | Multi Select | ✅ Yes | rendered as array of names | | Date | ✅ Yes | rendered as string | | Formula | ❌ missing | | | Relation | ✅ Yes | rendered as array of page ids | | Rollup | ❌ missing | | | Title | ✅ Yes | used as page title | | People | ❌ missing | | | Files | ❌ missing | | | Checkbox | ❌ missing | | | Url | ✅ Yes | rendered as string | | Email | ✅ Yes | rendered as string | | Phone Number | ✅ Yes | rendered as string | | Created time | ✅ Yes | rendered as string | | Created by | ✅ Yes | rendered as name | | Last edited time | ✅ Yes | rendered as string | | Last edited by | ✅ Yes | rendered as name |

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 { slugify, SyncConfig, sync } from "notion-markdown-cms";
const config: SyncConfig = {
  cmsDatabaseId: "8f1de8c578fb4590ad6fbb0dbe283338",
  pages: {
    destinationDirBuilder: (page) => slugify(page.properties.get("Category")),
    frontmatterBuilder: (page) => ({
      id: page.meta.id,
      url: page.meta.url,
      title: page.meta.title,
      category: page.properties.get("Category")
    }),
  },
  databases: {
    "fe9836a9-6557-4f17-8adb-a93d2584f35f": {
      sorts: [
        {
          property: "Scope",
          direction: "ascending",
        },
        {
          property: "Cluster",
          direction: "ascending",
        },
      ],
      renderAs: "pages+views",
      pages: {
        destinationDirBuilder: (page) => slugify(page.properties.get("Scope")),
        frontmatterBuilder: (page) => ({
          id: page.meta.id,
          url: page.meta.url,
          title: page.meta.title,
          cluster: page.properties.get("Cluster")
        }),
      },
      views: [
      {
        title: "By Scope",
        properties: {
          groupBy: "Scope",
          include: ["Name", "Scope", "Cluster", "Summary"],
        },
      },
    },
  },
};

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

  rimraf.sync("docs/!(README.md)**/*");

  // change into the docs dir, this simplifies handling relative paths
  process.chdir("docs/");

  const rendered = await sync(notionApiToken, config);

  // do something with the rendered index, e.g. writing it to a file or building a nav structure
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

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.

| Project | Notion API | Language | Rendering Engine | Output looks like | | ------------------------------------------------------------------------ | ------------ | ---------- | ------------------- | -------------------- | | Nortion Markdown CMS | ✅ official | TypeScript | Markdown + JS Index | Site generator theme | | Notion2GitHub | ⚠️ unofficial | Python | Markdown | Site generator theme | | notion-cms | ⚠️ unofficial | TypeScript | React | Notion App | | vue-notion | ⚠️ unofficial | JavaScript | Vue.js | Notion App | | react-notion | ⚠️ unofficial | JavaScript | React | Notion App |

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.