Confluence

Confluence is Atlassian’s enterprise wiki and documentation platform. typub supports publishing to Confluence Cloud via the REST API with Basic authentication.

Capabilities

Feature	Support
Tags	Yes (maps to labels)
Categories	No
Internal Links	Yes
Draft Support	Reversible (status field: `current` vs `draft`)
Math Rendering	LaTeX (via ADF extension) or PNG (attachments)
Local Output	No

Asset Strategies

Strategy	Supported	Default	Notes
`upload`	Yes	*	Upload as page attachments
`embed`	No		Not supported
`external`	No		Not supported
`copy`	No		Not supported

Prerequisites

Confluence Cloud instance (Server/Data Center may work but is not tested)
Personal Access Token or API token for authentication
(Optional) LaTeX Math plugin for formula rendering

Authentication

Confluence Cloud uses Basic authentication with your email and an API token.

Step 1: Create an API Token

Go to Atlassian Account Settings
Click Create API token
Give it a label (e.g., “typub”)
Copy the generated token

Step 2: Configure typub

[platforms.confluence]
base_url = "https://your-company.atlassian.net"  # Your Confluence URL
default_space = "DOCS"                            # Default space key
email = "you@example.com"                         # Your email (or use CONFLUENCE_EMAIL env var)
api_key = "your-api-token"                        # API token (or use CONFLUENCE_API_KEY env var)

Environment Variables:

export CONFLUENCE_EMAIL="you@example.com"
export CONFLUENCE_API_KEY="your-api-token"

Security Warning: Never commit API tokens to version control. Use environment variables instead.

LaTeX Math Rendering

Confluence supports two math rendering strategies:

Option 1: LaTeX via ADF Extension (Recommended)

Uses the Appfire LaTeX Math plugin with Atlassian Document Format (ADF) extensions. This provides native LaTeX rendering without image attachments.

Prerequisites:

Install the LaTeX Math for Confluence app from Atlassian Marketplace
Get the App ID and Environment ID from the app configuration

Configuration:

[platforms.confluence]
math_rendering = "latex"           # Use LaTeX rendering
latex_math_app_id = "your-app-id"  # From Appfire app configuration
latex_math_env_id = "your-env-id"  # From Appfire app configuration

To find your App ID and Environment ID:

In Confluence, use the LaTeX Math macro in a page
Open the browser’s developer tools (F12) → Network tab
Insert a LaTeX formula and look for API calls
The App ID and Environment ID appear in the request URLs

Alternatively, contact your Confluence administrator or check the app’s configuration in Settings → Apps → Manage apps.

Note: When the app ID and env ID are not provided, the LaTeX rendering backend would fall back to use the traditional ac macros, which are going to be deprecated and may not work as expected.

Option 2: PNG Attachments

Render math formulas as PNG images and attach them to the page. This works without any plugins but produces image-based formulas.

[platforms.confluence]
math_rendering = "png"

Generated PNG files are stored in your content’s assets/ folder and uploaded as attachments.

Usage

# Preview content
typub dev posts/my-post -p confluence

# Publish to Confluence
typub publish posts/my-post -p confluence

Confluence Published

Post Configuration

Space Selection

Specify which Confluence space to publish to:

# In your post's meta.toml
[platforms.confluence]
space = "ENG"  # Override default space
parent_id = "123456"  # Optional: parent page ID for hierarchical structure

Note: parent_id only applies when creating new pages. If the page already exists, updating content will not change its parent location. This prevents accidental page moves during content updates.

Labels (Tags)

Tags are automatically synced as Confluence labels:

# In your post's meta.toml
tags = ["rust", "tutorial", "api"]

Label normalization rules:

Converted to lowercase
Special characters replaced with hyphens
Maximum 255 characters
Duplicates removed

Draft Mode

Confluence supports draft mode via the published field:

[platforms.confluence]
published = false  # Creates/updates as draft

published = true: Page status is current (visible to readers)
published = false: Page status is draft (hidden from readers)

You can toggle this at any time.

Asset Handling

All images are uploaded as page attachments. The adapter uses Confluence’s attachment API with deduplication:

Images are uploaded with their original filename
If an attachment with the same name exists, it’s replaced
Image references in content are resolved to attachment URLs

Image Caption and Alt Mapping

For a single-image figure, typub maps figcaption to Confluence <ac:caption> on <ac:image>
Image alt is mapped to ac:alt (accessibility/metadata), not visible caption
If no figcaption exists, typub does not promote alt into <ac:caption>