conf2obsi

Copy personally authored Confluence documents into your Obsidian vault.

Run it with no arguments and it walks you through setup: Confluence URL, API token, which accounts to export, and where to put notes. Settings live under $XDG_CONFIG_HOME/conf2obsi/config.toml (default ~/.config/conf2obsi/config.toml) and are never committed to git.

Requirements

• Python 3.11+
• pandoc (for HTML → Markdown conversion)
• A Confluence Cloud site you can access
• An Atlassian API token

Install

From this repo (recommended for development / one-off use):

git clone https://github.com/trak3r/conf2obsi.git
cd conf2obsi
uv sync
uv run conf2obsi setup   # optional — `uv run conf2obsi` alone will prompt on first run

Prefix every command with uv run while working from the repo. That uses the project’s .venv and does not install anything on your PATH.

Or install as a user tool (puts conf2obsi on your PATH):

uv tool install .
conf2obsi

Usage

From the repo:

uv run conf2obsi              # first run: setup wizard, then full export
uv run conf2obsi setup        # (re)configure interactively
uv run conf2obsi config       # show saved settings (no secrets printed)
uv run conf2obsi export       # export using saved settings
uv run conf2obsi export --max 10   # smoke test with 10 pages
uv run conf2obsi export --no-install   # convert only, skip copy to output dir

If you used uv tool install, drop the uv run prefix.

What it does

1. Resolves Atlassian account IDs for your creator email(s)
2. Searches Confluence with CQL: creator in (...)
3. Skips junk titles (deprecated, screenshots, etc.) — configurable in config
4. Downloads page HTML in parallel
5. Converts to GitHub-Flavored Markdown via pandoc
6. Adds YAML frontmatter with title and Confluence URL
7. Copies new notes into your output directory (existing files are left alone unless overwrite_existing = true)

Scratch HTML and intermediate Markdown go to /tmp/conf2obsi/ by default (override with work_dir in config).

Configuration file

Example ~/.config/conf2obsi/config.toml:

confluence_url = "https://your-company.atlassian.net"
auth_email = "you@company.com"
api_token = "your-api-token"
creator_emails = ["you@company.com", "old-you@previous-company.com"]
known_account_ids = []
output_dir = "/path/to/Obsidian/Vault/Confluence"
skip_patterns = ["deprecated", "cleanshot", "meeting_note"]
overwrite_existing = false
search_limit = 100
fetch_parallel = 8
fetch_retries = 3

Override the config path with CONF2OBSI_CONFIG=/path/to/config.toml.

Development

uv sync --all-extras
uv run pytest
uv run ruff check .

License

MIT — see LICENSE.