A tried and test approach is to write docs in Asciidoc, version control them in Bitbucket (or other version control system), and publish the pages to Confluence via Confluence Publisher.

https://confluence-publisher.atlassian.net/wiki/spaces/CPD/overview?homepageId=315719687

This approach works amazing well (for me and others).

You might want to give our commercial app Include Bitbucket for Confluence a try.

It provides a Confluence macro to render AsciiDoc files stored in Bitbucket within Confluence pages.

With that, you have a version-controlled single source of truth, while still being able to render technical documentation with AsciiDoc in Confluence.

In case you decide to try the app and are missing a feature, please let us know in our Jira.

It would be great make use of the attributes in asciidoc to supply the metadata required for Confluence.

+1

metoo

This ticket is still stuck in Gathering Interest. How many votes does it need?

A great first step (For us) would be to have asciidoc as an export format. This would give us the ability to maintain our wiki documentation as code without losing comments/talk/etc. As we do when we use tooling like confluence-publisher. We have now started using WebDAV with a small toolkit (https://github.com/bougyman/confluential) To bridge the gap, But none of the XML/XHTML to asciidoc converters we've seen allow us to preserve <ac:structure-macro ... /> blocks at this time, so we have to do some juggling to keep that content in sync. Ideally, we'd have a system which allowed authors who wish to use the web editor the ability to do that, as well as use the talk/discussion/comment links, while authors who prefer to use asciidoc, or for developers to publish their asciidoc code documentation, directly to the wiki without clobbering those things. If confluence had an 'export to asciidoc' functionality, we could achieve this nirvana with our current tooling plus a small bit of extra glue. 

Agreed. Our use case is to write documentation using ASCIIDOC next to the source code which is under version control in Bitbucket (git) - for architectural or library user documentation.

Our maven build will generate the documentation on each build.

Confluence should include the documentation (when rendered to HTML) based on the release branch (usually master).

Idea is to easily create sites with links to develop docs or even feature docs.

So it isn't actually the support of asciidoc in confluence per se, as this still wouldn't offer source control (compared to the meaningless site history) but to be able to include external documentation.

The initial suggestion with having full integration of an external cvs for asciidoc documentation for several projects looks sexy but we would want to have documentation next to the actual source code.

I hope that makes sense. If not, I'm happy to clarify.

Here is an adapted user macro (originally from Jared Morgan, see above) that works for me. Replace http://*myserver* with your server / location of asciidoctor javascript and css fies.

## Macro name: adoc
## Macro title: AsciiDoc Markup with Asciidoctor
## Categories: Formatting
## Description: Display content in AsciiDoc format using the asciidoctor.js engine.
## Visibility: to all users
## Icon URL: https://raw.githubusercontent.com/norganna/adoc-usermacro/master/adoc.png
## Documentation URL: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
## Macro has a body: Y
## Body processing: Unrendered
## Generates: HTML
##
## @noparams
##
## Developed by: Ken Allan (https://github.com/norganna)
## Date created: 2015-09-02
## Modified by Stefan Eidelloth

## You can select whether to use the Foundation AsciiDoctor style, which will make articles look different to standard confluence styles, or leave it as is if
##you want to achieve something closer to the standard Confluence styling by setting the following to either "confluence"  or "foundation":
#set($style="confluence")

## A handy macro to generate a new random ID between 0 and maxint each time you call it:
#set ($randomId="")

#macro(getRandomId)
#set ($string="")
#set ($rand=$string.class.forName("java.util.Random").getConstructor().newInstance())
#set ($randomId=$rand.nextInt(2147483647).toString())
#end

#getRandomId()
<div id="adoc-content-$randomId" class="adoc-content">
</div>

#if($style == "confluence")
<link type="text/css" rel="stylesheet" href="http://**myserver**/adoc-confluence.css" media="all">
#else
##<link type="text/css" rel="stylesheet" href="http://**myserver**/adoc-foundation.css" media="all">
#end

## This CSS is the FontAwesome font which enables the admonition icons.
<link type="text/css" rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css" media="all">

##reference to asciidoctor.js
<script src="http://**myserver**/asciidoctor.min.js">
</script>

##reference to mathjax.js
<script type="text/x-mathjax-config">
	  MathJax.Hub.Config(\{
		extensions: ["tex2jax.js"],
		jax: ["input/TeX", "output/HTML-CSS"],
		tex2jax: {
		  inlineMath: [ ['$','$'], ["\\(","\\)"] ],
		  displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
		  processEscapes: true
		},
		"HTML-CSS": \{ fonts: ["TeX"] }
	  });
	</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js">

<script>
jQuery(function() \{

    var asciidocContent= $jsonator.convert($body).serialize();

    var asciidoctor = Asciidoctor();
   
    var asciidoctorOptions = {          
            safe: 'safe'           
     };      

    var renderedHtmlOutput = asciidoctor.convert(asciidocContent, asciidoctorOptions);

    jQuery('#adoc-content-$randomId').html(renderedHtmlOutput);

});
</script>

This is the sole reason my documentation has not made it into confluence. Such a pain to wait for the admins to get around to maybe installing or enabling a plugin.

Please add support for Markdown and Asciidoc, natively. Confluence is going to be a second, third, or fourth class doc platform without support for the de facto doc languages –
provided out-of-the-box by most every other tool in the industry.

Or try https://github.com/norganna/adoc-usermacro to use AsciiDoc directly on a confluence page.

I'm experimenting with safe mode to allow content to be sucked into the page from raw GitHub or Stash repos.

It's free and open source