Update & expand README documentation, standardize configuration optio…

…ns (#28)

* Update & expand README documentation

* Standardize on lowercase option names; allow top-level lastmod string

* Additional tweaks to README

* Add second path example for object paths

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.7.1
+
+* Updated and expanded README documentation
+* Standardize on non-camel-cased configuration values for consistency with underlying `sitemap` package (camel-cased values are still supported for backwards compatibility)
+* Allow providing a top-level date string for `lastmod` (if a boolean `true` is provided, the current date will still be used for backwards compatibility)
+
 ## 0.7.0
 
 * Switched to [sitemap](https://www.npmjs.com/package/sitemap) package for generating sitemaps under the hood, which provides more configuration options

README.md

@@ -2,102 +2,118 @@
 
 # sitemap-webpack-plugin
 
-Webpack plugin to generate a sitemap. Designed to work with [static-site-generator-webpack-plugin](https://github.com/markdalgleish/static-site-generator-webpack-plugin/) (although it also works great by itself).
+Webpack plugin to generate a sitemap from a list of paths.
 
 ## Installation
 
     npm install sitemap-webpack-plugin --save-dev
 
-For webpack 4, use version 0.6 or greater. For webpack <= 3, use version 0.5.x.
+For webpack 4 or 5, use version 0.6 or greater. For webpack <= 3, use version 0.5.x.
 
 ## Usage
 
 Add to your webpack config -- see below for examples. The plugin signature is:
 
     new SitemapPlugin(base, paths, options)
 
-* `base` is the root URL of your site (e.g. 'https://mysite.com')
-* `paths` is the array of locations on your site -- this can be the same one you pass to `static-site-generator-webpack-plugin`. If you want to customize each path in the sitemap, you can also pass an array of objects; objects must have a `path` attribute and may have a `lastMod`, `priority`, and/or `changeFreq` attribute. (However, an array of objects will not be directly compatible with `static-site-generator-webpack-plugin`.)
-* `options` is an optional object of configurable options -- see below
+* `base` is the root URL of your site (e.g. `https://mysite.com`)
+* `paths` is the array of locations on your site. These can be simple strings or you can provide objects if you would like to customize each entry; objects must have a `path` attribute and may have other attributes documented [below](#path-specific-options).
+* `options` is an optional object of top-level configuration settings.
 
 ### Options
 
-* `fileName` (string) -- default `sitemap.xml` -- name of the output file
-* `skipGzip` (boolean) -- default `false` -- whether to skip generating a gzipped `.xml.gz` sitemap. (By default, both an uncompressed and a compressed sitemap are generated -- the compressed version is generated at `sitemap.xml.gz`, or `[fileName].gz` if the `fileName` configuration option is set.)
-* `formatter` (function) -- default `null` -- an optional function to format the generated sitemap before it is emitted (for example, if you'd like to pretty-print the XML). The provided function must accept one argument (the unformatted XML) and return the formatted XML as a string. For an example of pretty-printing configuration, see the [formatted test](https://github.com/schneidmaster/sitemap-webpack-plugin/blob/master/test/success-cases/formatted/webpack.config.js).
-* `lastmod` (boolean) -- default `false` -- whether to include the current date as the `<lastmod>`. Can be overridden by path-specific `lastmod`.
-* `priority` (number) -- default `null` -- a `<priority>` to be set globally on all locations. Can be overridden by path-specific `priority`.
-* `changefreq` (string) -- default `null` -- a `<changefreq>` to be set globally on all locations; list of applicable values based on [sitemaps.org](http://www.sitemaps.org/protocol.html): `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. Can be overridden by path-specific `changefreq`.
-* This library uses the [sitemap](https://www.npmjs.com/package/sitemap) package under the hood, so you can also provide [any other options](https://www.npmjs.com/package/sitemap#example-of-most-of-the-options-you-can-use-for-sitemap) that `sitemap` supports.
+The following options may be provided in the top-level `options` argument to the plugin constructor. This library uses the [sitemap](https://www.npmjs.com/package/sitemap) package under the hood, so you can also provide [any other options](https://www.npmjs.com/package/sitemap#example-of-most-of-the-options-you-can-use-for-sitemap) that `sitemap` supports.
 
-### webpack.config.js
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `filename` | `string` | `sitemap.xml` | Name of the sitemap file emitted to your build output |
+| `skipgzip` | `boolean` | `false` | Whether to skip generating a gzipped `.xml.gz` sitemap. (By default, both an uncompressed and a compressed sitemap are generated -- the compressed version is generated at `sitemap.xml.gz`, or `[filename].gz` if the `filename` configuration option is set.) |
+| `formatter` | `function` | `undefined` | An optional function to format the generated sitemap before it is emitted (for example, if you'd like to pretty-print the XML). The provided function must accept one argument (the unformatted XML) and return the formatted XML as a string. For an example of pretty-printing configuration, see the [formatted test](https://github.com/schneidmaster/sitemap-webpack-plugin/blob/master/test/success-cases/formatted/webpack.config.js). |
+| `lastmod` | `string` / `boolean` | `false` | The date value for `<lastmod>` on all paths. Can be overridden by path-specific `lastmod` setting. If set to boolean `true`, the current date will be used for all paths; otherwise, the provided date string will be used. |
+| `priority` | `number` | `undefined` | A `<priority>` to be set globally on all locations. Can be overridden by path-specific `priority`. |
+| `changefreq` | `string` | `undefined` | A `<changefreq>` to be set globally on all locations; list of applicable values based on [sitemaps.org](http://www.sitemaps.org/protocol.html): `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. Can be overridden by path-specific `changefreq`. |
 
-```js
-import SitemapPlugin from 'sitemap-webpack-plugin';
+### Path-specific options
+
+If you choose to provide the paths as an array of objects, the following attributes may be set on each path object. This library uses the [sitemap](https://www.npmjs.com/package/sitemap) package under the hood, so you can also provide [any other options](https://www.npmjs.com/package/sitemap#example-of-most-of-the-options-you-can-use-for-sitemap) that `sitemap` supports.
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `path` (required) | `string` | N/A | The URL path, e.g. `/some/page` |
+| `lastmod` | `string` | `false` | The date value for `<lastmod>` -- when this path was last modified. |
+| `priority` | `number` | `undefined` | A numerical `<priority>` to be set on the path. |
+| `changefreq` | `string` | `undefined` | The `<changefreq>` to be set on the path; list of applicable values based on [sitemaps.org](http://www.sitemaps.org/protocol.html): `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. |
 
-// If you are not using babel, note that the plugin is exported on default so you will need e.g.
+### Example webpack.config.js
+
+```js
 const SitemapPlugin = require('sitemap-webpack-plugin').default;
 
-/* basic paths -- directly compatible with static-site-generator-webpack-plugin */
+// Example of simple string paths
 const paths = [
   '/foo/',
   '/bar/'
 ];
 
-/* object paths -- more fine-grained but not directly compatible with static-site-generator-webpack-plugin */
-/* object paths must have a `path` attribute -- others are optional, and fall back to global config (if any) */
+// Example of object paths
+// Object paths must have a `path` attribute -- others are optional,
+// and fall back to global config (if any)
 const paths = [
   {
     path: '/foo/',
-    lastMod: '2015-01-04',
+    lastmod: '2015-01-04',
     priority: '0.8',
-    changeFreq: 'monthly'
+    changefreq: 'monthly'
+  },
+  {
+    path: '/bar/',
+    lastmod: '2018-02-05',
+    priority: '0.5',
+    changefreq: 'yearly'
   }
 ];
 
-/* you can also convert object paths back into static-site-generator-webpack-plugin compatible paths */
-const staticSiteGeneratorCompatiblePaths = paths.map(({path}) => path);
-
+// Example webpack configuration -- input/output/etc. omitted for brevity.
 export default {
-
-  /* snip */
-
-  /* basic (output defaults to sitemap.xml) */
+  // Basic usage (output defaults to sitemap.xml)
   plugins: [
     new SitemapPlugin('https://mysite.com', paths)
   ]
 
-  /* with custom output filename */
+  // With custom output filename
   plugins: [
     new SitemapPlugin('https://mysite.com', paths, {
-      fileName: 'map.xml'
+      filename: 'map.xml'
     })
   ]
 
-  /* skip generating a gzipped version of the sitemap */
+  // Skip generating a gzipped version of the sitemap
   plugins: [
     new SitemapPlugin('https://mysite.com', paths, {
-      skipGzip: true
+      skipgzip: true
     })
   ]
 
-  /* with global options */
+  // With global options
   plugins: [
     new SitemapPlugin('https://mysite.com', paths, {
-      fileName: 'map.xml',
-      lastMod: true,
-      changeFreq: 'monthly',
+      filename: 'map.xml',
+      lastmod: true,
+      changefreq: 'monthly',
       priority: '0.4'
     })
   ]
-
 };
 ```
 
 ## Contributing
 
-1. Fork it (https://github.com/schneidmaster/sitemap-webpack-plugin/fork)
+1. Fork the repository (https://github.com/schneidmaster/sitemap-webpack-plugin/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+5. Create a new pull request
+
+## License
+
+MIT

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sitemap-webpack-plugin",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Webpack plugin to generate a sitemap.",
   "main": "lib/index.js",
   "scripts": {

src/index.js

@@ -22,22 +22,31 @@ export default class SitemapWebpackPlugin {
     if (typeof options === "undefined") {
       options = {};
     }
-    options = normalizeOptions(options, ["lastMod", "changeFreq"]);
+    options = normalizeOptions(options, [
+      "changeFreq",
+      "fileName",
+      "lastMod",
+      "skipGzip"
+    ]);
 
     const {
-      fileName,
-      skipGzip,
+      filename,
+      skipgzip,
       formatter,
       lastmod,
       changefreq,
       priority,
       ...rest
     } = options;
-    this.fileName = fileName || "sitemap.xml";
-    this.skipGzip = skipGzip || false;
+    this.filename = filename || "sitemap.xml";
+    this.skipgzip = skipgzip || false;
     this.formatter = formatter || null;
     if (lastmod) {
-      this.lastmod = generateDate();
+      if (typeof lastmod === "string") {
+        this.lastmod = lastmod;
+      } else {
+        this.lastmod = generateDate();
+      }
     }
     this.changefreq = changefreq;
     this.priority = priority;
@@ -103,8 +112,8 @@ export default class SitemapWebpackPlugin {
         try {
           sitemap = await this.generate();
 
-          compilation.fileDependencies.add(this.fileName);
-          compilation.assets[this.fileName] = {
+          compilation.fileDependencies.add(this.filename);
+          compilation.assets[this.filename] = {
             source: () => {
               return sitemap;
             },
@@ -116,12 +125,12 @@ export default class SitemapWebpackPlugin {
           compilation.errors.push(err.stack);
         }
 
-        if (sitemap !== null && this.skipGzip !== true) {
+        if (sitemap !== null && this.skipgzip !== true) {
           zlib.gzip(sitemap, (err, compressed) => {
             if (err) {
               compilation.errors.push(err.stack);
             } else {
-              compilation.assets[`${this.fileName}.gz`] = {
+              compilation.assets[`${this.filename}.gz`] = {
                 source: () => {
                   return compressed;
                 },

test/success-cases/global-opts-lastmod/desc.js

@@ -0,0 +1 @@
+export default "Sitemap with options set globally and lastmod as a date string";

test/success-cases/global-opts-lastmod/expected-output/sitemap.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"><url><loc>https://mysite.com/</loc><lastmod>2019-06-01T00:00:00.000Z</lastmod><changefreq>monthly</changefreq><priority>0.4</priority></url><url><loc>https://mysite.com/about</loc><lastmod>2019-06-01T00:00:00.000Z</lastmod><changefreq>monthly</changefreq><priority>0.4</priority></url></urlset>

test/success-cases/global-opts-lastmod/webpack.config.js

@@ -0,0 +1,19 @@
+import SitemapPlugin from "../../../src/";
+
+export default {
+  entry: () => [],
+  output: {
+    filename: "index.js",
+    path: `${__dirname}/actual-output`,
+    libraryTarget: "umd"
+  },
+
+  plugins: [
+    new SitemapPlugin("https://mysite.com", ["/", "/about"], {
+      fileName: "sitemap.xml",
+      lastMod: "2019-06-01",
+      changeFreq: "monthly",
+      priority: "0.4"
+    })
+  ]
+};