docusaurus-notion-mdx-plugin
v0.1.9
Published
> Currently in the testing version, only supports docs. Will support multiple docs and blogs in the future.
Downloads
10
Readme
Currently in the testing version, only supports docs. Will support multiple docs and blogs in the future.
docusaurus-notion-mdx-plugin
docusaurus-notion-mdx-plugin enables you to use Notion as the editor for Docusaurus. By using Notion instead of raw markdown files, you eliminate the need to teach non-developers how to make git commits and pull requests. This simplifies collaboration and editing between users with less technical proficiency. docusaurus-notion-mdx-plugin allows non-technical team members to contribute content in a more user-friendly manner without having to learn complex version control processes.
Example Site: https://sillsdev.github.io/docu-notion-sample-site/
Instructions
1. In Notion, duplicate the docu-notion template
Go to this template page. Duplicate it into your own workspace. However, please note that you should not modify the fields of the database.
2. Create a Notion Integration
In order for docusaurus-notion-mdx-plugin to read your site via Notion's API, you need to create what Notion calls an "integration". Follow these instructions to make an integration and get your token. Remember to limit your integration to "READ" access.
Please remember your Notion Integration key, as it will be used for configuring the Docusaurus plugin later.
3. Connect your Integration
Go to the page that will be the root of your site. This page should have, as direct children, your "Outline" (required) and "Database" (optional) pages. Follow these instructions.
4. Set up your documentation site.
Install the plug-in
npm i docusaurus-notion-mdx-plugin
5. Modify the docusaurus.config.js file to configure plugins.
plugins: [
.......,
['docusaurus-notion-mdx-plugin',
{
notionAuth: 'Your docusaurus-notion-mdx-plugin Notion Integration Key.',
databaseId: 'Notion template page database ID',
lastSyncTime:"2023-12-07T10:32:23.473Z"
}
],
],
How to obtain the database ID.
First, determine the id of your root page by clicking "Share" and looking at the url it gives you. E.g. https://www.notion.so/max-gao/ex0b17d232e34a81sdf72197c041108f means that the id is "ex0b17d232e34a81sdf72197c041108f".
lastSyncTime Field Description
This field represents the data you want to synchronize from this day onwards. Each subsequent run of the project will automatically update it. The corresponding field in the database is the last modified time, so any updated articles will also be synchronized here.
5. Add your page under the database.
When adding a page under the template database you copied, please pay attention to the fields of the database. Below are the meanings and explanations of the fields.
- Name -> Docs title
- DN - Short title -> Corresponding to the sidebar_label in Docusaurus docs front matter.
- DN - Tags -> Corresponding to the tags in Docusaurus docs front matter.
- DN - Docs classification -> Corresponding directory structure under "docs".
- DN - Last edited time -> For synchronization
6. Run your docusaurus project
pnpm
pnpm start
View the files generated in the Docs
directory.
7. Commit
Every time you run the project, the page will be updated. If you are using a CI system (such as Github Actions) for deployment, you can exclude submitting the page file.
Code blocks configuration
Some popular languages like Java, C#, or PHP are not enabled by default. Supported Languages
The MDX example
tips
The code block header in Docusaurus corresponds to the Caption in the notion code block
TODO
- [ ] Reverse delete
- [ ] Image Resources Sync
- [ ] Elegant configuration category.json file
Please begin to enjoy
Release Nodes
Release 0.1.8 2023-12-12
- Internal refactoring
- Support for bold, underline, and other formatting.
- Support hyperlinks in the block.
- The unified directory structure is lowercase
- Improve README.
- Support code block title
Release 0.1.9 2023-12-14
- bugfix
- Suppport MDX and React
- Suppport Admonitions