Skip to content

Commit e1b7368

Browse files
alvisalvis
committed
docs: enrich the documentation
1 parent 0be8b1b commit e1b7368

File tree

1 file changed

+251
-2
lines changed

1 file changed

+251
-2
lines changed

‎README.md

Lines changed: 251 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
# Gatsby Source Plugin Notion
66

7-
</div>
7+
💫 _Use Notion as the CMS for your Gatsby site, multiple databases and pages via the official API._
88

9-
> Use Notion as the CMS for your Gatsby site, supporting multiple databases and pages.
9+
•   [Quick Start](#quick-start)   •   [Usage](#usage)   •   [Known Limitations](#known-limitations)   •   [FAQ](#faq)   •   [About](#about)   •
1010

1111
[![npm](https://img.shields.io/npm/v/gatsby-source-notion?style=flat-square)](https://github.com/alvis/gatsby-source-notion/releases)
1212
[![build](https://img.shields.io/github/workflow/status/alvis/gatsby-source-notion/code%20test?style=flat-square)](../actions)
@@ -16,8 +16,257 @@
1616
[![dependencies](https://img.shields.io/david/alvis/gatsby-source-notion.svg?style=flat-square)](https://david-dm.org/alvis/gatsby-source-notion)
1717
[![license](https://img.shields.io/github/license/alvis/gatsby-source-notion.svg?style=flat-square)](https://github.com/alvis/gatsby-source-notion/blob/master/LICENSE)
1818

19+
</div>
20+
21+
Tired of uploading a markdown file to your GitHub for every new blog post? Having colleagues who don't know how to git commit? or simply you don't want to integrate with another CMS?
22+
23+
**gatsby-source-notion** is a solution for you manage the content of your Gatsby site without any
24+
25+
### Features
26+
27+
- 👉 Allow you to build a website with content from your Notion databases or pages
28+
- 💈 Page contents in markdown!
29+
- ⌨️ Title and their properties in plain text accessible via the front matter
30+
- 🔮 All raw properties accessible via GraphQL
31+
- 🍻 Support for `remark` and `mdx`
32+
33+
# Quick Start
34+
35+
## Step 0 - Install the source plugin
36+
37+
```shell
38+
npm install --save-dev gatsby-source-notion
39+
```
40+
41+
Optionally, if you want markdown support,
42+
it's recommended to have `gatsby-plugin-mdx` installed as well.
43+
44+
```shell
45+
npm install --save-dev gatsby-source-notion gatsby-plugin-mdx
46+
```
47+
48+
## Step 1 - Get your access token
49+
50+
[Follow the official integration guide](https://developers.notion.com/docs/getting-started).
51+
52+
1. Go to https://www.notion.com/my-integrations.
53+
2. Click the `+ New integration` button.
54+
3. Give your integration a name, for example `My Gatsby Website`.
55+
4. Select the workspace where you want this plugin to get content from.
56+
5. Click `Submit` to create the integration.
57+
6. Copy the `Internal Integration Token` on the next page and export it to the `GATSBY_NOTION_TOKEN` environment variable.
58+
59+
<div align="center">
60+
<img alt="Steps to get an access token" src="https://files.readme.io/2ec137d-093ad49-create-integration.gif" width="50%" />
61+
</div>
62+
63+
## Step 2 - Specify the databases and pages you allow this plugin to access
64+
65+
Integrations don't have access to any databases or pages in the workspace initially.
66+
For the plugin to access content, you must share a specific database or page with the integration.
67+
68+
1. Open the page or database in which your content sits.
69+
2. Click the `Share` button and select your integration by its name, then click `Invite`.
70+
3. Repeat for each of the content resource you want to use for building your Gatsby website.
71+
72+
**NOTE** Alternative to sharing your databases and pages one by one, you can also choose to grant access to all databases and pages to your integration in the `Members` section in the workspace settings.
73+
However, it is not advisable to do this because that will grant unnecessary access which is bad for security.
74+
75+
<div align="center">
76+
<img alt="Steps to share a database" src="https://files.readme.io/0a267dd-share-database-with-integration.gif" width="50%" />
77+
</div>
78+
79+
**IMPORTANT** For each of your shared databases or pages, remember to record the UUID.
80+
You will need to specify them in the config.
81+
82+
The UUID of a database can be obtained from your database URL.
83+
One way to get this information is by using your own database URL which has the following format:
84+
`https://www.notion.so/<your workspace>/<database UUID>?some_query_string`
85+
86+
`https://www.notion.so/<your workspace>/<page title>-<page UUID>`
87+
88+
## Step 3 - Setup the plugin in your gatsby site
89+
90+
**IMPORTANT** For security reasons, it's recommended to specify the API access token via the `GATSBY_NOTION_TOKEN` environment variable.
91+
92+
In your `gatsby-config`, add `gatsby-source-notion` with settings something like:
93+
94+
```ts
95+
{
96+
resolve: 'gatsby-source-notion',
97+
options: {
98+
databases: ['<< your database UUID >>'],
99+
pages: ['<< your page UUID >>'],
100+
},
101+
};
102+
```
103+
104+
**NOTE** Alternatively, you can specify the databases and pages via the `GATSBY_NOTION_DATABASES` and `GATSBY_NOTION_PAGES` environment variables separated by a comma `,`.
105+
106+
## Step 4 - Create pages with your content stored in Notion
107+
108+
**IMPORTANT** In this step, assume that you have `gatsby-plugin-mdx` installed and there is a `path` property in your database page.
109+
110+
Here is an example in TypeScript. A JS implementation would follow the same logic:
111+
112+
```ts
113+
/* gatsby-node */
114+
import type { GatsbyNode } from 'gatsbby';
115+
116+
// types generated from a code generator such as `gatsby-plugin-graphql-codegen`
117+
import type { BlogsQuery } from '@graphql';
118+
119+
export const createPages: GatsbyNode['createPages'] = async ({
120+
actions,
121+
graphql,
122+
}) => {
123+
const { createPage } = actions;
124+
125+
const response = await graphql<BlogsQuery>(`
126+
query Blogs {
127+
notionDatabase(ref: { eq: "<< your database UUID >>" }) {
128+
childrenNotionPage {
129+
childMdx {
130+
id
131+
frontmatter {
132+
path
133+
}
134+
}
135+
}
136+
}
137+
}
138+
`);
139+
140+
response?.data?.notionDatabase?.childrenNotionPage?.forEach((page) => {
141+
const mdx = page?.childMdx;
142+
143+
const path = mdx?.frontmatter?.path;
144+
145+
if (mdx && path) {
146+
createPage({
147+
path,
148+
// NOTE: must resolve to the absolute path of the component
149+
component: resolve('<< path to your page component >>'),
150+
context: {
151+
id: mdx.id,
152+
},
153+
});
154+
}
155+
});
156+
};
157+
```
158+
159+
```tsx
160+
/* you page component */
161+
import React from 'react';
162+
import { graphql } from 'gatsby';
163+
import { MDXRenderer } from 'gatsby-plugin-mdx';
164+
165+
import { Layout } from '<< path to your layout component >>';
166+
167+
import type { PageProps } from 'gatsby';
168+
169+
// types generated from a code generator such as `gatsby-plugin-graphql-codegen`
170+
import type { BlogQuery } from '@graphql';
171+
172+
const Blog: React.FC<PageProps<BlogQuery>> = ({ data }) => {
173+
// since this page is referred from the createPages API, it's safe to assume the mdx node is there
174+
const mdx = data.mdx!;
175+
176+
const title = mdx.frontmatter?.title;
177+
const body = mdx.body;
178+
179+
return (
180+
<Layout>
181+
<h1>{title}</h1>
182+
<MDXRenderer>{body}</MDXRenderer>
183+
</Layout>
184+
);
185+
};
186+
187+
export const pageQuery = graphql`
188+
query Blog($id: String!) {
189+
mdx(id: { eq: $id }) {
190+
frontmatter {
191+
title
192+
}
193+
body
194+
}
195+
}
196+
`;
197+
198+
export default Blog;
199+
```
200+
201+
# Usage
202+
203+
At this point, you should have an idea of how to use gatsby-source-notion. To make your experience even better, you can also configure a few more things:
204+
205+
```ts
206+
/* plugin options you can specify in `gatsby-config` */
207+
interface PluginConfig {
208+
/** access token, default to be the environment variable GATSBY_NOTION_TOKEN */
209+
token?: string;
210+
/** api version, default to be 2021-05-13 */
211+
version?: string;
212+
/** UUID of databases to be sourced, default to be `[]` i.e. none */
213+
databases?: string[];
214+
/** UUID of pages to be sourced, default to be `[]` i.e. none */
215+
pages?: string[];
216+
}
217+
```
218+
219+
# Known Limitations
220+
221+
As this plugin relies on the the official Notion API which is still in beta, we share the same limitations as the API.
222+
223+
- Currently, only text-based blocks can be extracted via this API.
224+
i.e. Items such as embedded pdfs are not supported.
225+
- If you have a very long or sizing page, be aware that [the official Notion API has a limit of maximum size of 1000 block elements and 500kb](https://developers.notion.com/reference/errors#size-limits).
226+
Currently, there is no way we can get data beyond that.
227+
- Indentation is only supported for lists such as bullets, numbers and to-do lists.
228+
Other text will not be indented due to the limitations of the markdown format.
229+
- Due to GraphQL’s limitation, property names with non-alphanumeric characters, such as a space ` ` etc will be converted to an underscore `_` automatically.
230+
You may run into conflicts if you have two properties (e.g., `Property Name` and `Property_Name`) whose names are close but differ in these characters.
231+
232+
## Unsupported Blocks
233+
234+
- Sub Page
235+
- Call out
236+
- Image
237+
- Video
238+
- Code Block
239+
- Coloured Text
240+
- Underlined Text
241+
242+
## Image
243+
244+
As of `2021-07-01`, the official Notion API doesn't export any image block from a page.
245+
However, there is a workaround that you can use to inject images into an article.
246+
You just need to embed them using the normal markdown syntax as part of your paragraph like this:
247+
248+
```md
249+
![alt text](path-to-image)
250+
```
251+
252+
# FAQ
253+
254+
1. How can I specify different databases and pages for different environments, such as those used by staging, or production?
255+
You can specify the database or page UUIDs in the `GATSBY_NOTION_DATABASES` and `GATSBY_NOTION_PAGES` environment variables, separated by a comma.
256+
257+
2. I encountered a 404 error from the plugin, what happened?
258+
You may forget to grant the integration access to the database or page specified in the config.
259+
Check if you've given it permissions, or if any of the UUIDs contain typos.
260+
261+
3. What can I do if I don't want to permanently delete a post but just hide it for awhile?
262+
You can create a page property (for example, a publish double checkbox) and use this information in your page creation process.
263+
19264
# About
20265

266+
This source plugin is built on the official Notion API.
267+
If you are interested in using it as well, here is a [Postman collection](<(<(https://www.postman.com/notionhq/workspace/notion-s-public-api-workspace/overview)>)>) you can explore.
268+
Also follow the [official API documentation](https://developers.notion.com/reference/intro) to learn more about how to use it.
269+
21270
### License
22271

23272
Copyright © 2021, [Alvis Tang](https://github.com/alvis). Released under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)