Import markdown into Confluence
Asked by Jason Haines:

According to the Confluence documentation on [http://Importing Content Into Confluence](https://confluence.atlassian.com/conf51/importing-content-into-confluence-336169436.html), there is no supported way of importing markdown. Is this the case?

3rd party solutions seem not to work with current, self-hosted versions.


Answers:
author: Sharon Tan
body: Hi there, appreciate everyone's input on this. I'm adding some clarification on what's possible OOTB today with Confluence.

**Confluence Cloud:**

Our Confluence Cloud editor (sites hosted on atlassian.net) supports markdown on the fly, so text with markdown formatting that is pasted directly into the editor will be converted. You can see more on supported markdown in [Confluence's keyboard shortcuts](https://support.atlassian.com/confluence-cloud/docs/keyboard-shortcuts-markdown-and-autocomplete).

We don't yet offer a plain text markdown editor so you can edit in markdown, but we're tracking interest on our feature request, [Edit in Markdown with the new editor](https://jira.atlassian.com/browse/CONFCLOUD-68272) for Confluence Cloud.

**Self-hosted:**

With self-hosted Confluence, this can be done OOTB with the [Markup macro](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) (select Insert \> Markdown from the drop-down).

You also have the option of adding a Marketplace app - [Markdown Macro for Confluence](https://marketplace.atlassian.com/apps/1211438/markdown-macro-for-confluence?hosting=server&tab=overview) is a free one, but you can browse apps specific to Confluence [Server](https://marketplace.atlassian.com/search?hosting=server&product=confluence&query=markdown) and [Data Center](https://marketplace.atlassian.com/apps/1211445/markdown-for-confluence?hosting=datacenter&tab=overview) in addition.

As for native support in self-hosted Confluence, we're collecting feedback at our feature requests for:

* [Native Markdown Support](https://jira.atlassian.com/browse/CONFSERVER-55637)
* [Bulk Import Markdown Files](https://jira.atlassian.com/browse/CONFSERVER-59543)

Along with a bug that has since been resolved as of Confluence 6.14 and up:

* [Markdown converter in Confluence does not handle Indentation correctly](https://jira.atlassian.com/browse/CONFSERVER-56442)

You can see how feature requests are considered in our [New Features Policy](https://confluence.atlassian.com/support/implementation-of-new-features-policy-201294576.html).

comments: author: Daniel Carter
body: When i paste markdown into a new confluence page, it creates a code block and does no conversion  

![Screenshot from 2021-11-19 15-50-07.png](https://community.atlassian.com/t5/image/serverpage/image-id/170109iECD2C164BF0D9FF6/image-size/large?v=v2&px=999 "Screenshot from 2021-11-19 15-50-07.png")


author: Daniel Carter
body: Or if i Ctrl+Shift+V, it pastes as plain text instead of a code block, but again no markdown conversion. This is on the cloud version

![Screenshot from 2021-11-19 15-53-19.png](https://community.atlassian.com/t5/image/serverpage/image-id/170110i173A4704932ECBC0/image-size/large?v=v2&px=999 "Screenshot from 2021-11-19 15-53-19.png")


author: Stig Grafsr?nningen
body: Same here. Extremely simple cases work but no where anything useful.


author: tanner.stirrat
body: It's also not correct when it comes to whitespace.

If I write a

paragraph like

this, adding whitespace

in the source document,

in markdown, all of the above gets treated and formatted as a single paragraph, eliding the whitespace in the same way that HTML does. If you paste into confluence, it doesn't do that. This is really frustrating.


author: John Kramer
body: This doesn't really solve the problem. These shortcuts are handy but I have multiple pages in markdown that I would like to import. There appears to be no option. And if you cut and paste, the keyboard shortcuts aren't recognized.


author: Nar Kumar C. - Narva Software
body: Hi everyone,

If you have trouble using Markdown in Confluence default editor, checkout our new app: [**Markdown for Confluence - Native Markdown Editor**](https://marketplace.atlassian.com/apps/1231324/markdown-for-confluence-native-markdown-editor?hosting=cloud&tab=overview&utm_source=community&utm_medium=referral&utm_content=211797)

<br />

This app has alternative Markdown editor where you can paste Markdown and edit the existing pages using Markdown.

Sidenote: Sharon, maybe you could add our app in the Confluence Cloud section above?


author: tanner.stirrat
body: This isn't going to be a solution for everyone. It being a third-party application means that it needs to be reviewed by our (already-stretched) security team, and it may or may not receive approval. There are also probably companies that can't use third-party applications at all.


author: a4z
body: in days where markdown is basically the goto language for documentation of developers, not supporting it is insane.

Everyone here around me hates confluence, our devs write docs in markdown or, preferably, asciidoctor.

The management insists of having documents in confluence. And no, we can not install addons since this is done by different division/people and it requires process no one wants to go. A quite common situation.   
So guess what, confluence gets more and more negative feelings. All the mentioned work arounds are crap. It seams Atlassian is on a suicide trip by making developers hating their solution.

comments: author: Michael Uman
body: I agree. In our organization we have some users who like Confluence and we are keeping some of our documents there. The problem is much of my work includes documents using Markdown format. I find it hard to believe that Markdown is not supported out of the box.

Michael Uman  
Lead S/W Engineer  
Wunder-Bar


author: Colin_Puttick
body: What other app would your developers recommend?


author: a4z
body: for devs,

something like <https://antora.org/> with asciidoctor  
or some home made stuff

or sphinx, with rst docs, python devs like it

then there is the 'just add markdown' to the wiki (github / lab have wikis)

whatever allows to write doc without to leave the IDE/editor currently in use


author: Colin_Puttick
body: Thank you. I don't think Alassian is for us. Too big bloated and crazy to get going here. We're on readme.io but have outgrown it. I'll take a look Antora and Sphinx. :)


author: Miles Maddox
body: This solution may not work for everyone, but I wrote a tool to do just this. It takes a markdown file and uploads it to confluence. I use it to sync my notes daily. It's not perfect, but it works: <https://github.com/justmiles/go-markdown2confluence>  

comments: author: Laurent Hoss
body: Another importer script, written in Python (haven't tested yet): <https://github.com/RittmanMead/md_to_conf>


author: boardtc
body: There are a number of ways.

A. To insert markdown in the editor:

1. Choose Insert \> Markup
2. Select Markdown
3. Type or paste your text - the preview will show you how it will appear on your page
4. Choose Insert.

B. Use the Mardown macro which renders Markdown from a URL

C. Use HTML Macro

1. Use [pandoc](https://pandoc.org/getting-started.html) to convert your markdown file to html
   * e.g. pandoc myfile.md -f markdown -s -o myfile.html
2. On your confluence page insert a [HTML macro](https://confluence.atlassian.com/conf66/html-macro-943962092.html) which allows the use of HTML code within a Confluence page.
   * Note that HTML macros are disabled by default.

comments: author: Rick Mann
body: This doesn't work at all for me. It just pastes my text as regular body text in the page, and removes a lot of whitespace. We're using Confluence hosted by Atlassian.


author: Alexis Tremblay
body: Me too. The preview is fine, but then it's just a big block of regular text.


author: Scott Webster
body: I get the same. Preview looks good, but text on actual page not rendered correctly. Example: inserted markdown has a '# HeadingExample'. Preview looks great. On the page, this is rendered as plain text 'h1. HeadingExample'.


author: Adrian C.
body: Same for me. Furthermore, the markup button doesn't work a second time and I have to clear my browser's "Local Storage" to be able to display it again.

But to no avail as even using it a second time accomplishes nothing.


author: Laurent Hoss
body: About A)

For me the Insert/Markup(Markdown) Macro sometimes works as expected, but sometimes \*not at all\* (maybe with too large contents, or missing new lines ??)

If it's not working, trying to fix it in the form also often fails (vs fixing in external editor, and re-copy\&pasting into the form)

IMO It would be great if that tool would be more powerful and robust. At least providing some 'reparse' button (in case the live editing is too tricky for large contents') or maybe it could give some hints, about issues detected while parsing the MD?!


author: Wes Waugh
body: The macro doesn't seem to exist anymore, neither does there exist an "Insert" menu anymore. When I copy \*some\* HTML from a page, some of it imports correctly, but things like \`abc_\*_foo\` turn into bullet points... And when I paste the whole content, the editor acts like the clipboard is empty.


author: Alan Kelly
body: works like a dream.

thanks you


author: Artjoms Suharevs
body: Mark up \> Markdown is it working at all? I mean quoting, code inserting, lists, tables e.t.c.?! Looks useless for anything more then simple headings.


author: JORDAN STEWART
body: I actually just copied, and pasted the rendered Markdown. Seems to work alright. The marcos were not working for me.

comments: author: Laurent Hoss
body: Indeed, copying the rendered Markdown (p.eg from VS-code "Markdown Preview") works \*quite\* well, BUT/except **code blocks** (rendered via \`\`\` code \`\`\` sections) are not properly migrated (just as normal text)

Does anybody know a way to also get code-blocks migrated (in a MD file)?


author: Joseph Gardner
body: I just copied the plain text of the markdown file into the editor, and it formatted it correctly. Have you tried that?

comments: author: ?ron Benk?czy
body: Ooooh gash, I found the problem. The visual studio code is forcing my text with some info to behave like a code. I copy and paste it to sublime text and paste it to Jira and it works perfectly!


author: Luke Wisniewski
body: If you copy markdown from VS Code and use Chrome or the Chromium based version of Edge, then you can right-click and choose "Paste as Plain Text"......contrary to how it sounds, it will render the markup correctly!


author: Roger Gordon
body: Simply pasting markdown into the document works for me as well.


author: Anthony -Shadow- Elmore
body: Hi, for everyone that has come to this topic looking for answers or wanting enhancements, it's been my experience that Atlassian doesn't prioritize work on feature requests unless there is an issue filed that generates community interest.  

But since their bug/issue tracking system is buried in their website, it may be hard to find. For Confluence Server in general, you can go here:  
<https://jira.atlassian.com/projects/CONFCLOUD/issues>

<br />

There is a separate project for Confluence Server, if that is what you are using but I think features tend to make it into the Cloud version first.  

I found an open Suggestion ticket here:

<https://jira.atlassian.com/browse/CONFSERVER-58265>  

Given that I have come across numerous Atlassian Community posts lamenting about this for several years, I think that there is significant demand that hasn't been given proper visibility to Atlassian.  

If you want this feature, please go vote for it.


author: hulius
body: If you have Notion, you can copy your markdown in it and then copy/paste it from Notion to Confluence.

comments: author: David Ventimiglia
body: No. You cannot, if the Confluence editor doesn't recognize and render the Markdown, which it often does not for people (even if sometimes it does for other people).


author: Ron Lusk
body: Using **pandoc** , I just converted a page of *Markdown* (exported from the *Notion* app) into **org-mode** (an Emacs organizer/markup/task-management/everything "app"), and then used an export module to export that page to JIRA (Confluence) format. I could then paste that into a comment.

I wouldn't recommend it as a regular thing, but it did the job in this case, and I'm fairly fluent in all three markup languages, so I could fix something if it broke along the way.


author: Brett Russ
body: Another option I found to workaround this wiki that doesn't support Markdown:

Paste the Markdown-formatted plain text in a new Jira ticket's description field with "Text" mode selected, then switch to the preview using the "Visual" mode and copy/paste this into Confluence's new page editor.

Similar to other workarounds, but uses Atlassian's own product. YMMV with other Jira variants, we have Server.

comments: author: Stuart Swain
body: Thanks Brett - this worked perfectly for me, and was definitely the least fuss.   

The way JIRA converts markdown is exactly the way Confluence ***should*** convert markdown...

EDIT:  
Well.. almost - links to locations in the same document don't appear to work.. grr.


author: Alexandra Shumway
body: Try copying from your code editor and using 'Paste and Match Style' in Confluence - it should do the trick!

My markdown is in VSCode and I have a new page created in Confluence open in Google Chrome. I did not install any plugins or add-ons to Confluence.

I was experiencing similar behavior to others above where pasting markdown from VSCode resulted in code blocks and the markdown was not converted. I tried cmd+shift+v as well which produced a text result that interpreted bullets in a single level list and that was pretty much the only thing that got converted.

However, I just found that I was able to paste in large amounts of markdown text into the Confluence editor with correct conversion of all elements by right clicking and selecting 'Paste and Match Style'.

As an example I've included several screenshots:

1 - My markdown in VSCode

![1-MD in VSCode.png](https://community.atlassian.com/t5/image/serverpage/image-id/198217iD26B4E4D10AFEB91/image-dimensions/338x278?v=v2 "1-MD in VSCode.png")

2 - Result of cmd+v ?

![2-cmd+v.png](https://community.atlassian.com/t5/image/serverpage/image-id/198218i47062BCFA6B19960/image-dimensions/273x294?v=v2 "2-cmd+v.png")

3 - Result of cmd+shift+v ?

![3-cmd+shift+v.png](https://community.atlassian.com/t5/image/serverpage/image-id/198220i02628CA5F191B955/image-dimensions/403x296?v=v2 "3-cmd+shift+v.png")

4 - Right Click Menu in Confluence editor

![4-Right Click Menu.png](https://community.atlassian.com/t5/image/serverpage/image-id/198219iC35AD503A96C431E/image-dimensions/282x236?v=v2 "4-Right Click Menu.png")

5 - Result of "Paste and Match Style" ?

![5-Paste and Match Style.png](https://community.atlassian.com/t5/image/serverpage/image-id/198221iC94CA6B3128520D7/image-dimensions/580x426?v=v2 "5-Paste and Match Style.png")

Hope this helps! This worked for my use case as I have just a few pages I need to import, and copying and pasting each page won't be too much trouble for me. I recognize this solution might not work for those wishing to import several markdown files at once.

comments: author: Daniel Carter
body: What browser are you using? I don't see a 'paste and match style' option

![Screenshot from 2022-05-20 14-57-09.png](https://community.atlassian.com/t5/image/serverpage/image-id/198279i5FAD24F72D919999/image-size/large?v=v2&px=999 "Screenshot from 2022-05-20 14-57-09.png")


author: Alexandra Shumway
body: Per the second sentence of my comment:

"My markdown is in VSCode and I have a new page created in Confluence open in **Google Chrome**. I did not install any plugins or add-ons to Confluence."


author: Daniel Carter
body: 'paste and match' seems to be a Mac thing. Explains why it's not there on linux chrome or firefox.


author: Lee Page
body: 2022 and I still can't make a table in Confluence in any way besides clicking the table icon in the editor and wasting the rest of my day.


author: jan_ekholm
body: Seems Markdown is utterly broken now with Confluence? At least when I paste in something it gets rendered as a code block and I would have to go and fiddle with every single line to get it in the format I want.

This doc says to just "Insert -\> Markup", but there is no such option.

<https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html>

I can't believe we pay for a Wiki that doesn't support Markdown properly.


author: PJ Mc
body: Yes. Ridiculous thing is Confluence used to be great for this.  
I championed and introduced Confluence into many sites as part of Documenation projects, centered on Markdown.   

But their once-'wiki' doesn't even support link-by-name anymore, nor placeholder links.   
These aren't small harmless omissions in Enterprise wiki software.  
And they're not accidental either.  

Now they just don't care - they want to lock as many people in so they can impose anything they like on their userbase, rather than being a part of the marketplace and the cloud competitive ethos.  

The tribe working at Atlassian these days appear to have gone the 'Slack' route and are uninterested in the old 'wiki' (quick) concept. They are treating the product as more of an advanced webpage authoring tool. A bit like Squarespace or Wix. Nothing that is useful to me.  

When I say this, I've made many polite requests on their supportbases.. they have ways of making issues seem to disappear, which are really about renaming and reclassifying things in their JIRA system. Some of the threads.. with many hundreds of disappointed / puzzled / angry users are just amazing to read. Including the 'answers' or 'responses', which are nothing short of 'gaslighting'.

They have become low quality and thus fearful.  

If your product is reliably good \& high quality..  
then keeping at that s the only 'stickiness' you need.  

The alternative is to be whatever you like and focus your effforts on trapping users.

Confluence actually were ahead of the times, and then actively shifted to become hermitlike and scared.

comments: author: PJ Mc
body: Oh I earned a badge for that answer too hehe


author: Jeferson Lemos dos Santos
body: I just figured out that you can do the following:

1. Write your markdown document
2. Open it up in Chrome or any other MD viewer. You can use an extension like [this](https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk/related?hl=pt-BR) to view MD files in Chrome.
3. Copy all content
4. Paste on your Confluence Documentation Page.

It worked for me.

comments: author: Tom Wilkins
body: This is great, my solution is similar.

1. Write markdown in Visual Studio Code
2. Open preview \`ctrl + shift + v\`
3. Copy contents and paste into Confluence


author: PJ Mc
body: Only good if you have 'just a handful' of markdown.

When does that ever happen?

Useless for absorbing a body of documenation.


author: Gabriela Costa
body: My team developed a plugin that can help you, check out [Markdown Extensions for Confluence.](https://marketplace.atlassian.com/apps/1215703/markdown-extensions-for-confluence)

. Here's a list of what it supports:

* Import markdown from Github, Bitbucket, Gitlab, and generic URLs
* Edit and preview markdown inline
* Support for HTML within markdown
* Offers extended markdown formatting

comments: author: PJ Mc
body: Nice.  

This is as good as it can be, given the API limitations imposed by Atlassian.  
The obstruction by Atlassian seems part of their lock-in.  
Their insistance on preventing markdown usage will not serve them well in the long term.


author: Eric Ma
body: [@Gabriela Costa](/t5/user/viewprofilepage/user-id/2760175) can I ask, do your auto-imported Confluence pages auto-update upon new pushes to Markdown content in Bitbucket/GitHub/Gitlab?


author: Jim Cooper
body: Our team uses <https://github.com/justmiles/go-markdown2confluence> to auto-update from Markdown content. We use Bitbucket, but it'll work with the others.


author: Vinu S Renish
body: [@Gabriela Costa](https://community.atlassian.com/t5/user/viewprofilepage/user-id/2760175) same question as [@ema](/t5/user/viewprofilepage/user-id/4910497)

do your auto-imported Confluence pages auto-update upon new pushes to Markdown content in Bitbucket/GitHub/Gitlab?


author: Jim Collier
body: We've been long-time users of Confluence. Personally I've always been frustrated with the WYSIWYG editor.

But then again, I've yet to see any product or plugin for any platform, successfully crack the web-based WYSIWYG editor nut. You'd think by now someone would have. But once you get to a certain level of formatting complexity, Confluence and every other web-based WYSIWYG editor starts soiling the bed. (E.g. in the case of Confluence, at some point you can't position the cursor with the keyboard, without skipping over entire sections. Or formatting one section will format whole chunks or even the entire document, the same way. Again - not unique problems to Confluence.) I think part of the problem is that if you make the mistake of changing the formatting of a section (e.g. to bullets and back to normal paragraph), rather than replacing formatting directives, it keeps adding them...in ways that confuses itself. If web-based WYSIWYG editors would just do self-linting, that would probably be a big help.

It's similar to the problem of exporting a Word document to HTML. Even if you choose "simplified", the HTML is an absolute rat's nest. Running it through HTMLTidy is usually the only way to turn it into sensible HTML, but even that's often not enough.

When we (and specifically I) really started using Markdown, it was like a revelation. Finally, a way to do reasonably sophisticated formatting in a way that you have total control over the formatting directives, and it never gets confused. I use Markdown everywhere now.

But I was shocked to learn that Confluence can't to Markdown!

Suddenly, Confluence feels stone-age and very limited. Thinking of other possible shared documentation repository solutions...


author: Nar Kumar C. - Narva Software
body: Hi Jason,

We released an add-on which allows importing documents from different file formats like Markdown, Word, ODT and many others: [All-in-one File Importer for Confluence](https://marketplace.atlassian.com/apps/1221333/all-in-one-file-importer-for-confluence)

Please give it a try and give us feedback if you see any issues. You can install from here:

<https://marketplace.atlassian.com/apps/1221333/all-in-one-file-importer-for-confluence>

Currently this add-on works on Confluence cloud. If there is enough interest from Atlassian community, we are more than happy to release server version.


author: david.s.mittman
body: If you you have intermediate familiarity with Python, you may be able to create a simple utility that takes as input a MarkDown file, and creates a Confluence page (as a child of an existing ancestor) that is consistently styled. The utility will use Confluence Remote API, Python Requests, and Python Markdown.

Here are some resources for you:

Python Requests: <http://docs.python-requests.org/en/master/>

Python Markdown: <http://pythonhosted.org/Markdown/>

Confluence Server REST API: <https://developer.atlassian.com/confdev/confluence-server-rest-api>

Page Information: <https://confluence.atlassian.com/conf510/view-page-information-829077461.html>

The Page Information link is there because the Confluence Server REST API uses Page IDs, and you can use the Page Information menu item to obtain the Page ID of the Confluence page you're viewing.


author: Rob Woodgate
body: Hi Jason,

These are the [markdown add-ons](https://marketplace.atlassian.com/search?application=confluence&category=&cost=&hosting=server&marketingLabel=&q=markdown) that support server installations. Of these, the only one that appears to do something close to an import is [Marked](https://marketplace.atlassian.com/plugins/com.borisdiakur.marked/server/overview), which is free and has very good reviews. It allows you to point to a markdown file and show it in a Confluence page.

If this is a one time transfer of .md files, you might want to consider spinning up a free trial version of Confluence Cloud, installing the trial version of one of the Cloud markdown import add-ons (e.g. [Confluence Pandoc](https://marketplace.atlassian.com/plugins/com.atlassian.confluence.pandocconnect/cloud/overview)), performing the import and then exporting the space and importing it into your server instance. (I've never tried this, so I don't know if it's possible, but it's worth exploring if you've got a large amount to import.)


author: md2conf
body: Hi folks.

Try [md2conf toolset.](https://github.com/md2conf/md2conf )

It is set of tools to convert and publish directories with markdown files to Confluence.

Additionally this toolset can dump Confluence pages and convert to local markdown files.

Also see [Comparison with other tools](https://github.com/md2conf/md2conf/blob/master/docs/comparison_with_other_tools.md)

I decided to share it with the community since it looks stable enough.

Regards,

md2conf author.


author: yasn77
body: I've come across this thread pretty late and thought I would include a Python module/script I wrote that converts Markdown to Confluence.  

However, I haven't really maintained it (it worked fine the last I used it), so I think the suggestion from Jim Cooper might be better -\> <https://github.com/justmiles/go-markdown2confluence>  

My repo is here -\> <https://github.com/yasn77/readme2confluence>


Tags: markdown