From 140d9f5038bd098f453a8f7902cda99c50995e99 Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Fri, 14 Mar 2025 09:35:47 -0400 Subject: [PATCH 1/6] Documentation progress --- README.md | 158 +++++++++++++++++++---------------------------- src/questions.js | 2 +- 2 files changed, 64 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index b4f99ad..35f6203 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,118 @@ # wordpress-export-to-markdown -Converts a WordPress export file into Markdown files that are compatible with static site generators ([Eleventy](https://www.11ty.dev/), [Gatsby](https://www.gatsbyjs.com/), [Hugo](https://gohugo.io/), etc.). - -Each post is saved as a separate Markdown file with frontmatter. Images are downloaded and saved. +Converts a WordPress export XML file into Markdown files. This makes it easy to migrate from WordPress to a static site generator ([Eleventy](https://www.11ty.dev/), [Gatsby](https://www.gatsbyjs.com/), [Hugo](https://gohugo.io/), etc.). ![wordpress-export-to-markdown running in a terminal](https://user-images.githubusercontent.com/1245573/72686026-3aa04280-3abe-11ea-92c1-d756a24657dd.gif) +## Features + +- Saves each post as a separate Markdown file with frontmatter. +- Also saves drafts, pages, and custom post types, if you have any. +- Downloads images and updates references to them. +- User-friendly wizard guides you through the process. +- Lots of command line options for configuration, if needed. + ## Quick Start You'll need: -- [Node.js](https://nodejs.org/) installed -- Your [WordPress export file](https://wordpress.org/support/article/tools-export-screen/) (be sure to export "All content"). -To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run this script from. +- [Node.js](https://nodejs.org/) installed. +- Your [WordPress export file](https://wordpress.org/support/article/tools-export-screen/). Be sure to export "All Content". -You can run this script immediately in your terminal with `npx`: +Then run this in your terminal: ``` npx wordpress-export-to-markdown ``` -Or you can clone this repo, then from within the repo's directory, install and run: +## Options -``` -npm install && node index.js -``` +The script will start with a wizard to ask you a few questions. -Either way, the script will start a wizard to configure your options. Answer the questions and off you go! - -## Command Line - -Options can also be configured via the command line. The wizard will skip asking about any such options. For example, the following will give you [Jekyll](https://jekyllrb.com/)-style output in terms of folder structure and filenames. - -Using `npx`: +Optionally, you can provide answers to any of these questions via command line arguments, in which case the wizard will skip asking those questions. Here's an example: ``` npx wordpress-export-to-markdown --post-folders=false --prefix-date=true ``` -Using a locally cloned repo: +The questions, and their command line arguments, are given below. -``` -node index.js --post-folders=false --prefix-date=true -``` +### Path to WordPress export file? (`--input`) -The wizard will still ask you about any options not specified on the command line. To skip the wizard entirely and use default values for unspecified options, add `--wizard=false`. +The path to your [WordPress export file](https://wordpress.org/documentation/article/tools-export-screen/). Default is `export.xml`. -## Options +To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run the script from. -These are the questions asked by the wizard. Command line arguments, along with their default values, are also being provided here if you want to use them. +### Put each post into its own folder? (`--post-folders`) -### Path to WordPress export file? +Whether or not a separate folder is created for each post's Markdown file (and images). Default is `true`. -**Command line:** `--input=export.xml` +| Value | Description | +| --- | --- | +| `true` | A folder is created for each post, with an `index.md` file and `/images` folder within. The post slug is used to name the folder. | +| `false` | The post slug is used to name each post's Markdown file. These files are all saved in the same folder. All images are saved in a shared `/images` folder. | -The path to your WordPress export file. To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run this script from. +### Add date prefix to posts? (`--prefix-date`) -### Path to output folder? +Whether or not the post date is prepended when naming a post's folder or file. Default is `false`. -**Command line:** `--output=output` +| Value | Description | +| --- | --- | +| `true` | Prepend the date, in the format `--`. Nothing will be prepended if there is no date (for example, an undated draft post). | +| `false` | Don't prepend the date. | -The path to the output directory where Markdown and image files will be saved. If it does not exist, it will be created. +### Organize posts into date folders? (`--date-folders`) -### Create year folders? +If and how output is organized into folders based on date. Default is `none`. -**Command line:** `--year-folders=false` +| Value | Description | +| --- | --- | +| `year` | Output is organized into folders by year. This won't happen for posts with no date (for example, an undated draft post). | +| `year‑month` | Output is organized into folders by year, then into nested folders by month. Again, for posts with no date, this won't happen. | +| `none` | No date folders are created. | -Whether or not to organize output files into folders by year. +### Save images? (`--save-images`) -### Create month folders? +Which images you want to download and save. Default is `all`. -**Command line:** `--month-folders=false` +| Value | Description | +| --- | --- | +| `attached` | Save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. | +| `scraped` | Save images scraped from `` tags in post body content. The `` tags are updated to point to where the images are saved. | +| `all` | Save all images, essentially `attached` and `scraped` together. | +| `none` | Don't save any images. | -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. +## Advanced Options -### Create a folder for each post? +These are not included in the wizard, so you'll need to set them on the command line. -**Command line:** `--post-folders=true` +### Path to output folder? (`--output`) -Whether or not to save files and images into post folders. +The path to the output folder where files will be saved. It'll be created if it doesn't exist. Default is `output`. -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. +Existing files in the output folder won't be overwritten. Furthermore, existing images won't be downloaded again. This essentially lets you resume progress by restarting the script, if it was previously terminated early. - /first-post - /images - potato.png - index.md - /second-post - /images - carrot.jpg - celery.jpg - index.md +To start clean, delete the output folder. -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. +### Frontmatter fields? (`--frontmatter-fields`) - /images - carrot.jpg - celery.jpg - potato.png - first-post.md - second-post.md +Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a frontmatter field, it is left off. Default is `title,date,categories,tags,coverImage,draft`. -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. +Available frontmatter fields are: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. -### Prefix post folders/files with date? +You can rename a frontmatter field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. -**Command line:** `--prefix-date=false` +### Delay between image file requests? (`--request-delay`) -Whether or not to prepend the post date to the post slug when naming a post's folder or file. +### Delay between writing markdown files? (`--write-delay`) -If `--post-folders` is `true`, this affects the folder. +### Timezone to apply to date? (`--timezone`) - /2019-10-14-first-post - index.md - /2019-10-23-second-post - index.md +### Include time with frontmatter date? (`--include-time`) -If `--post-folders` is `false`, this affects the file. +### Frontmatter date format string? (`--date-format`) - 2019-10-14-first-post.md - 2019-10-23-second-post.md +### Wrap frontmatter date in quotes? (`--quote-date`) -### Save images attached to posts? +### Use strict SSL? (`--strict-ssl`) -**Command line:** `--save-attached-images=true` - -Whether or not to download and save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. Images are saved into `/images`. - -### Save images scraped from post body content? - -**Command line:** `--save-scraped-images=true` - -Whether or not to download and save images scraped from `` tags in post body content. Images are saved into `/images`. The `` tags are updated to point to where the images are saved. - -### Include custom post types and pages? - -**Command line:** `--include-other-types=false` - -Some WordPress sites make use of a `"page"` post type and/or custom post types. Set this to `true` to include these post types in the output. Posts will be organized into post type folders. - -## Customizing Frontmatter and Other Advanced Settings - -You can edit [settings.js](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/src/settings.js) to configure advanced settings beyond the options above. This includes things like customizing frontmatter, date formatting, throttling image downloads, and more. - -You'll need to run the script locally (not using `npx`) to edit these advanced settings. - -## Contributing - -Please read the [contribution guidelines](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/CONTRIBUTING.md). diff --git a/src/questions.js b/src/questions.js index 0e9a18b..8b858b3 100644 --- a/src/questions.js +++ b/src/questions.js @@ -90,7 +90,7 @@ export function load() { value: 'scraped' }, { - name: 'Both', + name: 'All Images', value: 'all' }, { From 8969a0b9d05e73fbd61d13693a3d903e829cbe62 Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Fri, 14 Mar 2025 17:04:39 -0400 Subject: [PATCH 2/6] Documented all advanced options --- README.md | 48 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 35f6203..c28cb0e 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ To make things easier, you can rename your WordPress export file to `export.xml` ### Put each post into its own folder? (`--post-folders`) -Whether or not a separate folder is created for each post's Markdown file (and images). Default is `true`. +Whether or not to create a separate folder for each post's Markdown file (and images). Default is `true`. | Value | Description | | --- | --- | @@ -54,7 +54,7 @@ Whether or not a separate folder is created for each post's Markdown file (and i ### Add date prefix to posts? (`--prefix-date`) -Whether or not the post date is prepended when naming a post's folder or file. Default is `false`. +Whether or not to prepend the post date when naming a post's folder or file. Default is `false`. | Value | Description | | --- | --- | @@ -79,7 +79,7 @@ Which images you want to download and save. Default is `all`. | --- | --- | | `attached` | Save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. | | `scraped` | Save images scraped from `` tags in post body content. The `` tags are updated to point to where the images are saved. | -| `all` | Save all images, essentially `attached` and `scraped` together. | +| `all` | Save all images, essentially the results of `attached` and `scraped` combined. | | `none` | Don't save any images. | ## Advanced Options @@ -90,29 +90,57 @@ These are not included in the wizard, so you'll need to set them on the command The path to the output folder where files will be saved. It'll be created if it doesn't exist. Default is `output`. -Existing files in the output folder won't be overwritten. Furthermore, existing images won't be downloaded again. This essentially lets you resume progress by restarting the script, if it was previously terminated early. - -To start clean, delete the output folder. +Existing files in the output folder won't be overwritten. Furthermore, existing images won't be downloaded again. This lets you resume progress by restarting the script, if it was previously terminated early. To start clean, delete the output folder. ### Frontmatter fields? (`--frontmatter-fields`) -Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a frontmatter field, it is left off. Default is `title,date,categories,tags,coverImage,draft`. +Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a field, it is left off. Default is `title,date,categories,tags,coverImage,draft`. -Available frontmatter fields are: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. - -You can rename a frontmatter field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. +Available fields are: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. You can rename a field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. ### Delay between image file requests? (`--request-delay`) +Time (in milliseconds) to wait between requesting image files. Default is `500`. + +Increasing this might help if you see timeouts or server errors. + ### Delay between writing markdown files? (`--write-delay`) +Time (in milliseconds) to wait between saving Markdown files. Default is `10`. + +Increasing this might help if your file system becomes overloaded. + ### Timezone to apply to date? (`--timezone`) +The timezone applied to post dates, as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). Default is `utc`. + ### Include time with frontmatter date? (`--include-time`) +Whether or not time should be included with the date in frontmatter. Default is `false`. + +| Value | Description | +| --- | --- | +| `true` | Time is included using an ISO 8601-compliant format. For example, `2020-12-25T11:20:35.000Z`. | +| `false` | Time is not included. For example, `2020-12-25`. | + ### Frontmatter date format string? (`--date-format`) +A custom formatting string to apply to frontmatter dates, using [these tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens). If set, takes precedence over `--include-time`. Default is an empty string, which falls back to the basic `--` format. + ### Wrap frontmatter date in quotes? (`--quote-date`) +Whether or not to put double quotes around the date when writing it to frontmatter. Default is `false`. + +| Value | Description | +| --- | --- | +| `true` | Adds double quotes around the date. This technically turns the date into a string value. | +| `false` | Doesn't add double quotes. | + ### Use strict SSL? (`--strict-ssl`) +Whether or not to use strict SSL when downloading images. Default is `true`. + +| Value | Description | +| --- | --- | +| `true` | Use strict SSL. This is the safer option. | +| `false` | Don't use strict SSL. This will let you avoid the "self-signed certificate" error when working with a self-signed server. Just make sure you know what you're doing. | From 4f2e027453335d5171b6255426c99fbe875d632c Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Sat, 15 Mar 2025 13:36:35 -0400 Subject: [PATCH 3/6] Trying a different options format --- README.md | 202 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 138 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index c28cb0e..f403e04 100644 --- a/README.md +++ b/README.md @@ -37,110 +37,184 @@ npx wordpress-export-to-markdown --post-folders=false --prefix-date=true The questions, and their command line arguments, are given below. -### Path to WordPress export file? (`--input`) +### Path to WordPress export file? -The path to your [WordPress export file](https://wordpress.org/documentation/article/tools-export-screen/). Default is `export.xml`. +``` +--input=export.xml +``` -To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run the script from. +The path to your [WordPress export file](https://wordpress.org/documentation/article/tools-export-screen/). To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run the script from. -### Put each post into its own folder? (`--post-folders`) +**Allowed values:** -Whether or not to create a separate folder for each post's Markdown file (and images). Default is `true`. +- A path to a file that exists. -| Value | Description | -| --- | --- | -| `true` | A folder is created for each post, with an `index.md` file and `/images` folder within. The post slug is used to name the folder. | -| `false` | The post slug is used to name each post's Markdown file. These files are all saved in the same folder. All images are saved in a shared `/images` folder. | +### Put each post into its own folder? -### Add date prefix to posts? (`--prefix-date`) +``` +--post-folders=true +``` -Whether or not to prepend the post date when naming a post's folder or file. Default is `false`. +Whether or not to create a separate folder for each post's Markdown file (and images). -| Value | Description | -| --- | --- | -| `true` | Prepend the date, in the format `--`. Nothing will be prepended if there is no date (for example, an undated draft post). | -| `false` | Don't prepend the date. | +**Allowed values:** -### Organize posts into date folders? (`--date-folders`) +- `true` - A folder is created for each post, with an `index.md` file and `/images` folder within. The post slug is used to name the folder. +- `false` - The post slug is used to name each post's Markdown file. These files are all saved in the same folder. All images are saved in a shared `/images` folder. -If and how output is organized into folders based on date. Default is `none`. +### Add date prefix to posts? -| Value | Description | -| --- | --- | -| `year` | Output is organized into folders by year. This won't happen for posts with no date (for example, an undated draft post). | -| `year‑month` | Output is organized into folders by year, then into nested folders by month. Again, for posts with no date, this won't happen. | -| `none` | No date folders are created. | +``` +--prefix-date=false +``` -### Save images? (`--save-images`) +Whether or not to prepend the post date when naming a post's folder or file. -Which images you want to download and save. Default is `all`. +**Allowed values:** -| Value | Description | -| --- | --- | -| `attached` | Save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. | -| `scraped` | Save images scraped from `` tags in post body content. The `` tags are updated to point to where the images are saved. | -| `all` | Save all images, essentially the results of `attached` and `scraped` combined. | -| `none` | Don't save any images. | +- `true` - Prepend the date, in the format `--`. Nothing will be prepended if there is no date (for example, an undated draft post). +- `false` - Don't prepend the date. + +### Organize posts into date folders? + +``` +--date-folders=none +``` + +If and how output is organized into folders based on date. + +**Allowed values:** + +- `year` - Output is organized into folders by year. This won't happen for posts with no date (for example, an undated draft post). +- `year‑month` - Output is organized into folders by year, then into nested folders by month. Again, for posts with no date, this won't happen. +- `none` - No date folders are created. + +### Save images? + +``` +--save-images=all +``` + +Which images you want to download and save. + +**Allowed values:** + +- `attached` - Save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. +- `scraped` - Save images scraped from `` tags in post body content. The `` tags are updated to point to where the images are saved. +- `all` - Save all images, essentially the results of `attached` and `scraped` combined. +- `none` - Don't save any images. ## Advanced Options These are not included in the wizard, so you'll need to set them on the command line. -### Path to output folder? (`--output`) +### Path to output folder? -The path to the output folder where files will be saved. It'll be created if it doesn't exist. Default is `output`. +``` +--output=output +``` -Existing files in the output folder won't be overwritten. Furthermore, existing images won't be downloaded again. This lets you resume progress by restarting the script, if it was previously terminated early. To start clean, delete the output folder. +The path to the output folder where files will be saved. It'll be created if it doesn't exist. Existing files in the output folder won't be overwritten and won't be downloaded again. This lets you resume progress by restarting the script, if it was previously terminated early. To start clean, delete the output folder. -### Frontmatter fields? (`--frontmatter-fields`) +**Allowed values:** -Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a field, it is left off. Default is `title,date,categories,tags,coverImage,draft`. +- A valid folder path. -Available fields are: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. You can rename a field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. +### Frontmatter fields? -### Delay between image file requests? (`--request-delay`) +``` +--frontmatter-fields=title,date,categories,tags,coverImage,draft +``` -Time (in milliseconds) to wait between requesting image files. Default is `500`. +Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a field, it is left off. -Increasing this might help if you see timeouts or server errors. +**Allowed values:** -### Delay between writing markdown files? (`--write-delay`) +- A comma separated list with any of the following: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. You can rename a field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. -Time (in milliseconds) to wait between saving Markdown files. Default is `10`. +### Delay between image file requests? -Increasing this might help if your file system becomes overloaded. +``` +--request-delay=500 +``` -### Timezone to apply to date? (`--timezone`) +Time (in milliseconds) to wait between requesting image files. Increasing this might help if you see timeouts or server errors. -The timezone applied to post dates, as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). Default is `utc`. +**Allowed values:** -### Include time with frontmatter date? (`--include-time`) +- Any positive integer. -Whether or not time should be included with the date in frontmatter. Default is `false`. +### Delay between writing markdown files? -| Value | Description | -| --- | --- | -| `true` | Time is included using an ISO 8601-compliant format. For example, `2020-12-25T11:20:35.000Z`. | -| `false` | Time is not included. For example, `2020-12-25`. | +``` +--write-delay=10 +``` -### Frontmatter date format string? (`--date-format`) +Time (in milliseconds) to wait between saving Markdown files. Increasing this might help if your file system becomes overloaded. -A custom formatting string to apply to frontmatter dates, using [these tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens). If set, takes precedence over `--include-time`. Default is an empty string, which falls back to the basic `--` format. +**Allowed values:** -### Wrap frontmatter date in quotes? (`--quote-date`) +- Any positive integer. -Whether or not to put double quotes around the date when writing it to frontmatter. Default is `false`. +### Timezone to apply to date? -| Value | Description | -| --- | --- | -| `true` | Adds double quotes around the date. This technically turns the date into a string value. | -| `false` | Doesn't add double quotes. | +``` +--timezone=utc +``` -### Use strict SSL? (`--strict-ssl`) +The timezone applied to post dates. -Whether or not to use strict SSL when downloading images. Default is `true`. +**Allowed values:** -| Value | Description | -| --- | --- | -| `true` | Use strict SSL. This is the safer option. | -| `false` | Don't use strict SSL. This will let you avoid the "self-signed certificate" error when working with a self-signed server. Just make sure you know what you're doing. | +- A valid timezone, as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). + +### Include time with frontmatter date? + +``` +--include-time=false +``` + +Whether or not time should be included with the date in frontmatter. + +**Allowed values:** + +- `true` - Time is included using an ISO 8601-compliant format. For example, `2020-12-25T11:20:35.000Z`. +- `false` - Time is not included. For example, `2020-12-25`. + +### Frontmatter date format string? + +``` +--date-format="" +``` + +A custom formatting string to apply to frontmatter dates. Takes precedence over `--include-time`. An empty string (the default) is ignored. + +**Allowed values:** + +- A custom formatting string that uses [these tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens). + +### Wrap frontmatter date in quotes? + +``` +--quote-date=false +``` + +Whether or not to put double quotes around the date when writing it to frontmatter. + +**Allowed values:** + +- `true` - Adds double quotes around the date. This technically turns the date into a string value. +- `false` - Doesn't add double quotes. + +### Use strict SSL? + +``` +--strict-ssl=true +``` + +Whether or not to use strict SSL when downloading images. + +**Allowed values:** + +- `true` - Use strict SSL. This is the safer option. +- `false` - Don't use strict SSL. This will let you avoid the "self-signed certificate" error when working with a self-signed server. Just make sure you know what you're doing. From 17d4b755958974f69c9c7d92a09ed7a2df5cb602 Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Sun, 16 Mar 2025 09:16:21 -0400 Subject: [PATCH 4/6] More documentation work --- .github/CONTRIBUTING.md | 10 ----- README.md | 82 +++++++++++++++++++++++++++++------------ src/questions.js | 12 +++--- 3 files changed, 65 insertions(+), 39 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index bdf4c6b..c2dfa4c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -9,13 +9,3 @@ Some quick notes when making a pull request. - Match the style and formatting of the code you are editing. - Each pull request should be focused on a single thing (a single bug fix, a single feature, etc.). This makes reviewing easier and minimizes merge conflicts. - Include a description of the problem being solved and what your code does. Steps to reproduce the problem or example input/output are very helpful. - -## Adding Options - -Keeping the wizard as short as possible is a priority. Pull requests that add options to the wizard will probably not be accepted. Instead, you can add an advanced setting to [settings.js](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/src/settings.js). - -## Adding Frontmatter Fields - -Similarly, default frontmatter output is limited to just a few widely used fields to avoid bloat. However, you may add new optional frontmatter fields to [/src/frontmatter.js](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/src/frontmatter.js). - -Users will be able to include your new frontmatter field by editing `frontmatter_fields` in [settings.js](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/src/settings.js). diff --git a/README.md b/README.md index f403e04..a368029 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,15 @@ Converts a WordPress export XML file into Markdown files. This makes it easy to ![wordpress-export-to-markdown running in a terminal](https://user-images.githubusercontent.com/1245573/72686026-3aa04280-3abe-11ea-92c1-d756a24657dd.gif) +## Table of Contents + +- [Features](#features) +- [Quick Start](#quick-start) +- [Options](#options) +- [Advanced Options](#advanced-options) +- [Local Development](#local-development) +- [Contributing](#contributing) + ## Features - Saves each post as a separate Markdown file with frontmatter. @@ -35,7 +44,7 @@ Optionally, you can provide answers to any of these questions via command line a npx wordpress-export-to-markdown --post-folders=false --prefix-date=true ``` -The questions, and their command line arguments, are given below. +The questions are given below, including a snippet for each one showing its command line argument set to its default value. ### Path to WordPress export file? @@ -43,11 +52,11 @@ The questions, and their command line arguments, are given below. --input=export.xml ``` -The path to your [WordPress export file](https://wordpress.org/documentation/article/tools-export-screen/). To make things easier, you can rename your WordPress export file to `export.xml` and drop it into the same directory that you run the script from. +The path to your [WordPress export file](https://wordpress.org/documentation/article/tools-export-screen/). To make things easier, you can rename it to `export.xml` and drop it into the same directory that you run the script from. -**Allowed values:** +Allowed values: -- A path to a file that exists. +- Any path to a file that exists. ### Put each post into its own folder? @@ -57,7 +66,7 @@ The path to your [WordPress export file](https://wordpress.org/documentation/art Whether or not to create a separate folder for each post's Markdown file (and images). -**Allowed values:** +Allowed values: - `true` - A folder is created for each post, with an `index.md` file and `/images` folder within. The post slug is used to name the folder. - `false` - The post slug is used to name each post's Markdown file. These files are all saved in the same folder. All images are saved in a shared `/images` folder. @@ -70,7 +79,7 @@ Whether or not to create a separate folder for each post's Markdown file (and im Whether or not to prepend the post date when naming a post's folder or file. -**Allowed values:** +Allowed values: - `true` - Prepend the date, in the format `--`. Nothing will be prepended if there is no date (for example, an undated draft post). - `false` - Don't prepend the date. @@ -83,7 +92,7 @@ Whether or not to prepend the post date when naming a post's folder or file. If and how output is organized into folders based on date. -**Allowed values:** +Allowed values: - `year` - Output is organized into folders by year. This won't happen for posts with no date (for example, an undated draft post). - `year‑month` - Output is organized into folders by year, then into nested folders by month. Again, for posts with no date, this won't happen. @@ -97,7 +106,7 @@ If and how output is organized into folders based on date. Which images you want to download and save. -**Allowed values:** +Allowed values: - `attached` - Save images attached to posts. Generally speaking, these are images that were uploaded by using **Add Media** or **Set Featured Image** in WordPress. - `scraped` - Save images scraped from `` tags in post body content. The `` tags are updated to point to where the images are saved. @@ -108,17 +117,30 @@ Which images you want to download and save. These are not included in the wizard, so you'll need to set them on the command line. +### Use wizard? + +``` +--wizard=true +``` + +Whether or not to use the wizard. + +Allowed values: + +- `true` - The script will start with a wizard to ask five questions (the ones from the [Options](#options) section) minus any that were answered on the command line. +- `false` - Skip wizard. Options set via command line are taken, while the rest have their default values used. + ### Path to output folder? ``` --output=output ``` -The path to the output folder where files will be saved. It'll be created if it doesn't exist. Existing files in the output folder won't be overwritten and won't be downloaded again. This lets you resume progress by restarting the script, if it was previously terminated early. To start clean, delete the output folder. +The path to the output folder where files will be saved. It'll be created if it doesn't exist. Existing files there won't be overwritten and won't be downloaded again. This lets you resume progress by restarting the script, if it was previously terminated early. To start clean, delete the output folder. -**Allowed values:** +Allowed values: -- A valid folder path. +- Any valid folder path. ### Frontmatter fields? @@ -128,9 +150,9 @@ The path to the output folder where files will be saved. It'll be created if it Comma separated list of the frontmatter fields to include in Markdown files. Order is preserved. If a post doesn't have a value for a field, it is left off. -**Allowed values:** +Allowed values: -- A comma separated list with any of the following: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. You can rename a field by appending `:` followed by the alias to use. For example, `date:created` will rename `date` to `created`. +- A comma separated list with any of the following: `author`, `categories`, `coverImage`, `date`, `draft`, `excerpt`, `id`, `slug`, `tags`, `title`, `type`. You can rename a field by appending `:` and the alias to use. For example, `date:created` will rename `date` to `created`. ### Delay between image file requests? @@ -140,7 +162,7 @@ Comma separated list of the frontmatter fields to include in Markdown files. Ord Time (in milliseconds) to wait between requesting image files. Increasing this might help if you see timeouts or server errors. -**Allowed values:** +Allowed values: - Any positive integer. @@ -152,7 +174,7 @@ Time (in milliseconds) to wait between requesting image files. Increasing this m Time (in milliseconds) to wait between saving Markdown files. Increasing this might help if your file system becomes overloaded. -**Allowed values:** +Allowed values: - Any positive integer. @@ -164,7 +186,7 @@ Time (in milliseconds) to wait between saving Markdown files. Increasing this mi The timezone applied to post dates. -**Allowed values:** +Allowed values: - A valid timezone, as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). @@ -176,7 +198,7 @@ The timezone applied to post dates. Whether or not time should be included with the date in frontmatter. -**Allowed values:** +Allowed values: - `true` - Time is included using an ISO 8601-compliant format. For example, `2020-12-25T11:20:35.000Z`. - `false` - Time is not included. For example, `2020-12-25`. @@ -187,11 +209,11 @@ Whether or not time should be included with the date in frontmatter. --date-format="" ``` -A custom formatting string to apply to frontmatter dates. Takes precedence over `--include-time`. An empty string (the default) is ignored. +A custom formatting string to apply to frontmatter dates. If set, takes precedence over `--include-time`. An empty string (the default) is ignored, resulting in the basic `--` format. -**Allowed values:** +Allowed values: -- A custom formatting string that uses [these tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens). +- Any valid custom formatting string. See [this table of tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens). ### Wrap frontmatter date in quotes? @@ -201,9 +223,9 @@ A custom formatting string to apply to frontmatter dates. Takes precedence over Whether or not to put double quotes around the date when writing it to frontmatter. -**Allowed values:** +Allowed values: -- `true` - Adds double quotes around the date. This technically turns the date into a string value. +- `true` - Adds double quotes. This technically turns the date into a string value. - `false` - Doesn't add double quotes. ### Use strict SSL? @@ -214,7 +236,21 @@ Whether or not to put double quotes around the date when writing it to frontmatt Whether or not to use strict SSL when downloading images. -**Allowed values:** +Allowed values: - `true` - Use strict SSL. This is the safer option. - `false` - Don't use strict SSL. This will let you avoid the "self-signed certificate" error when working with a self-signed server. Just make sure you know what you're doing. + +## Local Development + +You can install and run this script locally if you want to tinker with it: + +1. `git clone` this repo. +2. `cd` into the repo directory. +3. Run `npm install`. + +Now instead of running `npx wordpress-export-to-markdown` you can run `node app`. They both take all the same command line arguments in the same way. + +## Contributing + +Please read the [contribution guidelines](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/.github/CONTRIBUTING.md). diff --git a/src/questions.js b/src/questions.js index 8b858b3..fb1e55a 100644 --- a/src/questions.js +++ b/src/questions.js @@ -4,12 +4,6 @@ export function load() { // questions with a description are displayed in command line help // questions with a prompt are included in the wizard (if not set on the command line) return [ - { - name: 'wizard', - type: 'boolean', - description: 'Use wizard', - default: true - }, { name: 'input', type: 'file-path', @@ -100,6 +94,12 @@ export function load() { ], prompt: inquirer.select }, + { + name: 'wizard', + type: 'boolean', + description: 'Use wizard', + default: true + }, { name: 'output', type: 'folder-path', From b205b04bc4aee9a5b365f584eff6e0af6c7d3334 Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Sun, 16 Mar 2025 12:23:25 -0400 Subject: [PATCH 5/6] Small doc tweak --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a368029..7ff4da9 100644 --- a/README.md +++ b/README.md @@ -188,7 +188,7 @@ The timezone applied to post dates. Allowed values: -- A valid timezone, as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). +- Any valid timezone as [specified here](https://moment.github.io/luxon/#/zones?id=specifying-a-zone). ### Include time with frontmatter date? From 411f788b8e152ac8807f2e447508ea30a3e9d795 Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Sun, 16 Mar 2025 12:35:25 -0400 Subject: [PATCH 6/6] Remove table of contents --- README.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/README.md b/README.md index 7ff4da9..ba6c826 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,6 @@ Converts a WordPress export XML file into Markdown files. This makes it easy to ![wordpress-export-to-markdown running in a terminal](https://user-images.githubusercontent.com/1245573/72686026-3aa04280-3abe-11ea-92c1-d756a24657dd.gif) -## Table of Contents - -- [Features](#features) -- [Quick Start](#quick-start) -- [Options](#options) -- [Advanced Options](#advanced-options) -- [Local Development](#local-development) -- [Contributing](#contributing) - ## Features - Saves each post as a separate Markdown file with frontmatter.