Redmine Reformat - A Swiss-Army Knife for Converting Redmine Rich Text Data¶

Redmine Reformat is a Redmine plugin providing a rake task for flexible rich-text field format conversions and batch editing.

Features¶

• Conversion can be run on a per-project, per-object and per-field basis.
• Different sets of data can use different conversions - useful if some parts of your Redmine use different syntax flavours.
• Supports custom fields, journals and even custom field journals.
• Supports parallel conversion in several processes - especially handy when external tools are used (pandoc, web services).
• Transaction safety even for parallel conversion.
• Currently supported converters:
  • TextileToMarkdown - a Pandoc-based Textile to Markdown converter. Works on markup level. Battle-tested on quarter a million strings. See below for details.
  • MarkdownToCommonmark - converts main specifics in old Redmine markdown format (Redcarpet) to CommonMark/GFM.
  • RedmineFormatter - produces HTML using Redmine's internal formatter. Useful when chaining with external converters. See below for details.
  • LinkRewriter - useful for refactoring Redmine project structure (renaming, merging). See below for details.
  • Ws - calls an external web service, providing input in the request body and expecting converted output in the response body.
  • Feel free to submit more :)
• Conversions can be chained - e.g. convert Atlassian Wiki Markup (roughly similar to Textile) to HTML and then HTML to Markdown using Turndown.
• Newlines are normalized in a configurable way to make the result deterministic and most matching the converted texts.

Basic Usage¶

Current format Textile - convert all rich text to Markdown using the default TextileToMarkdown converter setup:

rake reformat:convert to_formatting=markdown

Dry run:

rake reformat:convert to_formatting=markdown dryrun=1

Parallel processing (Unix/Linux only):

rake reformat:convert to_formatting=markdown workers=10

If already using the commmon_mark format patch (see #32424 and Docker image orchitech/redmine-gfm):

# convert from textile:
rake reformat:convert to_formatting=common_mark
# convert from Redcarpet's markdown - same command:
rake reformat:convert to_formatting=common_mark

Renaming or merging Redmine project can only be done directly in the database. redmine_reformat can prepare wiki links for such change:

# 1. remove project prefix for wiki links within the renamed project
# 2. rename project prefix in wiki links outside of the renamed project
convcfg='[{
  "projects": ["oldname"]
  "converters": [["LinkRewriter", { "oldname": { "project": null } }]]
}, {
  "converters": [["LinkRewriter", { "oldname": { "project": "newname" } }]]
}]'
rake reformat:convert converters_json="$convcfg" 
# now you can rename the 'oldname' project to 'newname'

Convert to HTML (assuming a hypothetical html rich text format):

convcfg='[{
  "from_formatting": "textile",
  "to_formatting": "html",
  "converters": "RedmineFormatter" 
}]'
rake reformat:convert to_formatting=html converters_json="$convcfg" 

Convert using an external web service through intermediate HTML:

convcfg='[{
  "from_formatting": "textile",
  "to_formatting": "common_mark",
  "converters": [
    ["RedmineFormatter"],
    ["Ws", "http://localhost:4000/turndown-uservice"]
  ]
}]'
rake reformat:convert to_formatting=common_mark converters_json="$convcfg" 

For advanced scenarios and more info, visit the homepage.

Questions, Contributions and Issues¶

Feel free to open a ticket or PR on project's GitHub

Happy reformatting!

Database Backup¶

Either backup your database or clone your Redmine instance completely. A cloned Redmine instance allows you to compare conversion results with the original.

Install¶

cd $REDMINE_ROOT
git -C plugins clone https://github.com/orchitech/redmine_reformat.git
bundle install

And restart your Redmine.

Installing Converter Dependencies¶

If using TextileToMarkdown converter, install pandoc. The other provided converters have no direct dependencies.