notion-down - GitLite

KO | EN

gitlite — search

#typescript #llm #golang #machine-learning #rust #linux #docker #macos #windows #awesome #pytorch #security #openai #open-source

notion-down

(★ 125)

Notion >> Markdown. Python utility that converts Notion pages into MD files, along with intergation to build static webpages such as Hexo | 自动从 Notion 笔记生成 MD 文件，并部署到 Hexo 静态博客 | Notion Pages より Markdown Files をコンバートする、更に Hexo Webpages までの自動化も可能

File Explorer

Download Latest Version (.zip)

- TECHNICAL_DOCS.md
- config.yml
- - build-hexo.yml
  - build-readme.yml
  - check-pr.yml
  - pycorrector-test.yml
- banner_02_notiondown.png
- notion_down.svg
- notiondown.png
- notiondown_workflows_notiondown.png
- __init__.py
- inspect_spell.py
- - notiondown_custom_configs.md
  - notiondown_custom_configs.md_properties.json
  - notiondown_gettokenv2.md
  - notiondown_gettokenv2.md_properties.json
  - notiondown_readme.md
  - notiondown_readme.md_properties.json
  - README.md
- - README.md
- - main.py
  - README.md
- - main.py
  - README.md
- - main.py
  - README.md
- - __init__.py
  - notion_ci_test.py
- - __init__.py
  - notion_client_test.py
  - notion_image_replace_test.py
  - notion_writer_image_download_test.py
- - __init__.py
  - notion_client_official_test.py
  - notion_image_official_test.py
  - notion_page_test.py
  - notion_reader_test.py
  - notion_writer_custom_test.py
  - notion_writer_hexo_test.py
  - notion_writer_image_download_official_test.py
  - notion_writer_myblog_test.py
  - notion_writer_test.py
  - test_database_parsing.py
  - test_live_connection.py
  - test_migration.py
  - test_optimization_consistency.py
- __init__.py
- corrects_test.py
- utils_test.py
- utils_yaml_escape_test.py
- __init__.py
- database_utils.py
- notion_utils.py
- utils.py
.config_file.json
.gitignore
CHANGELOG.md
config.py
main.py
notion_page.py
notion_reader.py
notion_token.py
notion_writer.py
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Notion Down

