https://github.com/natikgadzhi/notoma
Use Notion as your blogging editor, with any static gen blog engine. Notoma converts Notion pages to Markdown files.
https://github.com/natikgadzhi/notoma
cli command-line hexo jekyll markdown-editor notion notion-blog notion-editor notion-markdown static-site
Last synced: 2 months ago
JSON representation
Use Notion as your blogging editor, with any static gen blog engine. Notoma converts Notion pages to Markdown files.
- Host: GitHub
- URL: https://github.com/natikgadzhi/notoma
- Owner: natikgadzhi
- License: apache-2.0
- Archived: true
- Created: 2020-04-19T03:17:12.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2022-12-09T05:52:51.000Z (over 3 years ago)
- Last Synced: 2024-04-24T12:25:42.052Z (about 2 years ago)
- Topics: cli, command-line, hexo, jekyll, markdown-editor, notion, notion-blog, notion-editor, notion-markdown, static-site
- Language: Python
- Homepage: https://nategadzhi.github.io/notoma/
- Size: 451 KB
- Stars: 49
- Watchers: 3
- Forks: 3
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# notoma
One-way sync tool from Notion to Obsidian via Notion API. Notoma is designed for regular ongoing incremental updates. If you need a one-time update, Obsidian-native Notion importer will work faster.
## Features
- Sync Notion pages and databases to Obsidian-flavored markdown
- Incremental updates — only sync pages modified since last run
- Database → Obsidian Bases (`.base` files) conversion
- Attachment handling with automatic download
- Rate limiting to respect Notion API limits
## Prerequisites
- Go 1.24+ (for local development)
- A Notion integration token ([create one here](https://www.notion.so/my-integrations))
## Building Locally
```bash
# Clone the repository
git clone https://github.com/natikgadzhi/notoma.git
cd notoma
# Build using Make (outputs to build/)
make build
# Verify it works
./build/notoma --help
```
Or build manually:
```bash
go mod download
go build -o build/notoma ./cmd/notoma
```
## Building with Docker
```bash
make docker
# Or manually:
docker build -t notoma .
# Run it
docker run --rm notoma --help
```
## Make Targets
```bash
make build # Build binary to build/
make test # Run tests
make clean # Remove build artifacts
```
## Configuration
### 1. Set up your Notion token
Create a `.env` file (or set environment variables):
```bash
cp .env.sample .env
# Edit .env and add your NOTION_TOKEN
```
### 2. Create a config file
Create `config.yaml`:
```yaml
sync:
roots:
- url: "https://www.notion.so/myworkspace/Personal-Wiki-abc123..."
name: "Personal Wiki"
- url: "https://www.notion.so/myworkspace/def456...?v=xyz789..."
name: "Reading List"
output:
vault_path: "/path/to/obsidian-vault"
attachment_folder: "_attachments"
state:
file: "/path/to/notoma-state.json"
options:
download_attachments: true
```
## Usage
```bash
# Full sync
./notoma sync --config config.yaml
# Preview changes without writing files
./notoma sync --config config.yaml --dry-run
# Force full resync (ignore state)
./notoma sync --config config.yaml --force
# Show version
./notoma version
```
### With Docker
```bash
docker run --rm \
-e NOTION_TOKEN="your-token" \
-v $(pwd)/config.yaml:/config.yaml:ro \
-v /path/to/vault:/vault \
notoma sync --config /config.yaml
```
## Development
```bash
# Run tests
go test ./...
# Run tests with race detection
go test -race ./...
# Format code
go fmt ./...
# Run linter (requires golangci-lint)
golangci-lint run
```
## Contributing
This project uses a task-driven multi-agent development workflow. Tasks are tracked as markdown files in the `tasks/` directory:
```
tasks/
├── backlog/ # Not yet started
├── in-progress/ # Currently being worked on
└── done/ # Completed and merged
```
All code changes go through pull requests. See `CLAUDE.md` for the full development workflow.
## License
MIT