From 27930c6545308ad3d1e46e3ca079b9832bc88dec Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Wed, 28 Feb 2024 09:36:40 -0500 Subject: [PATCH 1/4] Stuff above options --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e326453..d97bab9 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ # wordpress-export-to-markdown -A script that converts a WordPress export XML file into Markdown files suitable for a static site generator ([Gatsby](https://www.gatsbyjs.org/), [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/), etc.). +Converts a WordPress export file into Markdown files that are compatible with static site generators ([Eleventy](https://www.11ty.dev/), [Gatsby](https://www.gatsbyjs.org/), [Hugo](https://gohugo.io/), etc.). -Each post is saved as a separate Markdown file with appropriate frontmatter. Images are also downloaded and saved. Embedded content from YouTube, Twitter, CodePen, etc. is carefully preserved. +Each post is saved as a separate Markdown file with frontmatter. Images are also downloaded and saved. Embedded content from YouTube, Twitter, CodePen, etc. is carefully preserved. ![wordpress-export-to-markdown running in a terminal](https://user-images.githubusercontent.com/1245573/72686026-3aa04280-3abe-11ea-92c1-d756a24657dd.gif) ## Quick Start You'll need: -- [Node.js](https://nodejs.org/) v12.14 or later -- Your [WordPress export file](https://wordpress.org/support/article/tools-export-screen/) (be sure to export "All content" if you want to save images and/or pages) +- [Node.js](https://nodejs.org/) installed +- Your [WordPress export file](https://wordpress.org/support/article/tools-export-screen/) (be sure to export "All content"). -It is recommended that you drop your WordPress export file into the same directory that you run this script from so it's easy to find. +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. You can run this script immediately in your terminal with `npx`: @@ -20,17 +20,17 @@ You can run this script immediately in your terminal with `npx`: npx wordpress-export-to-markdown ``` -Or you can clone and run (this makes repeated runs faster and allows you to tinker with the code). After cloning this repo, open your terminal to the package's directory and run: +Or you can clone this repo, then from within the repo's directory, install and run: ``` npm install && node index.js ``` -Either way you run it, the script will start the wizard. Answer the questions and off you go! +Either way, the script will start a wizard to configure your options. Answer the questions and off you go! ## Command Line -The wizard makes it easy to configure your options, but you can also do so via the command line if you want. For example, the following will give you [Jekyll](https://jekyllrb.com/)-style output in terms of folder structure and filenames. +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`: @@ -44,7 +44,7 @@ Using a locally cloned repo: node index.js --post-folders=false --prefix-date=true ``` -The wizard will still ask you about any options not specifed on the command line. To skip the wizard entirely and use default values for unspecified options, add `--wizard=false`. +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`. ## Options From c0db27a1547c8fc3883fb52d233ea5ff02a2415a Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Wed, 28 Feb 2024 13:20:32 -0500 Subject: [PATCH 2/4] Reformatting options --- README.md | 60 +++++++++++++++++++------------------------------------ 1 file changed, 20 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index d97bab9..4c6a170 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Converts a WordPress export file into Markdown files that are compatible with static site generators ([Eleventy](https://www.11ty.dev/), [Gatsby](https://www.gatsbyjs.org/), [Hugo](https://gohugo.io/), etc.). -Each post is saved as a separate Markdown file with frontmatter. Images are also downloaded and saved. Embedded content from YouTube, Twitter, CodePen, etc. is carefully preserved. +Each post is saved as a separate Markdown file with frontmatter. Images are downloaded and saved. ![wordpress-export-to-markdown running in a terminal](https://user-images.githubusercontent.com/1245573/72686026-3aa04280-3abe-11ea-92c1-d756a24657dd.gif) @@ -48,51 +48,33 @@ The wizard will still ask you about any options not specified on the command lin ## Options -### Use wizard? - -- Argument: `--wizard` -- Type: `boolean` -- Default: `true` - -Enable to have the script prompt you for each option. Disable to skip the wizard and use default values for any options not specified via the command line. - ### Path to WordPress export file? -- Argument: `--input` -- Type: `file` (as a path string) -- Default: `export.xml` +**Command line:** `--input=export.xml` -The path to the WordPress export file that you want to parse. It is recommended that you drop your WordPress export file into the same directory that you run this script from so it's easy to find. +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. ### Path to output folder? -- Argument: `--output` -- Type: `folder` (as a path string) -- Default: `output` +**Command line:** `--output=output` -The path to the output directory where Markdown and image files will be saved. If it does not exist, it will be created for you. +The path to the output directory where Markdown and image files will be saved. If it does not exist, it will be created. ### Create year folders? -- Argument: `--year-folders` -- Type: `boolean` -- Default: `false` +**Command line:** `--year-folders=false` Whether or not to organize output files into folders by year. ### Create month folders? -- Argument: `--month-folders` -- Type: `boolean` -- Default: `false` +**Command line:** `--month-folders=false` 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. ### Create a folder for each post? -- Argument: `--post-folders` -- Type: `boolean` -- Default: `true` +**Command line:** `--post-folders=true` Whether or not to save files and images into post folders. @@ -121,9 +103,7 @@ Either way, this can be combined with with `--year-folders` and `--month-folders ### Prefix post folders/files with date? -- Argument: `--prefix-date` -- Type: `boolean` -- Default: `false` +**Command line:** `--prefix-date=false` Whether or not to prepend the post date to the post slug when naming a post's folder or file. @@ -141,27 +121,27 @@ If `--post-folders` is `false`, this affects the file. ### Save images attached to posts? -- Argument: `--save-attached-images` -- Type: `boolean` -- Default: `true` +**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** when editing a post in WordPress. Images are saved into `/images`. +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? -- Argument: `--save-scraped-images` -- Type: `boolean` -- Default: `true` +**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? -- Argument: `--include-other-types` -- Type: `boolean` -- Default: `false` +**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 results. Posts will be organized into post type folders. +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. + +### Use wizard? + +**Command line:** `--wizard=true` + +Enable to have the script prompt you for each option. Disable to skip the wizard and use default values for any options not specified via the command line. ## Advanced Settings From 220225fca6ec42c08f66d0d6e94ffb66d1db807e Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Wed, 28 Feb 2024 13:58:17 -0500 Subject: [PATCH 3/4] Finish updating README --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4c6a170..fe83ced 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,8 @@ The wizard will still ask you about any options not specified on the command lin ## Options +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. + ### Path to WordPress export file? **Command line:** `--input=export.xml` @@ -137,14 +139,12 @@ Whether or not to download and save images scraped from `` tags in post bod 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. -### Use wizard? +## Customizing Frontmatter and Other Advanced Settings -**Command line:** `--wizard=true` +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. -Enable to have the script prompt you for each option. Disable to skip the wizard and use default values for any options not specified via the command line. +You'll need to run the script locally (not using `npx`) to edit these advanced settings. -## Advanced Settings +## Contributing -You can edit [settings.js](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/src/settings.js) to tweak advanced settings. This includes things like customizing frontmatter fields and throttling image downloads. - -You'll need to run the script locally (not using `npx`) to make use of advanced settings. +Please read the [contribution guidelines](https://github.com/lonekorean/wordpress-export-to-markdown/blob/master/CONTRIBUTING.md). From dde87ba3bc4ba5eba41fe6631a547df7088e371d Mon Sep 17 00:00:00 2001 From: Will Boyd Date: Wed, 28 Feb 2024 14:03:44 -0500 Subject: [PATCH 4/4] Minor link update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fe83ced..b4f99ad 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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.org/), [Hugo](https://gohugo.io/), etc.). +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.