/ README.md
README.md
1 # Caramelize 2 3 [](https://codeclimate.com/github/Dahie/caramelize/maintainability) 4 5 Caramelize is a compact and flexible wiki migration tool. It is intended for easy transfer of content from legacy wikis. With caramelize you can create your own export configurations and migrate your page revisions into a git repository of markdown files. This retains all your history and you gain the most flexible access to your wiki content available for use with git-based wikis like [gollum](https://github.com/github/gollum), [Otter Wiki](https://github.com/redimp/otterwiki), [Wiki.js](https://js.wiki/) or [Obsidian](https://obsidian.md/). 6 7 By default, it ships with configurations for [WikkaWiki](http://wikkawiki.org/) and [Redmine](http://www.redmine.org/). 8 9 10 ## Usage 11 12 ### Installation 13 14 ```sh 15 $ gem install caramelize 16 ``` 17 18 Install the latest release of caramelize using RubyGems. 19 Requires pandoc to be installed. 20 21 ### Use 22 23 ```sh 24 $ caramelize create 25 ``` 26 27 Creates a template configuration file "caramel.rb". This includes documentation on how to use the preset Wiki-connectors and how to write addition customized connectors. More about this below. 28 29 ```sh 30 $ caramelize run 31 ``` 32 33 Will start the wiki migration based on the configuration file. These are either found in predefined paths (./caramel.rb, ./config.rb, …), or passed as argument, as below. 34 35 ```sh 36 $ caramelize doctor 37 ``` 38 39 Can be used to assess the quality of your wiki conversion. It'll help you see 40 how many wiki links may be broken and how many pages were orphaned. 41 42 ```sh 43 $ caramelize help 44 ``` 45 46 Returns help information. 47 48 ```sh 49 $ caramelize version 50 ``` 51 52 Returns version and release information. 53 54 ### Options 55 56 ```sh 57 $ caramelize create --config my_caramel_configuration.rb 58 ``` 59 60 Creates an example configuration by the given name. 61 62 ```sh 63 $ caramelize run --config my_caramel_configuration.rb 64 ``` 65 66 Executes the given configuration. 67 68 ```sh 69 $ caramelize --verbose [command] 70 ``` 71 72 Displays more verbose output to the command line. 73 74 ## Content migration 75 76 ### Wiki support 77 78 Caramelize comes with direct support for [MediaWiki](https://www.mediawiki.org), [WikkaWiki](http://wikkawiki.org/) and [Redmine](http://www.redmine.org/)-Wiki. 79 More custom wikis can be supported by creating a suitable configuration file. 80 81 The wiki is exported to markdown files in a git-repository. This can be directly used as source for [gollum](https://github.com/github/gollum) wiki, [Otter Wiki](https://github.com/redimp/otterwiki), or if you don't care about the history even [Obsidian](https://obsidian.md/). 82 This gives you the flexibility of having all wiki pages exported as physical files, while keeping the history and having an easy and wide-supported way of access. 83 84 Since wiki software may have special features, that are not common among other wikis, content migration may always have a loss of style or information. Caramelize tries to support the most common features. 85 86 * Page meta data 87 * title 88 * content body 89 * author name 90 * author email address 91 * date 92 * revisions 93 * Markup conversion to markdown 94 * limited to "simple" formatting, excluding complex formats such as tables 95 * conversion using regular expressions -> somewhat easy to learn and extend 96 97 ### Configuration recipes 98 99 The `lib/caramelize/caramel.rb` configuration contains the settings on how to import the data of the existing wiki and how to convert it into the format required by caramelize to export to gollum. 100 You also find the predefined definitions for importing from WikkaWiki and Redmine and and example for a custom import. 101 102 Custom import allows you to import data from wikis that are not natively supported by caramelize. Defining your own wiki import requires a bit of knowledge on Ruby and MySQL as you setup the access to your wiki database and need to define how the data is to be transformed. Depending on the database model of the wiki this can be one simple call for all revisions in the database, or it can get more complicated with multiple mysql-calls as the database becomes more complex. 103 104 For a custom wiki you need to create a `wiki` instance object, that receives the necessary database creditials. 105 106 ```ruby 107 wiki = Caramelize::InputWiki::Wiki.new(host: "localhost", 108 username: "user", 109 database: "database_name", 110 password: 'monkey', 111 markup: :wikka}) 112 ``` 113 114 This example ignores custom markup conversion and assumes WikkaWiki-markup. 115 116 Once the object is established we need to hook in a method that defines how revisions are read from the database and how they are processed. 117 118 ```ruby 119 wiki.instance_eval do 120 def read_pages 121 sql = "SELECT id, tag, body, time, latest, user, note FROM wikka_pages ORDER BY time;" 122 revisions, titles = [], [] 123 results = database.query(sql) 124 results.each do |row| 125 titles << row["tag"] 126 author = authors[row["user"]] 127 page = Page.new({id: row["id"], 128 title: row["tag"], 129 body: row["body"], 130 markup: 'wikka', 131 latest: row["latest"] == "Y", 132 time: row["time"], 133 message: row["note"], 134 author: author}) 135 revisions << page 136 end 137 # titles is the list of all unique page titles contained in the wiki 138 titles.uniq! 139 # revisions is the list of all revisions ordered by date 140 revisions 141 end 142 ``` 143 144 In the end the `wiki` instance needs the `titles` and `revisions` filled. 145 146 Some wikis don't have all necessary metadata saved in the revision. In this case additional database queries are necessary. **The configuration recipe is pure ruby code, that is included on execution. This gives you a lot of freedom in writing your configuration, but also a lot of power to break things. Be advised.** 147 148 I'm happy to give support on your recipes and I'd also like to extend caramelize with more wiki modules, if you send in your configurations (minus database credentials of course). 149 150 ### Building 151 152 This is how you can build caramelize, in case you'd like to develop it further. To get startered you'll need Bundler. 153 154 ```sh 155 $ gem install bundler 156 ``` 157 158 Clone or fork this repository and start building. 159 160 ```sh 161 $ git clone git@github.com:Dahie/caramelize.git 162 $ gem build caramelize.gemspec 163 ``` 164 165 Now to build and package the gem do 166 167 ```sh 168 $ rake build 169 ``` 170 171 or 172 173 ```sh 174 $ rake install 175 ``` 176 177 to install the new gem right to your system. 178 179 Tests run with 180 181 ```sh 182 $ rspec 183 ``` 184 185 ## Contributing to caramelize 186 187 * Check out the latest main to make sure the feature hasn't been implemented or the bug hasn't been fixed yet 188 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it 189 * Fork the project 190 * Start a feature/bugfix branch 191 * Commit and push until you are happy with your contribution 192 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. 193 194 ## Copyright 195 196 Copyright (c) 2011-2024 Daniel Senff. See LICENSE.md for further details.