notionmd-cli

README

notionmd-cli

A CLI tool to manipulate Notion pages from Markdown files, wrapping Notion MD.

Build Instructions

You need Go 1.18+ installed.

# Clone the repo (if you haven't already)
git clone <repo-url>
cd notionmd-cli

# Build the binary
go build -o notionmd-cli

To override the version (shown with --version/-v), build with:

go build -ldflags "-X main.Version=1.2.3" -o notionmd-cli

Replace 1.2.3 with your desired version string.

Usage

You can run directly with Go or use the compiled binary.

With go run

go run main.go --token <token> --page <page_id> --md <markdown-file> [flags]

With the binary

./notionmd-cli --token <token> --page <page_id> --md <markdown-file> [flags]

Flags

• --token (required): Notion integration token
• --page (required): Target Notion page ID
• --md (required): Path to markdown file
• --append: Append content to the bottom of the existing Notion page (default)
• --replace: Replace all existing content with new content
• --use-hash: Store and check content hash in a dedicated metadata block and/or property
• --hash-property <name>: Optionally specify property name for content hash (e.g. --hash-property=MyPropName)
• --rewrite-text <mapping.json>: Path to JSON file mapping text to rewrite in the markdown file (see below)
• --dry-run: Run all logic except Notion sync (no changes will be made to Notion)
• --debug: Enable debug output to stdout
• --version, -v: Print program version and exit

Examples

Basic usage (append, default):

./notionmd-cli --token $NOTION_TOKEN --page <page_id> --md notes.md

Replace all content:

./notionmd-cli --token $NOTION_TOKEN --page <page_id> --md notes.md --replace

Using go run:

go run main.go --token $NOTION_TOKEN --page <page_id> --md notes.md --replace --debug

With rewrite mapping:

./notionmd-cli --token $NOTION_TOKEN --page <page_id> --md notes.md --rewrite-text notion-links.json

Rewrite Mapping JSON Format

• Single page mapping:

  {
    "TEST_REPLACE": "THIS_HAS_BEEN_REPLACED"
  }
  

• Multi-page mapping:

  {
    "docs/installation.md": {
      "TEST_REPLACE": "THIS_HAS_BEEN_REPLACED"
    },
    "docs/other.md": {
      "FOO": "BAR"
    }
  }
  

Releasing with GoReleaser

This project uses goreleaser for publishing releases.

Requirements

• Install GoReleaser:

  brew install goreleaser
  # or
  curl -sL https://git.io/goreleaser | bash
  

• Ensure you have a .goreleaser.yml file (already present in this repo).
• (Optional) Set up a GitHub token for publishing:

  export GITHUB_TOKEN=your_token
  

Tagging and Releasing a New Version

1. Bump your version in code or via git tag (e.g. git tag v1.2.3)
2. Push the tag to GitHub:

   git push origin v1.2.3
   

3. Run GoReleaser:

   goreleaser release --clean
   

   or for a dry run:

   goreleaser release --clean --skip-publish --skip-validate --snapshot
   

See the GoReleaser docs for more info.

Build and Test Locally

goreleaser build --clean

Create a Release

This will build, create archives, and publish to GitHub Releases:

goreleaser release --clean

For a dry run (no publishing):

goreleaser release --clean --skip-publish --snapshot

See goreleaser.com for more info.