Kaede Akatsuki

中二病也要开发 Android

Project NotionDown

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)
    • notion-sdk (official)

工作原理

NotionDown Workflows

NotionDown 通过 notion-py 读取 Notion Page 的数据,然后再(根据配置)解析成 MD 文件。

Basic usage

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

Advanced usage

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

Getting Started

Prepare

前置准备:

  1. Prepare notion_token_v2.
  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_v2

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

运行 NotionDown

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

1
2
3
4
5
6
7
8
9
10
11
# Run with cli cmd
PYTHONPATH=./ python main.py \
--blog_url <Notion Post Url> \
--token_v2 <token_v2>

# 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

参看以下 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

UnitTest Examples

单元测试放在 test/