@1984vc/notion_mdx
v2.0.0
Published
CLI tool to export Notion database pages to MDX files with frontmatter
Downloads
123
Maintainers
Readme
@1984vc/notion_mdx
A CLI tool to export Notion database pages to MDX files with frontmatter metadata.
Features
- Export all pages from a Notion database to MDX files
- 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
Prerequisites
- Node.js >= 14.0.0
- A Notion integration token
- Access to the Notion database you want to export
Installation
You can install this CLI tool globally using npm:
npm install -g @1984vc/[email protected]
Or locally in your project:
npm add -D @1984vc/[email protected]
Setup
- 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)
Usage
Export to MDX
notion_mdx export-mdx --id <database_id> -o <output_path> [options]
Options:
--id
: Required. The Notion database ID-o, --output
: Required. The output directory path for MDX files--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 MDX files
Example:
notion_mdx export-mdx --id "123456789abcdef" -o "./content/posts" --base-path "/docs"
Export to JSON
notion_mdx 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_mdx json --id "123456789abcdef" -o "./content/data"
Export Raw JSON
notion_mdx 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_mdx raw-json --id "123456789abcdef" -o "./data/raw.json"
Finding Your Database ID
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
Output Format
Each page is exported as an MDX 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]
Development
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_mdx export-mdx --id <database_id> -o <output_path>
Testing and Linting
Run tests:
npm test
Run linting:
npm run lint
CI/CD
This project uses GitHub Actions for continuous integration and deployment:
Continuous Integration
The CI workflow runs automatically on:
- All pull requests to the
main
branch - All pushes to the
main
branch
It performs:
- Installation of dependencies
- Code linting
- Test suite execution
Automated Releases
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.
Dependencies
Key dependencies:
- @notionhq/client: ^2.2.15
- commander: ^12.1.0
- notion-to-md: ^3.1.1
Error Handling
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
License
MIT