{"id":41586176,"url":"https://github.com/wiremind/markdown-to-notionapi","last_synced_at":"2026-01-24T09:06:23.033Z","repository":{"id":316268063,"uuid":"1061895390","full_name":"wiremind/markdown-to-notionapi","owner":"wiremind","description":"A small tool to convert markdown to Notion format and have the possibility to upload to the API. ","archived":false,"fork":false,"pushed_at":"2025-09-23T16:19:12.000Z","size":2813,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T17:34:12.497Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wiremind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T14:27:07.000Z","updated_at":"2025-09-23T16:19:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"4b35d813-371f-421b-9167-f726d8ff2a6e","html_url":"https://github.com/wiremind/markdown-to-notionapi","commit_stats":null,"previous_names":["wiremind/markdown-to-notionapi"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/wiremind/markdown-to-notionapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremind%2Fmarkdown-to-notionapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremind%2Fmarkdown-to-notionapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremind%2Fmarkdown-to-notionapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremind%2Fmarkdown-to-notionapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wiremind","download_url":"https://codeload.github.com/wiremind/markdown-to-notionapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremind%2Fmarkdown-to-notionapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28722042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T08:27:05.734Z","status":"ssl_error","status_checked_at":"2026-01-24T08:27:01.197Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-24T09:06:22.868Z","updated_at":"2026-01-24T09:06:23.016Z","avatar_url":"https://github.com/wiremind.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# md2notion\n\nA production-ready Go CLI tool that converts Markdown to Notion blocks and uploads them to Notion pages via the public REST API.\n\n## Features\n\n- **Zero dependencies**: Direct HTTP calls to Notion API, no external SDK required\n- **CommonMark + GitHub flavored Markdown**: Support for headings, paragraphs, lists, code blocks, quotes, images, and more\n- **Flexible operations**: Append to existing pages, replace content, or create new pages\n- **Robust error handling**: Rate limiting, retry logic with exponential backoff, and clear error messages\n- **Developer-friendly**: Dry-run mode, verbose logging, stdin support\n\n## Installation\n\n```bash\ngo install github.com/wiremind/markdown-to-notionapi/cmd/notion-md@latest\n```\n\n## Quick Start\n\n1. **Create a Notion Integration**:\n   - Go to [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)\n   - Click \"New integration\" and give it a name\n   - Copy the \"Internal Integration Token\"\n\n2. **Share your page with the integration**:\n   - Open your Notion page\n   - Click \"Share\" → \"Invite\" → Select your integration\n\n3. **Set your token**:\n   ```bash\n   export NOTION_TOKEN=\"secret_abc123...\"\n   ```\n\n4. **Upload Markdown**:\n   ```bash\n   md2notion --page-id YOUR_PAGE_ID --md document.md\n   ```\n\n## Usage Examples\n\n### Append to existing page\n```bash\nmd2notion --page-id abc123def456 --md notes.md\n```\n\n### Read from stdin\n```bash\ncat README.md | md2notion --page-id abc123def456\n```\n\n### Replace page content\n```bash\nmd2notion --page-id abc123def456 --md document.md --replace\n```\n\n### Create new page\n```bash\nmd2notion --create --parent-id xyz789 --title \"My Document\" --md notes.md\n```\n\n### Dry run (preview JSON)\n```bash\nmd2notion --page-id abc123def456 --md notes.md --dry-run\n```\n\n### Handle relative images\n```bash\nmd2notion --page-id abc123def456 --md notes.md --image-base-url \"https://example.com/assets/\"\n```\n\n## Supported Markdown\n\n| Markdown | Notion Block |\n|----------|--------------|\n| `# ## ###` | heading_1/2/3 |\n| Paragraphs | paragraph |\n| **bold**, *italic*, `code` | Rich text formatting |\n| ~~strikethrough~~ | Rich text formatting |\n| [links](url) | Rich text links |\n| `- bulleted lists` | bulleted_list_item |\n| `1. numbered lists` | numbered_list_item |\n| Nested lists | Nested list items |\n| `\u003e blockquotes` | quote |\n| ` ```code blocks``` ` | code |\n| `---` horizontal rules | divider |\n| `![images](url)` | image (external URLs only) |\n\n## Command Line Options\n\n```\nUsage: md2notion [options]\n\nOptions:\n  --page-id string         Notion page ID to append blocks to (required unless --create is set)\n  --parent-id string       Parent page ID for creating new page (required if --create is set)\n  --title string           Title for new page (required if --create is set)\n  --md string              Path to markdown file (default: read from stdin)\n  --append                 Append blocks to the end of the page (default true)\n  --replace                Replace existing page content\n  --create                 Create a new page\n  --image-base-url string  Base URL for relative image paths\n  --dry-run                Print JSON that would be sent, don't call API\n  --notion-version string  Notion API version (default \"2022-06-28\")\n  -v, --verbose            Verbose output\n  --timeout duration       HTTP request timeout (default 1000s)\n  -h, --help              Show help\n\nEnvironment Variables:\n  NOTION_TOKEN    Notion integration token (required)\n```\n\n## Finding Page IDs\n\n### From URL\nIf your page URL is `https://notion.so/My-Page-abc123def456`, the page ID is `abc123def456`.\n\n### From API\nYou can also use the Notion API to list pages in a database or workspace.\n\n## Error Handling\n\nThe tool provides clear, actionable error messages:\n\n- **Authentication errors**: Check your `NOTION_TOKEN`\n- **Permission errors**: Ensure the integration has access to the page\n- **Rate limiting**: Automatically handled with exponential backoff\n- **Invalid page ID**: Verify the page ID format and permissions\n\n## Limitations\n\n- **Images**: Only external URLs are supported (no binary upload)\n- **Tables**: Not supported (would require complex Notion table structure)\n- **Advanced formatting**: Some complex Markdown features may not translate perfectly\n\n## Development\n\n### Quick Setup\n```bash\ngit clone https://github.com/wiremind/markdown-to-notionapi.git\ncd markdown-to-notionapi\nmake dev-setup  # Install development tools\nmake build      # Build the binary\n```\n\n### Available Commands\n```bash\nmake help           # Show all available commands\nmake test           # Run tests\nmake coverage       # Run tests with coverage report\nmake lint           # Run golangci-lint\nmake security       # Run security scans\nmake check          # Run all quality checks\nmake build          # Build binary\nmake build-all      # Build for all platforms\nmake container-build # Build container image\nmake clean          # Clean build artifacts\n```\n\n### Running Tests\n```bash\n# Unit tests\nmake test\n\n# With coverage\nmake coverage\n\n# All quality checks\nmake check\n```\n\n### Local Testing\n```bash\n# Set up test environment\nexport NOTION_TOKEN=\"your-integration-token\"\nexport TEST_PAGE_ID=\"your-test-page-id\"\n\n# Test locally\nmake run-local\n\n# Test container\nmake container-test\n```\n\n### GitHub Actions CI\n```yaml\nname: CI\non: [push, pull_request]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - uses: actions/setup-go@v4\n      with:\n        go-version: '1.25'\n    - run: go test ./...\n    - run: go vet ./...\n    - run: go build ./cmd/notion-md\n```\n\n## Docker Usage\n\n### Pull and Run\n```bash\n# Pull the latest image\ndocker pull ghcr.io/wiremind/markdown-to-notionapi:latest\n\n# Run with a file\ndocker run --rm -v $(pwd):/data -e NOTION_TOKEN=$NOTION_TOKEN \\\n  ghcr.io/wiremind/markdown-to-notionapi:latest \\\n  -page-id=YOUR_PAGE_ID -md=/data/document.md\n\n# Run with stdin\ncat README.md | docker run --rm -i -e NOTION_TOKEN=$NOTION_TOKEN \\\n  ghcr.io/wiremind/markdown-to-notionapi:latest \\\n  -page-id=YOUR_PAGE_ID\n```\n\n### Build Locally\n```bash\n# Using Docker\ndocker build -f Containerfile -t md2notion .\n\n# Using Podman (also works with Containerfile)\npodman build -f Containerfile -t md2notion .\n\n# Run the container\ndocker run --rm -e NOTION_TOKEN=$NOTION_TOKEN md2notion -page-id=YOUR_PAGE_ID -dry-run\n```\n\n## GitHub Actions Integration\n\n### Using Docker Image Directly\n```yaml\nname: Upload to Notion\non: [push]\n\njobs:\n  upload:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    \n    - name: Upload README to Notion\n      uses: docker://ghcr.io/wiremind/markdown-to-notionapi:latest\n      env:\n        NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}\n      with:\n        args: -page-id=${{ secrets.NOTION_PAGE_ID }} -verbose README.md\n```\n\n### Using Custom Action\n```yaml\nname: Upload to Notion\non: [push]\n\njobs:\n  upload:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    \n    - name: Upload documentation\n      uses: wiremind/markdown-to-notionapi@main\n      with:\n        page-id: ${{ secrets.NOTION_PAGE_ID }}\n        markdown-file: 'docs/api.md'\n        dry-run: 'false'\n        verbose: 'true'\n      env:\n        NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}\n    \n    - name: Upload inline content\n      uses: wiremind/markdown-to-notionapi@main\n      with:\n        page-id: ${{ secrets.NOTION_PAGE_ID }}\n        markdown-content: |\n          # Build Report\n          \n          **Status**: ✅ Success\n          **Commit**: ${{ github.sha }}\n          **Branch**: ${{ github.ref_name }}\n          **Time**: ${{ github.event.head_commit.timestamp }}\n      env:\n        NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}\n```\n\n### Action Inputs\n| Input | Description | Required | Default |\n|-------|-------------|----------|---------|\n| `page-id` | Notion page ID to upload to | ✅ | |\n| `markdown-file` | Path to markdown file | | |\n| `markdown-content` | Inline markdown content | | |\n| `notion-token` | Notion token (or use env var) | | |\n| `dry-run` | Only show what would be uploaded | | `false` |\n| `verbose` | Enable verbose output | | `false` |\n| `replace` | Replace page content instead of append | | `false` |\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Troubleshooting\n\n### \"NOTION_TOKEN environment variable is required\"\nSet your integration token:\n```bash\nexport NOTION_TOKEN=\"secret_your_token_here\"\n```\n\n### \"Object not found\" or \"Unauthorized\"\n- Verify the page ID is correct\n- Ensure the integration has access to the page (share the page with your integration)\n- Check that the token is valid and not expired\n\n### Images not appearing\n- Only external URLs (http/https) are supported\n- Use `--image-base-url` for relative paths\n- Verify image URLs are publicly accessible\n\n### Rate limiting\nThe tool automatically handles rate limiting with exponential backoff. If you hit limits frequently, consider:\n- Reducing concurrency\n- Adding delays between operations\n- Processing smaller batches\n\n### Large documents\nFor very large Markdown files:\n- The tool automatically chunks requests (100 blocks max per API call)\n- Use `--verbose` to monitor progress\n- Consider breaking large documents into smaller sections\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiremind%2Fmarkdown-to-notionapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiremind%2Fmarkdown-to-notionapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiremind%2Fmarkdown-to-notionapi/lists"}