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 (8 months ago)
Current version: 0.6.0
Compatible with: Redmine 4.2.x, 4.1.x, 4.0.x, 3.4.x
User ratings:   (3)

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 Ji-Hyeon Gim 8 months ago

  by Sandra Tatarevicova 8 months ago

  by Lucie Nevludov√° 8 months ago