Project NotionDown

1. Example
2. Features
3. 工作原理
   1. Basic usage
   2. Advanced usage
4. Getting Started
   1. Prepare
   2. 运行 NotionDown
   3. CI Builds
   4. Showcase Jobs
   5. UnitTest Examples
5. 旧自定义 API 支持 (token_v2)

Notion Down 是一个用来把 Notion Page 转换成 Markdown 文件的 Python 工具，同时还提供了一些如 Hexo 静态博客构建的集成功能。其灵感和目标是通过 “在 Notion 上写作并自动生成目标 MD 文件” 来解决写作的割裂问题。比如：在 Notion 上编辑日志，并按照不同渠道配置生成目标 MD 文件；将指定 Notion 日志生成 Hexo Page 并自动部署到静态博客。

Example

kaedea.com
hexo.kaedea.com
基于 Notion 的笔记写作和博客分享自动化方案

Features

现在 NotionDown 提供以下功能：

• Notion Page 转换成 MarkDown 文件
  • Basic Notion PageBlocks parsing
  • Notion images refer & download
  • Notion nested list blocks
  • Notion obfuscated-links parsing
  • Notion table block (Collection)
  • Notion subpage / alias link parsing
• Advanced Notion PageBlocks 支持
  • Pullquote Blocks (Notion ColumnList)
  • 图源替换
    • Replace notion image url with image file
    • Replace notion image url with other CDN urls
  • Notion page embed blocks
• 写作增强
  • Noton custom ShortCode blocks that control parametered MD files generating
  • Mixed CN-EN text separation format (by pangu)
  • Spelling inspect (by pycorrector)
• HEXO 集成
  • HEXO page properties config
  • HEXO generate
  • HEXO tags plugin
• PyPI 发布
• Notion APIs
  • notion-py (3rd party), 已废弃，请参考文末 旧自定义 API 支持 (token_v2)。
  • notion-sdk (official), 当前支持方案

工作原理

NotionDown 通过 notion-sdk-py 读取 Notion Page 的数据，然后再（根据配置）解析成 MD 文件。

Basic usage

notion-down >> Notion APIs (notion-sdk-py) >> Notion pages data >> generating MD files

Advanced usage

WebHook >> notion-down >> Notion APIs (notion-sdk-py) >> Notion pages data >> generating MD files >> Copy into Hexo source >> generating webpages >> push to GitHub pages

Getting Started

Prepare

前置准备：

1. Prepare Notion Integration Token.
2. Prepare public notion blog_url as root post for NotionDown to get the pages you want to handle.
3. Run notion-down/main.py with your configs.

参考 这里 获取 notion_token。 (关于 token_v2 & notion-py 的旧版本 API 支持，请参考分支 archive/token-v2-support。)

复制一份 NotionDown Posts Template 到你的 Notion Workspace 并把其 URL 做为 blog_url (或者直接使用你自己已有的 Notion Posts)。需要注意的是，现阶段配合 notion_token_v2 使用的 Notion Posts 必须是 Public 的。

运行 NotionDown

执行 Python 基本 notion-down/main.py :

# Run with cli cmd
PYTHONPATH=./ python main.py \
    --blog_url <Notion Post Url> \
    --notion_token <notion_token>

# or
PYTHONPATH=./ python main.py \
    --config_file '.config_file.json'

# 有三种方式配置 NotionDown 的运行参数：cli-args, config_file or SysEnv parameters
# Priority: cli args > config_file > SysEnv parameters > NotionDown default

更详细的参数配置，请参考 Custom Configurations。

以下提供几种使用 NotionDown 的案例。

CI Builds

相关 GitHub Actions 构建脚本，参看 /.github/workflows：

• build-readme.yml: GitHub Actions workflow that generating README for this repo.
• build-hexo.yml: GitHub Actions workflow that generating Hexo posts for https://github.com/kaedea/notion-down-hexo-showcase.
• pycorrector-test.yml: GitHub Actions workflow that that executing spelling check for the test posts.

更多 CI 脚本 /.circleci/config.yaml：

• test-build-readme: CircleCI jobs 用来生成 NotionDown 的 README.md。
• test-build-hexo: CircleCI jobs 用来演示如何生成 Hexo 源文件 https://github.com/kaedea/notion-down-hexo-showcase。
• test-run-pycorrector: CircleCI jobs 用来演示如何执行拼写检查。

Showcase Jobs

示例脚本放在 /jobs，其运行产物在 /dist。

• 生成 README
• 生成 Notion posts
• 生成 Hexo 源文件
• Notion image page source replacing (WIP)

UnitTest Examples

单元测试放在 test/。

旧自定义 API 支持 (token_v2)

NotionDown 的最新 API 已从第三方 token_v2 迁移至官方 Integration Token。关于基于 token_v2 & notion-py 的旧版本 API 支持，请参考分支 archive/token-v2-support。