Plugins Directory » Reformat

24862 Author: Martin Cizek
Website: https://github.com/orchitech/redmine_reformat
Code repository: https://github.com/orchitech/redmine_reformat
Registered on: 2020-02-19 (over 2 years ago)
Current version: 0.6.0
Compatible with: Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x
User ratings:   (4)

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!

Installation notes

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.

Changelog

0.6.0 (2020-06-03)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x.

Added PUT method to both provided microservicee and WS converter. PUT is now the default when invoking external services - preferring idempotent requests. Improved microservice error handling.

0.5.0 (2020-04-30)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x.

Introduced LinkRewriter converter for updating wiki link references. Useful for project and wiki refactoring - renaming project identifier, merging projects, ...

0.4.0 (2020-04-13)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x.

  • MarkdownToCommonmark: switched to patched (fixed) cmark-gfm library to get correct sourcepos of Markdown nodes
  • Made force_crlf and match_trailing_nl user-configurable.
  • Updated default converter config to handle markdown -> common_mark conversion out of the box.

0.3.0 (2020-04-06)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x.

Introduced MarkdownToCommonmark converter to help users with markdown to common_mark formatting migration. See #32424.

0.2.0 (2020-03-28)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x, 3.3.x.

  • Introduced rake reformat:microservice to facilitate certain integration tests.
  • Rake task for Redmine format conversion has been renamed to rake reformat:convert.

0.1.1 (2020-02-25)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x, 3.3.x.

from_formatting and to_fromatting in converter config can be specified as an array, so that a single converter spec can match more formats.

0.1.0 (2020-02-19)

Compatible with Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x, 3.3.x.

User ratings

  by Milan Brabec 11 months ago

Great plugin, done the task very well, and also big thanks to author's support with this!!!

  by Ji-Hyeon Gim about 2 years ago

  by Sandra Tatarevicova about 2 years ago

  by Lucie Nevludov√° about 2 years ago