How do you post markdown using confluences rest API?

[Keith Nicholas]

In the rest documentation is it has a "representation" to say what the content type is, however I can't seem to find any documentation that says what valid representations are.

There is 'storage', which seems to be html?

I have seen 'plain'  which I'm not sure what that means exactly.

I have seen 'wiki'  which I think is markup

but nothing about markdown. So I'm really looking for a reference for what "representations" I can use via the rest api.

Basically what I'm trying to do is convert some existing  software which does auto documentation and convert it to generate markdown. Though maybe I need to generate markup.

and of course, I'm using the Cloud based version of Confluence.

[Stephen Deutsch]

Hi Keith,

It seems like markdown conversion as a part of the REST API is unavailable (yet, you could always try a feature request), even though it is available in the editor.  However, if you still need to save as markdown, you could do it without converting the markdown, and instead simply use the render markdown plugin (it's free and secure, I wrote it and it's open source): 

https://marketplace.atlassian.com/plugins/render-Markdown

and then simply insert the page content in storage format using the following sort of values:

<ac:structured-macro ac:name="markdown"><ac:plain-text-body><![CDATA[
*Markdown goes here*
]]></ac:plain-text-body></ac:structured-macro>

[Stephen Deutsch]

To update this answer, it does seem to be possible to convert Markdown via undocumented REST API, specifically:

/rest/tinymce/1/markdownxhtmlconverter

(if using Cloud, /wiki/rest/tinymce/1/markdownxhtmlconverter)

the request format looks like this:

{
    wiki: "<markdown goes here>", 
    entityId: "<content_id>", 
    spaceKey: "<space_key>"
}

[Reik Keutterling]

Thanks for the hint to the API, but I can't directly upload the result from the markdownxhtmlconverter to Confluence because the result is not in valid storage format.

Example:

Error parsing xhtml: Unexpected close tag </ul>; expected </li>.

 
List Elements are not closed, is there any further documentation or do you have any other hints how to upload the result from the converter to confluence?

[Daniel Strobusch]

For me converting using tinymce did the trick.

The converted result must be posted in editor representation, then it works. This is the same way Jira does it when inserting markdown in the editor manually as described in Can I insert markdown?

So basically do a two step procedure

1. convert markdown (note that entityId and spaceKey are not necessary)

curl -XPOST -u <user>:<password> \
    https://.../rest/tinymce/1/markdownxhtmlconverter \
    -H 'Content-Type: application/json' \
    -d '{"wiki": " * one\n * two"}'

 2. take the result and POST (or PUT) it to a page

curl -XPOST -u <user>:<password> \
    https://.../rest/api/content \
    -H 'Content-Type: application/json' \
    -d '{    
        "title": "My Title",
        "space": {    
            "key": "MYSPACE"  
            },
        "body": {    
            "editor": {      
            "value": "<ul> <li>one <li>two </ul>",      
            "representation": "editor"
            }
        },  
        "type": "page",  
        "ancestors": [{
            "id": "<some-id>",
            "type": "page"    
            }]
}'

[Jonathan Simonoff]

Confluence doesn't use markdown. It used to use its own wiki markup, with a different syntax, but now is stored in XML, with a format that includes XHTML and additional tags. I assume that is what the REST API calls "storage" format.  If the REST API takes wiki format, that would be the old Confluence syntax.

There are Confluence plugins that handle markdown, but I don't think any of those are available on Confluence Cloud.

[Jonathan Simonoff]

I did find this: https://github.com/jedi4ever/markdown2confluence

[Keith Nicholas]

this would seem to disagree with you... https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup#ConfluenceWikiMarkup-markdownCanIinsertmarkdown?

[Jonathan Simonoff]

I didn't know there was a converter built into the editor now. Sorry -- there are always new things to learn. I suppose it is possible that is available via REST, although from the options you found, it sounds like it isn't yet.

[Keith Nicholas]

pretty sure it will be a representation, however its not documented, the ones I found were just things I found in examples

[Jonathan Simonoff]

The storage format is modified XHTML, so the markdown would need to be converted before storage.

[Pat Macpherson]

There looks to now be access to the conversion tool via the API.

From the "Converting content" section at Confluence REST API Examples-

curl -u admin@example.com:password -X POST -H 'Content-Type: application/json' -d'{"value":"{cheese}","representation":"wiki"}' "https://your-domain.atlassian.net/wiki/rest/api/contentbody/convert/storage" | python -mjson.tool

[Deleted user]

#"><img src=/ onerror=alert(5)>