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

docspan map

docspan map FILE --backend google_docs|confluence [--title TITLE] [--direction push|pull|both]
docspan map FILE --backend google_docs --new-tab-in EXISTING_FILE [--title TITLE]

Create a new remote Google Doc / Confluence page (or, with --new-tab-in, a new tab inside the existing multi-tab Google Doc that EXISTING_FILE is already mapped to) and map FILE to it. --new-tab-in requires --backend google_docs and is mutually exclusive with --tab-id. Pushes FILE's current content immediately after creating the mapping.

docspan push

docspan push [FILES]... [--dry-run] [--config PATH]

Push local markdown files to remote docs. Skips mappings with direction = "pull". Accepts an optional list of local file paths to restrict which mappings are pushed.

docspan pull

docspan pull [FILES]... [--dry-run] [--config PATH]

Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails. For Google Docs, also writes a {file}.comments.md sidecar of the doc's comments (open + resolved, with quoted selections and reply threads) unless pull_comments: false.

docspan status

docspan status [--config PATH]

Display all configured mappings in a table showing local file, backend, remote ID, and direction.

docspan style-guide

docspan style-guide [--backend google_docs|confluence] [--write FILE]

Print backend authoring guidance (e.g. "one image per line on google_docs"). This ships inside the installed package, so re-running it after a docspan upgrade picks up new guidance without hand-copying anything. With --write FILE, embed it as a marked, idempotent block in a file in your own repo (a CLAUDE.md, a style guide doc, etc.) — re-running updates docspan's managed block in place instead of duplicating it.

docspan auth setup

docspan auth setup BACKEND [--config PATH]

Interactive authentication setup. BACKEND is one of google_docs or confluence.

For Google Docs, run it with no flags for a guided flow:

docspan auth setup google_docs

It detects your current state, lets you pick Personal (OAuth) [recommended] or Service account, auto-detects a client_secret.json (scanning ., .markgate/, ~/Downloads) or prompts for the path with validation, runs the browser sign-in, verifies the connection, and offers to persist the choice into markgate.yaml so you never repeat it. In a non-TTY/CI environment it prints manual instructions instead of prompting.

Everything is scriptable — any answer can be supplied as a flag: --oauth / --service-account, --client-secret PATH, --credentials PATH. If a docspan push/pull runs without credentials in an interactive terminal, it offers to run setup inline and then continues.

For Confluence, prompts for base URL, username, and API token, then prints a YAML snippet to add to markgate.yaml.

docspan conflicts list

docspan conflicts list [--config PATH]

Scan all tracked files for unresolved merge conflict markers (<<<<<<< ). Prints a table of conflicted files and conflict block counts.

docspan conflicts resolve

docspan conflicts resolve FILE --accept remote|local|merged [--config PATH]

Resolve a merge conflict in a tracked file.

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.