# mdcx

Markdown to Confluence XML converter with bidirectional sync support for self-hosted Confluence Server/Data Center.

Converts Markdown to [Confluence storage format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html) XML and back. Supports pulling pages from Confluence, editing locally as Markdown, and pushing changes back — with template-aware embedding that preserves metadata tables, changelogs, and inline comment markers.

## Install

```bash
go install sourcecraft.dev/bigbes/markdown-to-confluence-xml@latest
```

The binary is named `mdcx`.

## Commands

### `convert` — Markdown to Confluence XML

```bash
mdcx convert input.md -o output.xml
cat input.md | mdcx convert > output.xml
```

### `embed` — Embed Markdown into a Confluence XML template

Converts Markdown and inserts it between marker comments in an existing Confluence document, preserving everything outside the markers (metadata table, TOC, changelog, etc.).

```bash
mdcx embed input.md --template template.xml -o output.xml
```

The template must contain marker comments:

```xml
<!-- MD_CONTENT_START -->
<!-- MD_CONTENT_END -->
```

### `extract` — Extract Markdown from Confluence XML

Extracts content between markers and converts back to Markdown.

```bash
mdcx extract input.xml -o output.md
mdcx extract input.xml --raw  # output raw Confluence XML
```

### `pull` — Pull a page from Confluence

```bash
mdcx pull "https://confluence.example.com/pages/viewpage.action?pageId=12345" -o page.md
mdcx pull "https://confluence.example.com/display/TEAM/Page+Title" -o page.md
mdcx pull "https://confluence.example.com/display/TEAM/Page+Title" --raw -o page.xml
```

### `push` — Push Markdown to a Confluence page

```bash
# Replace entire page body
mdcx push "https://confluence.example.com/display/TEAM/Page+Title" page.md

# Template mode: replace only content between markers
mdcx push "https://confluence.example.com/display/TEAM/Page+Title" page.md --template

# With version message
mdcx push "https://confluence.example.com/display/TEAM/Page+Title" page.md -m "Updated intro section"
```

## Authentication

For `pull` and `push`, provide a [Personal Access Token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) via:

- `--token` flag, or
- `CONFLUENCE_TOKEN` environment variable

```bash
export CONFLUENCE_TOKEN="your-token-here"
mdcx pull "https://confluence.example.com/display/TEAM/RFC-42" -o rfc.md
```

## Typical workflow

```bash
export CONFLUENCE_TOKEN="..."

# Pull page to local Markdown
mdcx pull "https://confluence.example.com/display/TEAM/RFC-42" -o rfc.md

# Edit locally
vim rfc.md

# Push back, preserving template structure
mdcx push "https://confluence.example.com/display/TEAM/RFC-42" rfc.md --template -m "Updated requirements"
```

## Supported elements

| Markdown | Confluence XML |
|---|---|
| `# Heading` | `<h1>` ... `<h6>` |
| `**bold**` | `<strong>` |
| `*italic*` | `<em>` |
| `~~strike~~` | `<del>` |
| `` `code` `` | `<code>` |
| Fenced code blocks | `<ac:structured-macro ac:name="code">` with CDATA |
| `- item` / `1. item` | `<ul>/<ol>` with `<li>` |
| Nested lists | Nested `<ul>/<ol>` inside `<li>` |
| `- [x] task` | `<ac:task-list>` / `<ac:task>` |
| `[text](url)` | `<a href="...">` |
| `![alt](url)` | `<ac:image><ri:url .../>` |
| `> blockquote` | `<ac:structured-macro ac:name="info">` (info panel) |
| `---` | `<hr/>` |
| GFM tables | `<table>` with `<th>/<td>` wrapped in `<p>` |
| Inline comment markers | Preserved via `<span data-inline-comment="ref">` in Markdown |

## Inline comment preservation

Confluence inline comments (`<ac:inline-comment-marker ac:ref="UUID">`) are preserved through round-trips. In Markdown they appear as:

```html
<span data-inline-comment="b2f6ce98-4dc9-...">commented text</span>
```

This is converted back to proper `<ac:inline-comment-marker>` tags when pushing to Confluence.

## License

MIT