text2confl

Publish docs written in structured text formats (Markdown, AsciiDoc) to Confluence (Server/DC and Cloud).

If this project helps you

Please ⭐ star this repo — it helps other people discover the tool and motivates further maintenance.

Why text2confl

text2confl focuses on turning docs-as-code (or any structured text) into a Confluence page tree:

• Works with Confluence Cloud and Confluence Server/Data Center
• Supports Markdown and AsciiDoc (and lets you mix formats in one documentation set)
• Tries to provide good feature coverage for the chosen markup language, mapped to Confluence capabilities
• Supports extensibility/customization (e.g., adding macros) so you don’t need to fork for common needs

Documentation

New to text2confl? Start with the first upload guide for your deployment:

• 🚀 Confluence Cloud — yoursite.atlassian.net
• 🚀 Confluence Data Center / Server — self-hosted

Doing a specific task? See the how-to guides:

• 🔒 Authenticate with Confluence
• ⬆️ Ad-hoc upload · Run with Docker
• ⬇️ Export a Confluence page to Markdown
• 📁 Use virtual pages · Manage orphaned pages
• 🏢 Configure multi-tenancy

Looking up options? See the reference:

• ⚙️ Configuration reference
• 📝 Markdown syntax · 📜 AsciiDoc syntax
• 📄 Page attributes · Image attributes · Code blocks

Want to understand how it works? See the explanations:

• 🔍 How publishing works
• 📚 Storage formats — Markdown vs AsciiDoc
• 🧠 Change detection strategies

Contributing:

• 🤝 Contributing guide
• 🚧 Contribution notes

Try it with this repo’s docs

You can publish text2confl’s own documentation to your Confluence to see the tool in action. Pick a space and a parent page under which the pages will be created:

# from the root of the checked out text2confl repo
text2confl upload --docs ./docs \
  --confluence-url https://wiki.example.org \
  --user bob \
  --password secret_password \
  --space DOCS \
  --parent "Text2Confl test"

Example resulting page tree:

Note on a public docs showcase: At the moment there is no public Confluence demo because Confluence Cloud free tier doesn’t allow publishing spaces/pages to non-members. If you’d like to sponsor a public demo space or provide access for a read-only showcase, please open an issue.

Who’s using text2confl

If your team uses text2confl, consider adding your company/project name here. It helps show that the tool is used in real setups.

• Your company / project

To get listed, open a PR that adds a bullet to this section. If you prefer not to do that publicly, you can also open an issue/PM to me and I’ll add it for you.

Scope

text2confl does not assume the purpose of the publishing process or the type of content you are going to upload. It can be formal docs managed as code, a to-do list, or a report generated from Jira.

Because of that there isn’t a strict “final” feature set. If you find something missing, please create an issue and describe your needs.

Design and usability goals

Key principles the tool tries to follow:

1. Provide good feature coverage for every supported source format. If you pick AsciiDoc, it should feel comfortable, not like you constantly hit unsupported features.

   Note: features still need to map to Confluence formatting or macros.

2. Provide reasonable defaults and auto-detection where possible (e.g., Cloud vs Server editor differences).

3. Support both Confluence Server/Data Center and Cloud and be aware of differences in editors/features.

4. If the source format supports extensibility/customization, support it. There should be no need to fork just to add common macros.

Supported source formats

• ✅ Markdown
• ✅ AsciiDoc