A CLI tool to export Notion database pages to various formats
- Export all pages from a Notion database to Markdown or MDX files
- Supports Hextra (Markdown) and Nextra (MDX) formats
- Preserves page metadata in frontmatter
- Maintains Notion content structure using notion-to-md
- Generates clean filenames from page titles
- Includes creation and last edited timestamps
- Supports internal link transformations
- Optional JSON export for raw data
- Node.js >= 14.0.0
- A Notion integration token
- Access to the Notion database you want to export
You can install this CLI tool globally using npm:
npm install -g @1984vc/notion-tools@latestOr locally in your project:
npm add -D @1984vc/notion-tools@latest- Create a Notion integration at https://www.notion.so/my-integrations
- Copy the integration token
- Set the token as an environment variable:
export NOTION_TOKEN=your_integration_token- Share your Notion database with the integration (click 'Share' in Notion and add your integration)
notion-tools export nextra --id <database_id> -o <output_path> [options]notion-tools export hextra --id <database_id> -o <output_path> [options]Options for both formats:
--id: Required. The Notion database ID-o, --output: Required. The output directory path--include-json: Optional. Include raw JSON export in output directory--base-path: Optional. Base path for internal links (e.g., /docs)--no-frontmatter: Optional. Exclude frontmatter from files
Example:
notion-tools export nextra --id "123456789abcdef" -o "./content/posts" --base-path "/docs"notion-tools json --id <database_id> -o <output_path>Options:
--id: Required. The Notion database ID-o, --output: Required. The output directory path for JSON file
Example:
notion-tools json --id "123456789abcdef" -o "./content/data"notion-tools raw-json --id <id> [-o <output_path>]Options:
--id: Required. The Notion database or page ID-o, --output: Optional. Output file path (defaults to stdout)
Example:
notion-tools raw-json --id "123456789abcdef" -o "./data/raw.json"The database ID is the part of your Notion database URL after the workspace name and before the question mark:
https://www.notion.so/workspace-name/123456789abcdef?v=...
^^^^^^^^^^^^^^
This is your database ID
Each page is exported as a file with frontmatter metadata:
---
title: Page Title
notionId: page-id
createdAt: 2024-01-01T00:00:00.000Z
lastEditedAt: 2024-01-01T00:00:00.000Z
weight: 0
---
[Your page content here]To develop locally:
- Clone this repository
- Install dependencies:
npm install - Set up your NOTION_TOKEN environment variable
- Link the package locally:
npm link - Run the CLI:
notion-tools export nextra --id <database_id> -o <output_path>
Run tests:
npm testRun linting:
npm run lintThis project uses GitHub Actions for continuous integration and deployment:
The CI workflow runs automatically on:
- All pull requests to the
mainbranch - All pushes to the
mainbranch
It performs:
- Installation of dependencies
- Code linting
- Test suite execution
To publish a new version to npm:
- Update the version in package.json:
npm version patch # for bug fixes
npm version minor # for new features
npm version major # for breaking changes- Push the new version tag:
git push origin v*The release workflow will automatically:
- Run tests
- Build the package
- Publish to npm under the @1984vc organization
Note: Publishing requires an NPM_TOKEN secret to be set in the repository's GitHub secrets.
Key dependencies:
- @notionhq/client: ^2.2.15
- commander: ^12.1.0
- notion-to-md: ^3.1.1
The CLI will:
- Verify the NOTION_TOKEN is set
- Create the output directory if it doesn't exist
- Skip and report any pages that fail to export
- Provide progress feedback during export
MIT
notion-tools export nextra --id <database_id> -o <output_path> [options]notion-tools export hextra --id <database_id> -o <output_path> [options]Options for both formats:
--id: Required. The Notion database ID-o, --output: Required. The output directory path--include-json: Optional. Include raw JSON export in output directory--base-path: Optional. Base path for internal links (e.g., /docs)--no-frontmatter: Optional. Exclude frontmatter from files
Example:
notion-tools export nextra --id "123456789abcdef" -o "./content/posts" --base-path "/docs"notion-tools json --id <database_id> -o <output_path>Options:
--id: Required. The Notion database ID-o, --output: Required. The output directory path for JSON file
Example:
notion-tools json --id "123456789abcdef" -o "./content/data"notion-tools raw-json --id <id> [-o <output_path>]Options:
--id: Required. The Notion database or page ID-o, --output: Optional. Output file path (defaults to stdout)
Example:
notion-tools raw-json --id "123456789abcdef" -o "./data/raw.json"The database ID is the part of your Notion database URL after the workspace name and before the question mark:
https://www.notion.so/workspace-name/123456789abcdef?v=...
^^^^^^^^^^^^^^
This is your database ID