# Markdown2Confluence

This tool converts [Markdown] to [Confluence Wiki Markup].

[![NPM version][npm-image]][npm-url]
[![Downloads][downloads-image]][downloads-url]

## 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][confluence-wiki-markup] and [references][wiki-render-help-action].

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

## Installation

```sh
npm i -g @shogobg/markdown2confluence
```

```sh
npm i --save @shogobg/markdown2confluence
```

## Command-Line Use

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

```sh
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.

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

This uses the wonderful [marked](https://www.npmjs.com/package/marked) library to parse and reformat the Markdown text.

## Custom options

Since this tool uses [marked](https://www.npmjs.com/package/marked), there is a pre-defined renderer which we pass to [marked](https://www.npmjs.com/package/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.

```javascript
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.

```javascript
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](./demo/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

[![License][license-image]][license-url]

# About

This tool was originally written by [chunpu](https://github.com/chunpu/markdown2confluence), but it was outdated with latest version from 2017.
It didn't suit my needs to convert Markdown generated by [widdershins](https://github.com/Mermade/widdershins), so I decided to update it and publish the changes.
Shamelessly copied improvements from [fdian](https://github.com/connected-world-services/markdown2confluence-cws).

[markdown]: http://daringfireball.net/projects/markdown/syntax
[github flavored markdown]: https://github.github.com/gfm/
[confluence wiki markup]: https://confluence.atlassian.com/display/CONF42/Confluence+Wiki+Markup
[npm-image]: https://img.shields.io/npm/v/@shogobg/markdown2confluence.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/@shogobg/markdown2confluence
[downloads-image]: http://img.shields.io/npm/dm/@shogobg/markdown2confluence.svg?style=flat-square
[downloads-url]: https://www.npmjs.com/package/@shogobg/markdown2confluence
[license-image]: http://img.shields.io/npm/l/@shogobg/markdown2confluence.svg?style=flat-square
[license-url]: #
[wiki-render-help-action]: https://roundcorner.atlassian.net/secure/WikiRendererHelpAction.jspa?section=all
[confluence-wiki-markup]: https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup
[removed-wiki-markup-editor]: http://blogs.atlassian.com/2011/11/why-we-removed-wiki-markup-editor-in-confluence-4/
[code-block-macro]: https://confluence.atlassian.com/doc/code-block-macro-139390.html