# HG changeset patch # User Ludovic Chabant # Date 1429594510 25200 # Node ID 3a496ffbb898108feba64a3dbaabb2cd2a7ee4a7 # Parent 019d274e67139b86bc5311c8ed6b07df6966d54f docs: Add documentation for importing content from other engines. diff -r 019d274e6713 -r 3a496ffbb898 docs/docs/20_importing.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/20_importing.md Mon Apr 20 22:35:10 2015 -0700 @@ -0,0 +1,16 @@ +--- +title: Importing +--- + +Many people come to static website generators after having been frustrated with +more full-fledged -- but paradoxically more limiting -- content management +systems like Wordpress. Others just try different static website generators +until they find one they're totally satisfied with. + +PieCrust supports importing content from other such systems, using the `chef +import` command. Here are some details about each importer: + +{% for part in family.children -%} +* [{{part.title}}]({{part.url}}) +{% endfor %} + diff -r 019d274e6713 -r 3a496ffbb898 docs/docs/20_importing/01_piecrust1.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/20_importing/01_piecrust1.md Mon Apr 20 22:35:10 2015 -0700 @@ -0,0 +1,67 @@ +--- +title: Importing from PieCrust 1.x +--- + +You can import content from a PieCrust 1.x website with: + + chef import piecrust1 /path/to/old/piecrust/website + +Most of the content will be converted, but some things will still require some +manual fixes -- see below. + +> ### Upgrading a website +> +> As with all other `chef import` commands, this will import all the content +> from the old site into the current site. However, you may pass the `--upgrade` +> parameter instead of a path to a site directory to upgrade the old site +> "in-place": +> +> cd /path/to/old/piecrust/website +> chef import piecrust1 --upgrade +> +> Instead of copying and converting content into a different folder, it will +> edit your files directly. Obviously, you need to make sure you have a backup, +> or that your website is stored in a revision control system. + + +## Manual fixes + +### Dates + +If you were using custom date formats, either in the site configuration or +through Twig filters, you'll have to convert them from [PHP date formats][php] +to [Python date formats][dt]. + +Note that if you need an RFC 2822 date format, you can use the `emaildate` with +Jinja as the template engine. And if you need an RFC 3339 date format (_e.g._ +for XML output like RSS and Atom feeds) you can use the `atomdate` filter. + +### Twig plugins + +If you were using Twig plugins to add tags, filters, and functions, you'll have +to find their equivalent in Jinja. + +### Clean up the asset folder + +PieCrust 1.x had all assets at the website root, mixed with the special +`_content` folder. This meant that if you had some files that weren't supposed +to be baked with the site, you had to exclude them using the +`baker/skip_patterns` site configuration setting. + +PieCrust 2 cleans that up a lot by having all the content at +the root, but all the assets in an `asset` folder. So if you have files that you +don't want to bake, just put them somewhere else than the `asset` folder. + +However, because PieCrust has no way of knowing what's what, it will, during +import, copy everything into the `asset` folder, and convert the +`baker/skip_patterns` setting to `baker/ignore`. + +Once the import process is complete, you're encouraged to move anything that +shouldn't be part of the bake out of the `assets` folder, and to remove the +uncessary `ignore` patterns. It's not required, but it will make your website a +lot tidier! + + +[php]: http://php.net/manual/en/function.date.php +[dt]: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior + diff -r 019d274e6713 -r 3a496ffbb898 docs/docs/20_importing/02_wordpress.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/20_importing/02_wordpress.md Mon Apr 20 22:35:10 2015 -0700 @@ -0,0 +1,42 @@ +--- +title: Importing from Wordpress +--- + +If you have a Wordpress site already, you can [export an XML archive][1] very +easily. Go into the administration panel and choose "_Tools > Export_". Keep the +"_All content_" option selected, and hit the "_Download export file_" button. + +Now create a new PieCrust website and import that archive: + + chef init myblog + cd myblog + chef import wordpress-xml /path/to/archive.xml + +This will create all the pages, posts, and metadata in the current PieCrust +website. + +Be aware of the following caveats however: + +* The import process will edit the current website's configuration file to set + some properties on it, like the website's title and list of authors. + +* At the moment, only _content_ is imported, not themes and templates and such. + Although it may be technically possible to do so, many Wordpress themes come + with commercial licenses which could potentially prevent converting it. + +* Because Wordpress stores its pages' contents in raw HTML, you won't get nice + Markdown or Textile syntax from the import process. + +* PieCrust will import any attachments to pages or posts (images, etc.). This + means it will make requests to the original URLs of those attachments in order + to download them. If your Wordpress website was taken down, PieCrust won't be + able to download anything and you'll be missing things from the imported + website. + +* If you had comments in your Wordpress blog, they will be lost. You can however + import those comments in a service like Disqus, and then use Disqus on your + PieCrust website. + + +[1]: https://en.support.wordpress.com/export/ + diff -r 019d274e6713 -r 3a496ffbb898 docs/docs/20_importing/03_jekyll.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/20_importing/03_jekyll.md Mon Apr 20 22:35:10 2015 -0700 @@ -0,0 +1,12 @@ +--- +title: Importing from Jekyll +--- + +You can import your website from Jekyll by running: + + chef import jekyll /path/to/jekyll/website + +This will import the whole website -- pages, posts, templates, etc. It will +attempt to convert Liquid templates to Jinja, but may fail if you're using +advanced syntax tricks or custom tags and filters. +