posthtml / posthtml-url-parameters

Add parameters to URLs with PostHTML.

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>

posthtml-url-parameters's Issues

Upgrade is-url-superb to 4.0.0 to fix a bug

Problem

Described here in the Maizzle project; template variables in a URL break Maizzle's urlParameters functionality.

Environment

• posthtml-url-parameters plugin version: 1.0.2
• PostHTML version: 0.13.0
• Node.js version: 13.8.0

The Test + Fix

Looks like the fix is to upgrade is-url-superb from 3.0.0 to 4.0.0; this code returns false with 3.0.0, but true with 4.0.0 (I used repl.it):

require('is-url-superb')('https://example.com/{{ var }}')

transfer is done

Support other tags/attributes

Would be useful to be able to add parameters to URLs in img tags, for example. Right now the plugin only looks for the href attribute, which means using it on img or other tags that use src/srcset/source is impossible.

posthtml([
    urlParams({
      parameters: { utm_source: 'maizzle', utm_campaign: 'Campaign Name', utm_medium: 'email', }
    })
  ])
  .process('<img src="https://example.com/image.png">')
  .then(result => console.log(result.html)))

Result:

<img src="https://example.com/image.png?utm_campaign=Campaign%20Name&utm_medium=email&utm_source=maizzle">