turndown-redmine

turndown-redmine is an HTML to GitHub Flavored Markdown converter designed to work well for Redmine as the text destination.

Technically, it is an opinionated extension and configuration of Turndown that recognizes Redmine-specific constructs like macros and improves Turndown in several ways. The holy grail is to fully pass backtranslation tests and we are very close.

turndown-redmine is able to transform specifics of HTML generated by Redmine and JIRA and create Redmine constructs like attachment links accordingly. There are two main use cases:

• Automatic format conversions
• WYSIWYG editing

Installation and usage

Using npm:

npm install turndown-redmine

In Node.js:

const TurndownRedmine = require('turndown-redmine');

Synopsis

const turndownRedmine = new TurndownRedmine();
const markdown = turndownRedmine.turndown(str);

Options

Options can be passed in to the constructor on instantiation.

Option	Valid values	Default
fontColor	true or false	false
attachmentUrlPatterns	RegExp	[/^\/secure\/attachment\/\d+\/\d+_([^/]+)$/,/^\/attachments\/download\/\d+\/([^/]+)$/]
codeClassPatterns	RegExp	[/^(?:language\|code)-(\S+)$/, /^(\S+)\s+syntaxhl$/]
fence	``` or ~~~ | ```
listSeparator	any string	\n<!-- end list -->\n
listItemPadding	any integer	0
citeDelimiter	<cite> or *	<cite>
preformattedCode	true or false	true
htmlEncodedRedmineMacros	true or false	true
thumbnailMacro	true or false	true
collapseMacro	true or false	true
collapseMacroDefaultArgs	Array of 2 string values	['Show', 'Hide']

• fontColor - Specifies whether colorized text should be rendered or not.
• attachmentUrlPatterns - Array of RegExp patterns which match attachments name in URL.
• codeClassPatterns - Array of RegExp patterns which match code language in code blocks.
• fence - Code fence of fenced code block.
• listSeparator - Separator of consecutive lists.
• citeDelimiter - Specifies delimiter to be used for rendering <cite> element.
• preformattedCode - treat inline code as preformatted, should be considered rather experimental, as correct escaping is not yet guaranteed
• htmlEncodedRedmineMacros - see redmine_reformat's RedmineFormatter for more details
• thumbnailMacro - use Redmine {{thumbnail}} macro for recognized image thumbnails.
• collapseMacro - use Redmine {{collapse}} macro for recognized collapsed text.
• collapseMacroDefaultArgs - Array of 2 string values that should be considered as default collapse macro arguments. Macros with matching arguments will be rendered with no arguments. Order of Array members is important.

Example

const TurndownRedmine = require('turndown-redmine');
 
const turndownRedmine = new TurndownRedmine();
const markdown = turndownRedmine.turndown('<h1>text</h1>');

Produces:

# text

Implementation details

Compared to Turndown, TurndownRedmine additionally uses two sets of rules:

1. Tables by Turndown plugin GFM
2. Custom rules for Redmine, which can be found in TurndownPluginRedmine.js

Additional rules can be added either to TurndownPluginRedmine.js if they are relevant to Redmine, or as a module in RedmineTurndownService.js.