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..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..map { |t| t[:title] }
d.data['author'] = post.[: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 https://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.