confluence-push-doc

Confluence — Push Document

Goal

Publish or update a local planning artifact (PRD, architecture doc, backlog, etc.) as a Confluence page with proper formatting and version metadata.

---

Prerequisite Check

Check integrations.confluence in config. If missing: "Run confluence-connect first."

---

Step 1: Select Document

Ask: "Which document do you want to push?"

#	Document	Path
1	PRD	{planning_artifacts}/prd/
2	Architecture	{planning_artifacts}/architecture/
3	Backlog	{planning_artifacts}/epics-stories/
4	Product Brief	{planning_artifacts}/briefs/
5	Sprint Plan	{implementation_artifacts}/sprints/
6	Other (specify path)

---

Step 2: Check if Page Already Exists

curl -s \
  "{confluence_url}/rest/api/content?title={encoded_title}&spaceKey={space_key}" \
  -u "{email}:{api_token}" \
  -H "Accept: application/json" | python3 -c "
import sys, json
results = json.load(sys.stdin)['results']
if results:
    print('EXISTS', results[0]['id'], results[0]['version']['number'])
else:
    print('NEW')
"

---

Step 3: Convert Markdown to Confluence Storage Format

Convert key markdown patterns:

• ## Heading → <h2>Heading</h2>
• Markdown tables → <table> format
• Code blocks → <ac:structured-macro ac:name="code">
• Mermaid diagrams → render as a code block with note "Diagram source — render with Mermaid"
• **bold** → <strong>bold</strong>

Build the body as Confluence Storage Format XML.

---

Step 4: Create or Update Page

Create new page:

curl -s -X POST \
  "{confluence_url}/rest/api/content" \
  -u "{email}:{api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "page",
    "title": "{page_title}",
    "space": { "key": "{space_key}" },
    "ancestors": [{ "id": "{parent_page_id}" }],
    "body": {
      "storage": {
        "value": "{escaped_html_content}",
        "representation": "storage"
      }
    }
  }' | python3 -c "import sys,json; d=json.load(sys.stdin); print('Created:', d.get('id'), d.get('_links',{}).get('webui',''))"

Update existing page (increment version):

curl -s -X PUT \
  "{confluence_url}/rest/api/content/{page_id}" \
  -u "{email}:{api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "version": { "number": {current_version + 1} },
    "title": "{page_title}",
    "type": "page",
    "body": {
      "storage": {
        "value": "{escaped_html_content}",
        "representation": "storage"
      }
    }
  }' | python3 -c "import sys,json; d=json.load(sys.stdin); print('Updated to version:', d['version']['number'])"

---

Step 5: Update Local Frontmatter

Add to the local document's frontmatter:

confluence_page_id: "{page_id}"
confluence_url: "{confluence_url}/wiki{webui_path}"
confluence_version: {version_number}
last_synced: {date}

---

Completion

"✅ Published to Confluence: {page_title} Version: {version}

The prd_version label is embedded in the page metadata so stories generated from this version can trace back to it."