Kaede Akatsuki

Notion Down とは、 Notion ページを Markdown ファイルにコンバートする Python ツールです。ちなみ、Hexo などのブログとのインテグレーションも可能です。このレポのインスピレーションやゴールは、「Notion のみでノートしながら自動的に目標な MD ファイルを生成する」ことで、ライティングの断片化を避ける。

Example

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

Features

今 NotionDown のできること:

• Notion ページのコンバート
  • (削除) 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
• アドバンス 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) (削除ここまで), Deprecated, 下記の " レガシー API のサポート (token_v2)" の部分を参考する
  • notion-sdk (official), Currently supported

ワークフロー

NotionDown Workflows

NotionDown は notion-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. Notion Integration Token を取る。
2. ルーツページの public notion blog_url を取る。
3. notion-down/main.py を実行する。

notion_token のゲットする方法は ここに ある。 (token_v2 & notion-py を使用するレガシー API のサポートについては、ブランチ archive/token-v2-support を参照してください。)

NotionDown Posts Template を自分の Notion Workspace にコピーする、そしてその URL を blog_url をしてつかいます(既存するルーツページを使うのもオッケー)。ちなみに、ルーツページを Public にセットすることが必要です。

NotionDown の実行

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> \
 --notion_token <notion_token>

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

# アーギュメントのコンフィグ: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: README.md を生成する GitHub Actions Workflow。
• build-hexo.yml: デーモン Hexo ソースコードを生成する GitHub Actions workflow、チェック https://github.com/kaedea/notion-down-hexo-showcase。
• pycorrector-test.yml: スペルチェックの GitHub Actions workflow。

CircleCI スクリプト /.circleci/config.yaml も参照してください:

• test-build-readme: README.md を生成する CircleCI Jobs。
• test-build-hexo: デーモン Hexo ソースコードを生成する CircleCI jobs、チェック https://github.com/kaedea/notion-down-hexo-showcase。
• test-run-pycorrector: スペルチェックの CircleCI jobs。

Showcase Jobs

デーモンスクリプトは /jobs にあり、そしてアウトプットは /dist。

• Build README
• Build Notion posts
• Build 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 を参照してください。