@shogobg/markdown2confluence

Markdown2Confluence

This tool converts Markdown to Confluence Wiki Markup.

Overview

Using Markdown is fast becoming a standard for open-source projects and their documentation. There are a few variants, such as GitHub Flavored Markdown, which add additional features.

Atlassian's Confluence has a different way of writing documentation, according to their Confluence Wiki Markup and later pages and references.

This project contains a library and a command-line tool that bridges the gap and converts from Markdown to Confluence.

Installation

npm i -g @shogobg/markdown2confluence

npm i --save @shogobg/markdown2confluence

Command-Line Use

Read in a Markdown file and write Confluence format to another file:

markdown2confluence <path/to/markdown.md> <path/to/output.txt>

Or output to standard output:

markdown2confluence README.md

Or pipe in a file and output to standard output:

cat README.md | markdown2confluence

(Piping into markdown2confluence only works on platforms that support /dev/stdin, for example not Windows.)

As library dependency

Or just edit your application package.json and add the following code to your dependencies object:

{
    ...
    "dependencies": {
        ...
        "@shogobg/markdown2confluence": "*"
        ...
    }
    ...
}

Now you write some JavaScript to load Markdown content and convert.

markdown2confluence = require('@shogobg/markdown2confluence');
markdown = fs.readFileSync('README.md');
confluence = markdown2confluence(markdown);
console.log(confluence);

This uses the wonderful marked library to parse and reformat the Markdown text.

Custom options

Since this tool uses marked, there is a pre-defined renderer which we pass to marked. If you want to replace any of the predefined functions or the renderer as a whole, you can do so by passing an options object to the tool.

markdown2confluence = require('@shogobg/markdown2confluence');
markdown = fs.readFileSync('README.md');
confluence = markdown2confluence(markdown, {
  renderer: {
    link: href => {
      return `http://example.com/${href}`;
    },
  },
});
console.log(confluence);

Additionally, the options objects takes custom arguments for the confluence code block options.

markdown2confluence = require('@shogobg/markdown2confluence');
markdown = fs.readFileSync('README.md');
confluence = markdown2confluence(markdown, {
  renderer: {
    link: href => {
      return `http://example.com/${href}`;
    },
  },
  codeBlock: {
    // Adds support for new language
    languageMap: {
      leet: '1337',
    },
    // Shows the supported options and their default values
    options: {
      title: 'none',
      language: 'none',
      borderStyle: 'solid',
      theme: 'RDark', // dark is good
      linenumbers: true,
      collapse: true,
    },
  },
});
console.log(confluence);

Supported Markdown

The aim of this library is to convert as much Markdown to Confluence Wiki Markup. As such, most Markdown is supported but there are going to be rare cases that are not supported (such as code blocks within lists) or other scenarios that people find.

If it is possible to convert the Markdown to Confluence Wiki Markup (without resorting to HTML), then this library should be able to do it. If you find anything wrong, it is likely a bug and should be reported. I would need a sample of Markdown, the incorrect translation and the correct way to represent that in Confluence. Please file an issue with this information in order to help replicate and fix the issue.

A good demonstration chunk of markdown is available in demo.md.

What does not work?

• HTML. It is copied verbatim to the output text.
• Did you find anything else? Please tell us about it by opening an issue.

License

About

This tool was originally written by chunpu, but it was outdated with latest version from 2017. It didn't suit my needs to convert Markdown generated by widdershins, so I decided to update it and publish the changes. Shamelessly copied improvements from fdian.