Feature Summary

Support Asciidoctor-backed AsciiDoc in:

• the WYSIWYG editor,
• through Stash (see https://jira.atlassian.com/browse/STASH-4769)
• through the API directly.

The unicorns and rainbows solution I'm looking for here is to:

• Write my docs in AsciiDoc
• Version Control docs files in Stash
• Push directly to a confluence node using a "Publish" button. (OH YEAH)

But I'd honestly just settle for native AsciiDoc (Asciidoctor tooling) support in Stash and the API so I can push easily.

Challenge

For me, the way I"m using the Atlassian solution suite is using Stash and AsciiDoc together with Confluence to achieve that elusive writing Zen. That, and I want to single-source my content as much as possible for reuse among the documents I'm writing, and then push the end result to Confluence as a static page.

The problem is my Zen is being interrupted when I try to push AsciiDoc into Confluence.

In short: I can't.

Attempted Workarounds

As there is no support natively at the moment, I need to use 3rd party Ruby tools to attempt to push content in, but these tools are not really working out (due to enhancements required to these tools - bugs raised).

When that fails, I need to transform my AsciiDoc files using Asciidoctor and then try to push the HTML directly into the code view of the Editing Window. The problem with that is due to the admonition macros and other rich content stuff Confluence uses, the beautiful Foundation styles and eye-pleasing Admonition blocks are changed to the Confluence style, and look amateurish. Which makes me look amateurish as a Technical Writer.

One of my DevOps guys has offered to create a buildbox that houses all the Ruby stuff I need to push static HTML into Confluence and listens on Stash Commit Hooks, but that seems overly complex when it would be better to just support AsciiDoc alongside Markdown.

Final Summary

Most professional TechComms professionals will tell you that separating content from presentation is the way to writing Zen. Probe Technical Writers further and they'll probably start talking about ways they use a VCS to control their documentation and manage content reuse.

AsciiDoc is the type of language that Tech Writers use when they are faced with creating complex douments. Many Markdown syntax items (such as admonitions) are a kludge-fest to get working compared to AsciiDoc, and having to do this make Tech Writers stabby and makes their teeth itch.

Please, help Tech Writers work efficiently and effectively using the Atlassian stack of products in a writing language that supports their advanced writing needs.