4 |
5 |
2 |
3 |
4 |
5 |
with the simplicity of Ghost's Content API.
11 | 12 |
13 |
14 | 
18 |
19 |
20 | 
30 | docs | 31 | quickstart 32 |
33 | 34 | ## Features 35 | 36 | 🏗️ Framework agnostic - it’s just JS. 37 | 🌲 Build a collection-based CMS tree from your Notion database. 38 | 🎚️ Leverage database structure to control your routing structure. 39 | ⚙️ Geared for Static Site Generation. 40 | 📑 Transform Notion blocks → Markdown, plaintext, and (customizable) html. 41 | 🗃️ Optimized Content Caching for super fast builds. 42 | 🧩 Plugin ready with some powerful core plugins on the way. 43 | 🦾 Tagging, filtering, path queries, and tree-walking utilities. 44 | ⌨️ Totally Typesafe. 45 | 46 | ## Install 47 | 48 | ``` npm install @agency-kit/notion-cms ``` 49 | ```pnpm add @agency-kit/notion-cms``` 50 | ```yarn add @agency-kit/notion-cms``` 51 | 52 | ## Why. 53 | 54 | Notion excels at managing content. It also has a great API and SDK. But why is it so challenging to _actually_ leverage Notion as a CMS (Content Management System) in production? 55 | 56 | Until recently there wasn't support for sub-pages (sub-items in a database) in Notion. So most existing Notion-as-a-cms solutions don't provide a way to leverage this new feature, which turns out to be crucial for building a collection-based CMS. Another barrier is that pulling content from Notion can be time consuming. Responses can take a few seconds at times, the API provides a lot of data to sift through, and multiple calls to different endpoints are required in order to go from CMS database to the content for each page. All of this together results in a less than excellent developer experience when using a static site generator that often makes requests on each build. 57 | 58 | NotionCMS exists to address each of these issues and provide an excellent developer experience while using Notion as your Content Management System. 59 | 60 | ## The Database Structure 61 | 62 | In order to make use of NotionCMS, you have to subscribe to a specific database structure. Its an extremely generic design that gives you all the things you need for basic sites but lends flexibility for types of content other than the standard web page, blog post etc. 63 | 64 | See the structure in this template [this template](https://cooked-shovel-3c3.notion.site/NotionCMS-Quickstart-Database-Template-719f1f9d1547465d96bcd7e80333c831?pvs=4). 65 | 66 | ## Basic Usage 67 | 68 | ```javascript 69 | 70 | // initialize 71 | const myCoolCMS = new NotionCMS({ 72 | databaseId: 'e4fcd5b3-1d6a-4afd-b951-10d56ce436ad', 73 | notionAPIKey: process.env.NOTION, 74 | // Other options 75 | }) 76 | 77 | // Pull down all Notion content 78 | await myCoolCMS.pull() 79 | 80 | // Access the routes here: 81 | console.log(myCoolCMS.routes) 82 | 83 | // Access the page content here: 84 | console.log(myCoolCMS.data) 85 | 86 | // Access paths like this: 87 | const postA = myCoolCMS.data['/posts']['/how-to-build-a-blog-with-notion'] 88 | const postB = myCoolCMS.data['/posts']['/how-to-use-notion-cms'] 89 | 90 | ``` 91 | 92 | ## Advanced Usage 93 | 94 | ```javascript 95 | 96 | const customPlugin = () => { 97 | return { 98 | name: 'my-custom-plugin', 99 | hook: 'pre-parse', // other option is 'post-parse' 100 | // list of blocks to transform. 101 | // If hook is post parse, its the string of html parsed from blocks 102 | exec: (blocksOrHtml) => { 103 | // do some transformations, 104 | const transformedBlocksOrHtml = someXform(blocksOrHtml) 105 | return transformedBlocksOrHtml 106 | } 107 | } 108 | } 109 | 110 | const myAdvancedCMS = new NotionCMS({ 111 | databaseId: 'e4fcd5b3-1d6a-4afd-b951-10d56ce436ad', 112 | notionAPIKey: process.env.NOTION, 113 | rootUrl: 'https://mycoolsite.com', 114 | localCacheDirectory: `${process.cwd()}/localcache/`, 115 | refreshTimeout: '1 hour', 116 | plugins: [customPlugin()], 117 | }) 118 | 119 | await myAdvancedCMS.pull() 120 | 121 | ``` 122 | 123 | See the full [API reference](https://www.agencykit.so/notion-cms/guide/api/). 124 | 125 | ## Some Helper methods 126 | 127 | ```javascript 128 | // returns page reference 129 | myCMS.queryByPath('/full/path/to/page') 130 | 131 | // returns an array of only child pages of a page looked up using the key. 132 | // This runs queryByPath under the hood so you can save a step 133 | myCMS.filterSubPages('/full/path/to/page' /* or Page reference*/) 134 | 135 | // returns page object without any children - just the content. Useful for serializing and sending a 136 | // single pages data to the client. 137 | myCoolCMS.rejectSubPages('/full/path/to/page' /* or Page reference*/) 138 | 139 | // Get tagged collections this way or by passing a single tag: 140 | const tagged = myCoolCMS.getTaggedCollection(['blog', 'programming']) 141 | 142 | // walk the CMS from the root node and perform some operation for each node. 143 | // the node parameter will be of type PageContent so you have access to all of the page data 144 | myCoolCMS.walk(node => console.log(node), '/partial/path/to/start') 145 | 146 | // for async callbacks 147 | await myCoolCMS.asyncWalk(async node => await asynchronousFunc()) 148 | ``` 149 | 150 | ## Project Stats 151 | 152 |  153 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@agency-kit/notion-cms", 3 | "type": "module", 4 | "version": "0.10.0", 5 | "description": "NotionCMS. Turn Notion into a full-fledged headless CMS (content management system).", 6 | "author": "Jacob Milhorn", 7 | "license": "MIT", 8 | "homepage": "https://www.agencykit.so/notion-cms/guide/", 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/agency-kit/notion-cms.git" 12 | }, 13 | "bugs": { 14 | "url": "https://github.com/agency-kit/notion-cms/issues" 15 | }, 16 | "keywords": [ 17 | "notion", 18 | "content", 19 | "content management", 20 | "cms", 21 | "notion-cms", 22 | "notion cms", 23 | "NotionCMS", 24 | "notion content management", 25 | "static site generation", 26 | "ssg", 27 | "ssr", 28 | "server side rendered", 29 | "server rendered", 30 | "node", 31 | "11ty", 32 | "eleventy", 33 | "headless cms", 34 | "headless content management system", 35 | "framework agnostic", 36 | "agnostic" 37 | ], 38 | "main": "./dist/index.js", 39 | "types": "./index.d.ts", 40 | "scripts": { 41 | "dev": "tsc --watch", 42 | "watch": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 chokidar \"src/**/*.ts\" -c \"rollup -c && tsc --project ./tsconfig.json && npx uvu test\"", 43 | "test:no-mock": "node test/notion-cms.spec.js true", 44 | "build": "rm -rf dist && tsc --project ./tsconfig.json && rollup -c", 45 | "build:dts": "rm -rf dist && tsc --project ./tsconfig.json && rollup -c && npm run dts", 46 | "dts": "dts-bundle-generator -o index.d.ts src/index.ts --no-check && rm -rf .tmp", 47 | "test": "uvu test", 48 | "build:test": "npm run build:dts && c8 npm test", 49 | "lint": "eslint .", 50 | "lint:fix": "eslint . --fix", 51 | "release": "changeset publish" 52 | }, 53 | "dependencies": { 54 | "@clack/prompts": "^0.6.3", 55 | "@notionhq/client": "^2.2.3", 56 | "file-type": "^18.5.0", 57 | "flatted": "^3.2.7", 58 | "highlight.js": "^11.7.0", 59 | "human-interval": "^2.0.1", 60 | "lodash": "^4.17.21", 61 | "marked": "^5.0.2", 62 | "marked-gfm-heading-id": "^3.0.3", 63 | "nanoid": "^4.0.2", 64 | "notion-utils": "^6.16.0", 65 | "picocolors": "^1.0.0", 66 | "serialize-javascript": "^6.0.1", 67 | "sharp": "^0.32.4", 68 | "walkjs": "^4.0.5", 69 | "zod": "^3.21.4" 70 | }, 71 | "devDependencies": { 72 | "@antfu/eslint-config": "^0.38.6", 73 | "@changesets/cli": "^2.26.1", 74 | "@notion-stuff/v4-types": "^6.0.0", 75 | "@rollup/plugin-terser": "^0.4.0", 76 | "@types/lodash": "^4.14.191", 77 | "@types/marked": "^4.0.8", 78 | "@types/node": "^20.1.5", 79 | "@types/serialize-javascript": "^5.0.2", 80 | "bottleneck": "^2.19.5", 81 | "c8": "^7.13.0", 82 | "chokidar": "^3.5.3", 83 | "chokidar-cli": "^3.0.0", 84 | "dotenv": "^16.0.3", 85 | "dts-bundle-generator": "^8.0.0", 86 | "esbuild": "^0.17.11", 87 | "nock": "^13.3.0", 88 | "rollup": "^3.19.1", 89 | "rollup-plugin-esbuild": "^5.0.0", 90 | "simple-git-hooks": "^2.8.1", 91 | "terser": "^5.16.6", 92 | "tslib": "^2.5.0", 93 | "typescript": "^4.9.5", 94 | "uvu": "^0.5.6" 95 | }, 96 | "simple-git-hooks": { 97 | "pre-commit": "npx lint-staged" 98 | }, 99 | "lint-staged": { 100 | "*": "eslint --fix" 101 | } 102 | } 103 | -------------------------------------------------------------------------------- /public/subtle_gltch_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agency-kit/notion-cms/6a32a0fc3fbca5655cbe4716f26bc6fa7fa2ee5d/public/subtle_gltch_logo.png -------------------------------------------------------------------------------- /public/welcome_gltch_rounded.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agency-kit/notion-cms/6a32a0fc3fbca5655cbe4716f26bc6fa7fa2ee5d/public/welcome_gltch_rounded.png -------------------------------------------------------------------------------- /rollup.config.mjs: -------------------------------------------------------------------------------- 1 | import esbuild from 'rollup-plugin-esbuild' 2 | import terser from '@rollup/plugin-terser' 3 | 4 | export default [{ 5 | input: 'src/index.ts', 6 | plugins: [esbuild()], 7 | output: [ 8 | { format: 'esm', file: './dist/index.js' }, 9 | ], 10 | }, 11 | { 12 | input: 'src/index.ts', 13 | plugins: [esbuild({ sourceMap: true }), terser()], 14 | output: [ 15 | { format: 'esm', file: './dist/index.min.js', sourcemap: 'inline' }, 16 | ], 17 | }, 18 | { 19 | input: 'src/tests/test.ts', 20 | plugins: [esbuild()], 21 | output: [ 22 | { format: 'esm', file: './test/test.mjs' }, 23 | ], 24 | }] 25 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | export type { 2 | Properties, 3 | Options, 4 | CMS, 5 | Route, 6 | Page, 7 | PageObjectTitle, 8 | PageObjectRelation, 9 | PageObjectUser, 10 | PageMultiSelect, 11 | PageRichText, 12 | PageSelect, 13 | Cover, 14 | RouteObject, 15 | Plugin, 16 | PluginPassthrough, 17 | } from './types' 18 | 19 | export type { BlockRenderers } from './notion-blocks-parser' 20 | export { default as NotionBlocksParser } from './notion-blocks-parser' 21 | export { default } from './notion-cms' 22 | export { default as blocksRenderPlugin } from './plugins/render' 23 | export { default as Linker } from './plugins/linker' 24 | export { default as Images } from './plugins/images' 25 | export { default as Head } from './plugins/head' 26 | -------------------------------------------------------------------------------- /src/notion-blocks-html-parser.ts: -------------------------------------------------------------------------------- 1 | import type { Renderer as MarkedRenderer } from 'marked' 2 | import { marked } from 'marked' 3 | import hljs from 'highlight.js' 4 | import type { Blocks } from '@notion-stuff/v4-types' 5 | import _ from 'lodash' 6 | 7 | // @ts-expect-error module 8 | import { gfmHeadingId } from 'marked-gfm-heading-id' 9 | import type NotionBlocksMarkdownParser from './notion-blocks-md-parser' 10 | 11 | export default class NotionBlocksHtmlParser { 12 | markdownParser: NotionBlocksMarkdownParser 13 | renderer: MarkedRenderer 14 | markedOptions 15 | debug: boolean 16 | 17 | constructor(parser: NotionBlocksMarkdownParser, debug?: boolean) { 18 | this.markdownParser = parser 19 | this.debug = debug || false 20 | 21 | this.renderer = new marked.Renderer() 22 | this.renderer.code = this._highlight.bind(this) 23 | this.markedOptions = { 24 | renderer: this.renderer, 25 | pedantic: false, 26 | mangle: false, 27 | gfm: true, 28 | headerIds: true, 29 | breaks: false, 30 | sanitize: false, 31 | smartypants: false, 32 | xhtml: false, 33 | // eslint-disable-next-line @typescript-eslint/no-unsafe-call 34 | extensions: [gfmHeadingId({ prefix: '' })], 35 | } 36 | marked.use({ silent: true }) 37 | // This is a workaround so that hljs doesn't complain about mermaid not being a registered lang. 38 | hljs.registerAliases('mermaid', { languageName: 'plaintext' }) 39 | } 40 | 41 | marked(md: string): string { 42 | return marked(md, this.markedOptions) 43 | } 44 | 45 | parse(blocks: Blocks) { 46 | let markdown = this.markdownParser.parse(blocks) 47 | // if (this.debug) 48 | // fs.writeFileSync('./debug/parsed.md', markdown) 49 | // Take another pass to wrap any deeply nested mixed HTML content's inner text in p tags 50 | markdown = this._mixedHTML(markdown) 51 | // if (this.debug) 52 | // fs.appendFileSync('./debug/parsed.md', `--------ALTERED----------**\n\n\n${markdown}`) 53 | return marked(markdown, this.markedOptions) 54 | } 55 | 56 | _highlight(code: string, lang: string | undefined): string { 57 | let language 58 | if (lang === 'mermaid') 59 | language = 'mermaid' 60 | else 61 | language = (lang && hljs.getLanguage(lang)) ? lang : 'plaintext' 62 | const higlighted = hljs.highlight(code, { language }) 63 | const langClass = `language-${ 64 | (!language || language.includes('plain')) ? 'none' : language}` 65 | return `${higlighted.value}