From 695cf0079f9ec30bacfc48bac29506961902258b Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Tue, 14 Jan 2020 13:56:28 -0500 Subject: [PATCH] First pass at updating documentation --- README.md | 153 +++++++++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index e9d6f1e..ec105cf 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,144 @@ # wordpress-export-to-markdown -Converts a WordPress export XML file into Markdown files. +Converts a WordPress export XML file into Markdown files. Useful if you want to migrate from WordPress to a static site generator ([Gatsby](https://www.gatsbyjs.org/), [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/), etc.). -Useful if you want to migrate from WordPress to a static site generator ([Gatsby](https://www.gatsbyjs.org/), [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/), etc.). - -Saves each post as a separate file with appropriate frontmatter. Also saves attached images and (optionally) any additional images found in post body content. Posts and images can be saved into a variety of folder structures. +Saves each post as a separate file with appropriate frontmatter. Also downloads and saves images. There are several options for controlling the folder structure of the output. ## Quick Start You'll need: -- [Node.js](https://nodejs.org/) v10.12 or later +- [Node.js](https://nodejs.org/) v12.14 or later - Your [WordPress export file](https://codex.wordpress.org/Tools_Export_Screen) -Open your terminal to this package's directory. Run `npm install` and then `node index.js`. +Open your terminal to this package's directory. Run `npm install` and then `node index.js`. This will start the wizard. Answers the prompts and off you go! -This will create an `/output` folder filled with your posts and images. +## Command Line -## Customization +The wizard makes it easy to configure your options, but you can also do so via the command line if you want. -You can use command line arguments to control options for how the script runs. For example, this will give you [Jekyll](https://jekyllrb.com/)-style output in terms of folder structure and filenames: +For example, this will give you [Jekyll](https://jekyllrb.com/)-style output in terms of folder structure and filenames: ``` node index.js --postfolders=false --prefixdate=true ``` -### --input +The wizard will still prompt you for any options not specifed on the command line. To skip the wizard entirely and use default values for unspecified options, use `--wizard=false`, like this: -- Type: String +``` +node index.js --wizard=false --postfolders=false --prefixdate=true +``` + +You can see available command line arguments by running: + +``` +node index.js -h +``` + +## Options + +### Use wizard? + +- Argument: `--wizard` +- Type: `boolean` +- Default: `true` + +Enable to have the script prompt you for each option. Disable to skip the wizard entirely and use default values for any options not specified via the command line. + +### Path to input file? + +- Argument: `--input` +- Type: `file` (as a path string) - Default: `export.xml` The file to parse. This should be the WordPress export XML file that you downloaded. -### --output +### Path to output folder? -- Type: String +- Argument: `--output` +- Type: `folder` (as a path string) - Default: `output` -The output directory where Markdown and image files will be saved. +The output directory where Markdown and image files will be saved. If it does not exist, it will be created for you. -### --yearmonthfolders +### Create year folders? -- Type: Boolean +- Argument: `--year-folders` +- Type: `boolean` - Default: `false` -Whether or not to organize output files into year and month folders. +Whether or not to organize output files into folders by year. - /output - /2017 - /01 - /02 - /2018 - /01 +### Create month folders? -### --yearfolders - -- Type: Boolean +- Argument: `--month-folders` +- Type: `boolean` - Default: `false` -Whether or not to organize output files into year folders. +Whether or not to organize output files into folders by month. You'll probably want to combine this with `--year-folders` to organize files by year then month. - /output - /2017 - /2018 +### Create a folder for each post? -### --postfolders - -- Type: Boolean +- Argument: `--post-folders` +- Type: `boolean` - Default: `true` Whether or not to save files and images into post folders. If `true`, the post slug is used for the folder name and the post's Markdown file is named `index.md`. Each post folder will have its own `/images` folder. - /output - /first-post - /images - potato.png - index.md - /oh-look-another-post - /images - cat1.gif - cat2.gif - index.md + /first-post + /images + potato.png + index.md + /second-post + /images + carrot.jpg + celery.jpg + index.md If `false`, the post slug is used to name the post's Markdown file. These files will be side-by-side and images will go into a shared `/images` folder. - /output - /images - cat1.gif - cat2.gif - potato.png - first-post.md - oh-look-another-post.md + /images + carrot.jpg + celery.jpg + potato.png + first-post.md + second-post.md -Either way, this can be combined with with `--yearmonthfolderes` and `--yearfolders`, in which case the above output will be organized under the appropriate year and month folders. +Either way, this can be combined with with `--year-folders` and `--month-folders`, in which case the above output will be organized under the appropriate year and month folders. -### --prefixdate +### Prefix post folders/files with date? -- Type: Boolean +- Argument: `--prefix-date` +- Type: `boolean` - Default: `false` Whether or not to prepend the post date to the post slug when naming a post's folder or file. -If `--postfolders` is `true`, this affects the folder. +If `--post-folders` is `true`, this affects the folder. - /output - /2017-01-14-first-post - index.md - /2017-01-23-oh-look-another-post - index.md + /2019-10-14-first-post + index.md + /2019-10-23-second-post + index.md -If `--postfolders` is `false`, this affects the file. +If `--post-folders` is `false`, this affects the file. - /output - 2017-01-14-first-post.md - 2017-01-23-oh-look-another-post.md + 2019-10-14-first-post.md + 2019-10-23-second-post.md -### --saveimages +### Save images attached to posts? -- Type: Boolean +- Argument: `--save-attached-images` +- Type: `boolean` - Default: `true` -Whether or not to download and save images attached to posts. Generally speaking, these are images that were added by dragging/dropping or clicking **Add Media** or **Set Featured Image** when editing a post in WordPress. Images are saved into `/images`. See `--postfolders` for more details. +Whether or not to download and save images attached to posts. Generally speaking, these are images that were added by dragging/dropping or clicking **Add Media** or **Set Featured Image** when editing a post in WordPress. Images are saved into `/images`. -### --addcontentimages +### Save images scraped from post body content? -- Type: Boolean -- Default: `false` +- Argument: `--save-scraped-images` +- Type: `boolean` +- Default: `true` -Whether or not to also include images scraped from <img> tags in post body content. These images are downloaded and saved along with other images as dictated by `--saveimages`. The <img> tags are updated to point to where the images are saved. +Whether or not to download and save images scraped from <img> tags in post body content. Images are saved into `/images`. The <img> tags are updated to point to where the images are saved.