# gulp-sitemap

> Generate a search engine friendly sitemap.xml using a Gulp stream

Latest version **8.0.0** (published 2020-12-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-sitemap
pnpm add gulp-sitemap
yarn add gulp-sitemap
bun add gulp-sitemap
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 8.0.0 |
| Published | 2020-12-08 |
| First published | 2014-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 8 |
| Unpacked size | 17.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 60 |
| Author | Gilad Peleg |
| Maintainers | pgilad |
| Keywords | gulpplugin, gulp, js, javascript, SEO, sitemap, sitemap.xml, Google, search-engine, xml |

## Links

- npm: https://www.npmjs.com/package/gulp-sitemap
- Repository: https://github.com/pgilad/gulp-sitemap
- Homepage: https://github.com/pgilad/gulp-sitemap#readme
- Issues: https://github.com/pgilad/gulp-sitemap/issues
- npm.io page: https://npm.io/package/gulp-sitemap

## Dependencies (8)

- [chalk](https://npm.io/package/chalk.md) ^2.4.2
- [slash](https://npm.io/package/slash.md) ^3.0.0
- [vinyl](https://npm.io/package/vinyl.md) ^2.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [through2](https://npm.io/package/through2.md) ^3.0.1
- [fancy-log](https://npm.io/package/fancy-log.md) ^1.3.3
- [multimatch](https://npm.io/package/multimatch.md) ^4.0.0
- [plugin-error](https://npm.io/package/plugin-error.md) ^1.0.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 8.0.0 (latest) — 2020-12-08
- 7.7.0 — 2020-12-08
- 7.6.0 — 2019-10-19
- 7.5.0 — 2019-09-02
- 7.4.0 — 2019-07-12
- 7.3.0 — 2019-06-19
- 7.2.0 — 2019-06-12
- 7.1.0 — 2019-06-05
- 7.0.0 — 2019-06-05
- 6.2.0 — 2019-02-08
- 6.1.0 — 2018-11-03
- 6.0.1 — 2018-09-25
- 6.0.0 — 2018-09-24
- 5.1.0 — 2018-03-27
- 5.0.0 — 2018-01-04
- … 40 more at https://npm.io/package/gulp-sitemap/versions

## README

# [gulp](https://github.com/wearefractal/gulp)-sitemap
> Generate a search engine friendly sitemap.xml using a Gulp stream

[![NPM version](http://img.shields.io/npm/v/gulp-sitemap.svg?style=flat)](https://www.npmjs.org/package/gulp-sitemap)
[![NPM Downloads](http://img.shields.io/npm/dm/gulp-sitemap.svg?style=flat)](https://www.npmjs.org/package/gulp-sitemap)
[![Build Status](http://img.shields.io/travis/pgilad/gulp-sitemap/master.svg?style=flat)](https://travis-ci.org/pgilad/gulp-sitemap)

Easily generate a search engine friendly sitemap.xml from your project.

:bowtie: Search engines love the sitemap.xml and it helps SEO as well.

For information about sitemap properties and structure, see the [wiki for sitemaps](http://www.wikiwand.com/en/Sitemaps)

## Install

Install with [npm](https://npmjs.org/package/gulp-sitemap)

```bash
$ npm install --save-dev gulp-sitemap
```

## Example

```js
var gulp = require('gulp');
var sitemap = require('gulp-sitemap');

gulp.task('sitemap', function () {
    gulp.src('build/**/*.html', {
            read: false
        })
        .pipe(sitemap({
            siteUrl: 'http://www.amazon.com'
        }))
        .pipe(gulp.dest('./build'));
});
```

* `siteUrl` is required.
* `index.html` will be turned into directory path `/`.
* `404.html` will be skipped automatically. No need to unglob it.

Let's see an example of how we can create and output a sitemap, and then return to the original stream files:
```js
var gulp = require('gulp');
var sitemap = require('gulp-sitemap');
var save = require('gulp-save');

gulp.task('html', function() {
    gulp.src('*.html', {
          read: false
        })
        .pipe(save('before-sitemap'))
        .pipe(sitemap({
                siteUrl: 'http://www.amazon.com'
        })) // Returns sitemap.xml
        .pipe(gulp.dest('./dist'))
        .pipe(save.restore('before-sitemap')) //restore all files to the state when we cached them
        // -> continue stream with original html files
        // ...
});
```

## Options

### siteUrl

Your website's base url. This gets prepended to all documents locations.

Type: `string`

Required: `true`

### fileName

Determine the output filename for the sitemap.

Type: `string`

Default: `sitemap.xml`

Required: `false`

### changefreq

Gets filled inside the sitemap in the tag `<changefreq>`. Not added by default.

Type: `string`

Default: `undefined`

Valid Values: `['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']`

Required: `false`

**Note: any falsey value is also valid and will skip this xml tag**

### priority

Gets filled inside the sitemap in the tag `<priority>`. Not added by default.

Type: `string|function`

Default: `undefined`

Valid Values: `0.0` to `1.0`

Required: `false`

**Note: any falsey (non-zero) value is also valid and will skip this xml tag**

Example using a function as `priority`:


```js
priority: function(siteUrl, loc, entry) {
    // Give pages inside root path (i.e. no slashes) a higher priority
    return loc.split('/').length === 0 ? 1 : 0.5;
}
```

### lastmod

The file last modified time.

- If `null` then this plugin will try to get the last modified time from the stream vinyl file, or use `Date.now()` as lastmod.
- If the value is not `null` - It will be used as lastmod.
- When `lastmod` is a function, it is executed with the current file given as parameter. (Note: the function is expected to be sync).
- A string can be used to manually set a fixed `lastmod`.

Type: `string|datetime|function`

Default: `null`

Required: `false`

Example that uses git to get lastmod from the latest commit of a file:

```js
lastmod: function(file) {
  var cmd = 'git log -1 --format=%cI "' + file.relative + '"';
  return execSync(cmd, {
    cwd: file.base
  }).toString().trim();
}
```

**Note: any falsey (other than null) value is also valid and will skip this xml tag**

### newLine

How to join line in the target sitemap file.

Type: `string`

Default: Your OS's new line, mostly: `\n`

Required: `false`

### spacing

How should the sitemap xml file be spaced. You can use `\t` for tabs, or `  ` with 2
spaces if you'd like.

Type: `string`

Default: `    ` (4 spaces)

Required: `false`

### noindex

Exclude pages from the sitemap when the `robots` meta tag is set to `noindex`. The plugin needs to be able to read the contents of the files for this to have an effect.

Type: `boolean`

Default: `false`

Required: `false`

### images

For generate sitemap for images per page, just enable images flag to `true`

Type: `boolean`

Default: `undefined`

Required: `false`


### mappings

An object to custom map pages to their own configuration.

This should be an array with the following structure:

Type: `array`

Default: `[]`

Required: `false`

Example:

```js
mappings: [{
    pages: [ 'minimatch pattern' ],
    changefreq: 'hourly',
    priority: 0.5,
    lastmod: Date.now(),
    getLoc(siteUrl, loc, entry) {
        // Removes the file extension if it exists
        return loc.replace(/\.\w+$/, '');
    },
    hreflang: [{
        lang: 'ru',
        getHref(siteUrl, file, lang, loc) {
            return 'http://www.amazon.ru/' + file;
        }
    }]
},
//....
]
```

- Every file will be matched against the supplied patterns
- Only defined attributes for a matched file are applied.
- Only the first match will apply, so consequent matches for the filename will not apply.
- Possible attributes to set: `hreflang`, `changefreq`, `priority`, `loc` and `lastmod`.
- All rules applying to [options](#options) apply to the attributes that can overridden.

##### pages

Type: `array`

Required: `true`

This is an array with [minimatch](https://github.com/isaacs/minimatch) patterns to match the
relevant pages to override.
Every file will be matched against the supplied patterns.

Uses [multimatch](https://github.com/sindresorhus/multimatch) to match patterns against filenames.

Example: `pages: ['home/index.html', 'home/see-*.html', '!home/see-admin.html']`

##### hreflang

Matching pages can get their `hreflang` tags set using this option.

The input is an array like so:

```js
hreflang: [{
    lang: 'ru',
    getHref: function(siteUrl, file, lang, loc) {
        // return href src for the hreflang. For example:
        return 'http://www.amazon.ru/' + file;
    }
}]
```

##### getLoc

Matching pages can get their `loc` tag modified by using a function.

```js
getLoc: function(siteUrl, loc, entry) {
    return loc.replace(/\.\w+$/, '');
}
```

#### verbose

Type: `boolean`

Required: `false`

Default: `false`

If true, will log the number of files that where handled.

## Complementary plugins

- [gulp-sitemap-files](https://github.com/adam-lynch/gulp-sitemap-files) - Get all files listed in a sitemap (Perhaps one generated from this plugin)

## Thanks

To [grunt-sitemap](https://github.com/RayViljoen/grunt-sitemap) for the inspiration on writing this.

## License

MIT © [Gilad Peleg](https://www.giladpeleg.com)

---
_Source: https://npm.io/package/gulp-sitemap · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._