[🇨🇳](https://www.kaedea.com/2021/05/01/devops/project-notion-down/) [🇯🇵](https://www.kaedea.com/2021/05/01/devops/project-notion-down-jp/)

![](https://github.com/kaedea/notion-down/actions/workflows/check-pr.yml/badge.svg)

![BANNER-02](https://raw.githubusercontent.com/kaedea/notion-down/master/assets/banner_02_notiondown.png)

[Notion Down](https://github.com/kaedea/notion-down), python tools that convert Notion blog pages into Markdown files, along with integration to build static webpages such as Hexo.  Its inspiration and goal is to **avoid separation  of writing** by keep writing drafts or posts within [notion.so](http://notion.so/) and then publish them into MD webpages automatically.

* [Notion Down](#notion-down)
 * &nbsp;&nbsp;&nbsp;&nbsp;[Examples](#examples)
 * &nbsp;&nbsp;&nbsp;&nbsp;[Features](#features)
 * &nbsp;&nbsp;&nbsp;&nbsp;[Hot It Works](#hot-it-works)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Basic usage](#basic-usage)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Advanced usage](#advanced-usage)
 * &nbsp;&nbsp;&nbsp;&nbsp;[Getting Started](#getting-started)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Prepare](#prepare)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Run NotionDown](#run-notiondown)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[CI Build Script](#ci-build-script)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Showcase Jobs](#showcase-jobs)
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[UnitTest Examples](#unittest-examples)

## Examples

[kaedea.com](http://www.kaedea.com/)  
[hexo.kaedea.com](http://hexo.kaedea.com/)  
[基于 Notion 的笔记写作和博客分享自动化方案](https://www.kaedea.com/2021/05/20/devops/notion-to-markdown-file-automating-solution/)

## Features

What can NotionDown do now:

- Notion pages to MarkDown files
     - ~~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 support
     - ~~Pullquote Blocks (Notion ColumnList)~~
     - Image source replacing 
         - ~~Replace notion image url with image file~~
         - Replace notion image url with other CDN urls
     - Notion page embed blocks
 - Writing optimized integration
     - ~~Noton custom `ShortCode` blocks that control parametered MD files generating~~
     - ~~Mixed CN-EN text separation format~~ ([by pangu](https://github.com/vinta/pangu))
     - ~~Spelling inspect~~ (by [pycorrector](https://github.com/shibing624/pycorrector))
 - HEXO Integration
     - ~~HEXO page properties config~~
     - ~~HEXO generate~~
     - HEXO tags plugin
 - PyPI Publish
     - WIP
 - Notion APIs
     - ~~notion-py (3rd party)~~, as legacy mechanism, see **Support of Legacy APIs (token_v2)** part at bottom.
     - ~~notion-sdk (official)~~, current mechanism

## Hot It Works

![NotionDown Workflows](https://raw.githubusercontent.com/kaedea/notion-down/master/assets/notiondown_workflows_notiondown.png)

NotionDown read Notion pages data using [notion-sdk-py](https://github.com/ramnes/notion-sdk-py), and then write pages into MD files.

### 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

To get started with NotionDown, you should:

1. Prepare your Notion [Integration Token](https://developers.notion.com/docs/getting-started).
1. Prepare `public notion blog_url` as root post for NotionDown to get the pages you want to handle.
1. Run `notion-down/main.py` with your configs.

Check [here](https://developers.notion.com/docs/getting-started) to get `notion_token`. 
(For supported of legacy APIs with token_v2 & notion-py, see branch [archive/token-v2-support](https://github.com/kaedea/notion-down/tree/archive/token-v2-support).)

Duplicate [NotionDown Posts Template](https://www.notion.so/kaedea/NotionDown-Posts-Template-f77f3322915a4ab48caa0f2e76e9d733) to your own notion and take it as `blog_url` (or you can just use your existing blog post url). Note that, for now the root page should be public  as well as placed in root path of notion workspace.

### Run NotionDown

Basically just run `notion-down/main.py` :

```bash
# 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'

# Your can configure notion-down args by cli-args, config_file or SysEnv parameters
# Priority: cli args > config_file > SysEnv parameters > NotionDown default
```

For custom configurations in details, see [Custom Configurations](https://github.com/kaedea/notion-down/blob/master/dist/parse_readme/notiondown_custom_configs.md).

Also check the following procedures as showcase usages for NotionDown.

### CI Build Script
See GitHub Actions building scripts at `/.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.

Also see building script at `/.circleci/config.yaml`.

- `test-build-readme`: CircleCI jobs generating README for this repo. 
 - `test-build-hexo`: CircleCI jobs generating Hexo posts for [https://github.com/kaedea/notion-down-hexo-showcase](https://github.com/kaedea/notion-down-hexo-showcase).
 - `test-run-pycorrector`: CircleCI jobs that executing spelling check for the test posts.

### Showcase Jobs

See the usage showcase jobs at [/jobs](/jobs), and jobs outputs at [/dist](/dist).

- [README generating](/jobs/parse_readme/)
 - [Notion sample post generating](/jobs/parse_sample_posts/)
 - [HEXO public generating](/jobs/parse_sample_posts_for_hexo/)
 - Notion image page source replacing (WIP)

### UnitTest Examples

See unittest cases at `test/`.

## Support of Legacy APIs (token_v2)
The lastest APIs of notion-down has been migrated form `3rd-party token_v2` to `official integration token`. For supported of legacy APIs with token_v2 & notion-py, see branch [archive/token-v2-support](https://github.com/kaedea/notion-down/tree/archive/token-v2-support).

---

> This page is generated by [notion-down](https://github.com/kaedea/notion-down) from [notion.so NotionDown-README](https://www.notion.so/kaedea/NotionDown-README-d3463f3d398743879d663caf87efa029).