URL Parameters

Add parameters to URLs

About

This is a PostHTML plugin that allows you to add query string parameters to URLs.

Install

npm i posthtml posthtml-url-parameters

Usage

import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'

posthtml([
  urlParams({
    parameters: { foo: 'bar', baz: 'qux' }
  })
])
  .process('<a href="https://example.com">Test</div>')
  .then(result => console.log(result.html)))

// <a href="https://example.com?baz=qux&foo=bar">Test</div>

Configuration

parameters

Type: Object
Default: undefined

Object containing parameter name (key) and its value.

Example:

import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'

posthtml([
  urlParams({
    parameters: {
      utm_source: 'Campaign',
      '1stDraft': true
    }
  })
])
  .process('<a href="https://example.com">Test</a>')
  .then(result => console.log(result.html))

tags

Type: Array
Default: ['a']

Array of tag names to process.

By default, only URLs inside known attributes of tags in this array will be processed.

Example:

import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'

posthtml([
  urlParams({
    tags: ['a', 'img']
  })
])
  .process(`
    <a href="https://example.com">Test</a>
    <img src="https://example.com/image.jpg">
  `)
  .then(result => console.log(result.html))

You may use some CSS selectors when specifying tags:

posthtml([
  urlParams({
    tags: ['a.button', 'a[href*="example.com"]' 'link'],
  })
])
  .process(/*...*/)

All posthtml-match-helper selectors are supported.

attributes

Type: Array
Default: ['src', 'href', 'poster', 'srcset', 'background']

Array of attributes to process for the given tags.

You may override this with your own list of attributes - the plugin will only process URLs in these attributes.

posthtml([
  urlParams({
    parameters: {foo: 'bar'},
    attributes: ['data-href']
  })
])
  .process('<a href="foo.html" data-href="https://example.com">Test</a>')
  .then(result => console.log(result.html)))

// <a href="foo.html" data-href="https://example.com?foo=bar">Test</a>

strict

Type: Boolean
Default: false

By default, the plugin will append query parameters only to valid URLs.

You may disable strict mode to append parameters to any string:

import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'

posthtml([
  urlParams({
    parameters: { foo: 'bar' },
    strict: false,
  })
])
  .process('<a href="https://example.com/campaigns/{{ id }}">Details</a>')
  .then(result => console.log(result.html)))

// <a href="https://example.com/campaigns/{{ id }}?foo=bar">Details</a>

qs

Type: Object
Default: undefined

Options to pass to query-string - see available options here.

For example, you may disable encoding:

import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'

posthtml([
  urlParams({
    parameters: { foo: '@Bar@' },
    qs: {
      encode: false
    }
  })
])
  .process('<a href="https://example.com">Test</a>')
  .then(result => console.log(result.html)))

// <a href="https://example.com?foo=@Bar@">Test</a>