docspan

Push and pull markdown to Google Docs and Confluence from a single CLI. docspan provides bidirectional sync with three-way merge conflict detection, structural diff push that preserves comments on unchanged paragraphs, and a simple YAML-based configuration file.

The config file is named markgate.yaml for backward compatibility. docspan.yaml is also recognized — if present in the working directory (and no markgate.yaml is there), docspan reads and writes it instead, so a project can rename its config file at its own pace.

Supported Backends

Install

pip install docspan

Optional: mermaid diagram rendering (Google Docs backend only). Pushing a ```mermaid fence to Google Docs renders it to a PNG via the official mermaid-cli (mmdc), which wraps Puppeteer/headless Chrome — there is no pure-Python renderer, so this is a Node.js dependency, not a uv/pip one, and isn't declared in pyproject.toml. Install it globally so docspan finds a real binary instead of falling back to npx (which re-fetches on every render):

npm install -g @mermaid-js/mermaid-cli   # tested against 11.x; older 10.x should also work

If Puppeteer's headless Chrome cache gets corrupted (a truncated download, an interrupted npm install), renders fail with an error like Could not find chrome-headless-shell; re-fetch it with:

npx puppeteer browsers install chrome-headless-shell

Without mmdc installed and without network access for npx to fetch it on demand, a mermaid render failure is reported as a push warning, not a crash — see Limitations.

Quick start

1. Create markgate.yaml:

backends:
  google_docs:
    credentials_path: /path/to/service-account.json

mappings:
  - local: docs/design-doc.md
    backend: google_docs
    remote_id: YOUR_GOOGLE_DOC_ID
    direction: both

2. Set up authentication:

docspan auth setup google_docs
# or
docspan auth setup confluence

3. Push and pull:

docspan push                     # push all mappings
docspan pull                     # pull all mappings
docspan status                   # show mapping table

4. Resolve conflicts (if any):

docspan conflicts list
docspan conflicts resolve docs/design-doc.md --accept remote

Configuration (markgate.yaml)

backends:
  google_docs:
    credentials_path: /path/to/service-account.json  # or use env ACCOUNT_A_CREDENTIALS_PATH
  confluence:
    base_url: https://yourorg.atlassian.net
    username: you@example.com
    api_token: your-api-token  # or env CONFLUENCE_API_TOKEN

mappings:
  - local: docs/notes.md
    backend: google_docs
    remote_id: YOUR_GOOGLE_DOC_ID
    direction: both  # push | pull | both
  - local: docs/page.md
    backend: confluence
    remote_id: YOUR_CONFLUENCE_PAGE_ID
    direction: both

Note: markgate.yaml is gitignored by default because it may contain API tokens. Commit a markgate.yaml.example template alongside it.

Central config & XDG storage

By default docspan stores its config, sync state, and credentials under the XDG base directories, and a central config lets you register multiple projects by prefix and run docspan from anywhere.

$XDG_CONFIG_HOME/docspan/config.yaml     # central config (project registry)
$XDG_CONFIG_HOME/docspan/<prefix>/…      # cached OAuth token
$XDG_STATE_HOME/docspan/<prefix>/…       # sync state + base store, per project

Central config (~/.config/docspan/config.yaml):

default_prefix: design-docs
projects:
  design-docs:
    markgate: ~/Documents/design-docs/markgate.yaml

Register and use projects:

docspan config add design-docs ~/Documents/design-docs/markgate.yaml   # register (prefix → markgate.yaml)
docspan config show                                                    # list projects + active resolution
docspan push --prefix design-docs                                      # or DOCSPAN_PREFIX, or default_prefix, or cwd match
docspan migrate-xdg --prefix design-docs                               # move legacy in-repo state to XDG + register

Prefix resolution order: --config PATH (legacy — storage stays beside the file) → --prefix → DOCSPAN_PREFIX → cwd inside a registered project → default_prefix. If nothing matches, docspan falls back to a local ./markgate.yaml with beside-the-file storage (fully backward-compatible).

Command Reference

Full reference — every command's arguments, options, and behavior — is generated straight from the CLI's source at docs/commands.md, so it can't go stale here. Build it locally with pip install docspan[docs] && mkdocs serve. Quick summary:

Configuration Reference

backends.google_docs

Auth resolution order: credentials_path → ACCOUNT_A_CREDENTIALS[_PATH] env → per-user OAuth (oauth_client_secret_path, or an already-cached token_path).

Environment variable alternatives (service account):

• ACCOUNT_A_CREDENTIALS_PATH — path to service account JSON
• ACCOUNT_A_CREDENTIALS — inline service account JSON string

backends.confluence

Environment variable alternatives:

• CONFLUENCE_BASE_URL
• ATLASSIAN_USER_NAME
• CONFLUENCE_API_TOKEN

mappings[]

State Files

docspan generates these files in your project directory after first sync:

Commit .markgate-state.json, .markgate-base/, and {file}.mermaid-cache.yaml — do not gitignore them. .markgate-state.json/.markgate-base/ need to be shared for three-way merge to work across machines/teammates; {file}.mermaid-cache.yaml is what makes mermaid-fence recovery work across machines at all (Google Docs has no API-writable place to store a diagram's source, only the rendered image — see mermaid_cache_sidecar.py's module docstring for why). {file}.orig and {file}.comments.md are transient/informational and safe to gitignore if you prefer.

Known Limitations

License

MIT. See LICENSE for details.

For contribution guidelines, see CONTRIBUTING.md. For the full change history, see CHANGELOG.md.