sutty-migration¶ ↑
Installation¶ ↑
Add this line to your site's Gemfile:
gem 'sutty-migration'
And then execute:
$ bundle
Or install it yourself as:
$ gem install sutty-migration
Usage¶ ↑
Add the plugin to your _config.yml
:
plugins: - sutty-migration array_separator: ','
Compile a CSV file with the following required fields:
id,title,date
The date
field is optional, but once they're set they can't change, otherwise you'll start to find duplicates.
Put the CSV file inside a _data/migration/
directory and name it as the layout you're migrating into. For instance, to migrate posts, use a file called _data/migration/post.csv
.
Then, define the layout data by using a layout data file. You can create one of these using sutty-cli
.
# install sutty-cli gem install sutty-cli # create a layout sutty-cli layout post # add fields sutty-cli field description --layout post --type text
And now you can add the description
field into the CSV:
id,title,date,description 1,"Article",2020-01-01,"Short description"
The ID is important to identify updates, it can be anything, numbers, letters, etc. We recommend using unique identifiers like UUIDs.
To start migration just build your site:
bundle exec jekyll build
Tip: Files can also be JSON, TSV and YAML, since they're all supported by Jekyll.
Wordpress¶ ↑
Instead of requiring you to install and configure MariaDB/MySQL, you can convert the database into SQLite3 like this:
git clone https://0xacab.org/sutty/mysql2sqlite.git cd mysql2sqlite ./mysql2sqlite /path/to/database/dump.sql | sed -re "s/, 0x([0-9a-f]+),/, X'\1',/i" | sqlite3 wordpress.sqlite3
It will probably show some errors.
Note the sed
command is required to convert hexadecimal values into SQLite syntax, since mysql2sqlite
doesn't support this yet.
Wordpress websites can include lots of posts and metadata, depending on the amount of plugins installed. We don't have an official way of dumping everything into Jekyll, because you will probably want to move things around. You can write a plugin like this:
# _plugins/wordpress.rb # frozen_string_literal: true require 'sutty_migration/wordpress' require 'sutty_migration/jekyll/document_creator' require 'jekyll-write-and-commit-changes' Jekyll::Hooks.register :site, :post_read, priority: :low do |site| wp = SuttyMigration::Wordpress.new(site: site, database: 'wordpress.sqlite3', prefix: 'wp_', url: 'https://wordpre.ss') # Download all files wp.download_all wp.posts(layout: 'post').each do |post| doc = Jekyll::Document.create(site: site, title: post[:post_title], date: post[:post_date], collection: 'posts') doc.content = post[:content] doc.save end end
WordPress XML¶ ↑
If you have the XML dump from a WordPress site, you can migrate content by writing a migration plugin.
# frozen_string_literal: true require 'sutty_migration/jekyll/document_creator' require 'sutty_migration/wordpress_xml' require 'jekyll-write-and-commit-changes' require 'securerandom' # Run after reading the site Jekyll::Hooks.register :site, :post_read do |site| # Put the XML dump at _files/wordpress.xml xml = SuttyMigration::WordpressXml.new site: site, file: '_files/wordpress.xml' # Download all files xml.attachments.values.map(&:download) # Migrate posts. You can move metadata around and recover # relationships or any info your theme requires. xml.posts.values.each do |post| # Update documents already migrated. doc = Jekyll::Document.find_or_create(site: site, collection: locale, title: post.title, slug: post.slug, date: post.date) # Don't change the UUIDv4 d.data['uuid'] ||= SecureRandom.uuid d.data['draft'] = post.draft? d.data['layout'] = 'post' d.data['last_modified_at'] = post.last_modified_at d.data['categories'] = post.categories.map { |c| c[:title] } d.data['tags'] = post.tags.map { |t| t[:title] } d.data['author'] = post.author[:email] d.data['description'] = post.description d.content = post.content doc.save rescue => e Jekyll.logger.warn "Couldn't migrate #{post.title}" end exit # Stop here end
Contributing¶ ↑
Bug reports and pull requests are welcome on 0xacab.org at 0xacab.org/sutty/jekyll/sutty-migration. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Sutty code of conduct.
If you like our plugins, please consider donating!
License¶ ↑
The gem is available as free software under the terms of the GPL3 License.
Code of Conduct¶ ↑
Everyone interacting in the sutty-migration project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.