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

Quick start

If you want to quickly see how text2confl works, you can upload the documentation of this repository to your own Confluence. 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.

Documentation

Start here:

• User guide: 📖 User guide
• Configuration reference: ⚙️ Configuration reference

Deep dives / feature docs:

• Storage formats:
  • 🔍 Overview
  • 📝 Markdown
  • 📜 AsciiDoc
• Working with attributes:
  • 📄 Page attributes
  • 🖼️ Image attributes
  • 📌 Table of contents (ToC) attributes
• Content tweaks:
  • 🔧 Auto-fix content
  • 💻 Code blocks
  • 🎨 Table colors
  • 📏 Table width
• Advanced usage:
  • 📁 Virtual pages
  • 🏢 Multitenant setups
  • 🧹 Pages cleanup

Contributing:

• 🤝 Contributing guide
• 🚧 Contribution notes

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