URL Parameters

Maizzle can automatically append custom parameters to your URLs.

Usage

To add the same parameters to all URLs in all Templates, use the environment config:

config.js

module.exports = {
  urlParameters: {
    _options: {
      tags: ['a'],
      qs: {}
    },
    utm_source: 'maizzle',
    utm_campaign: 'Campaign Name',
    utm_medium: 'email',
    custom_parameter: 'foo',
    '1stOfApril': 'bar'
  }
}

Front Matter

Of course, you may define URL parameters at a Template level, through Front Matter:

src/templates/example.html

---
title: "These URL params are unique to this template"
urlParameters:
  utm_source: custom
  utm_campaign: "Pre-launch August"
---

<extends src="src/layouts/main.html">
  <block name="template">
    <!-- ... -->
  </block>
</extends>

Options

Configure the tags to process and other transformer options.

tags

Type: array
Default: ['a']

Array of tag names to process. Only URLs inside href="" attributes of tags in this array will be processed.

You may use CSS selectors to select only certain attributes. For example, this will apply parameters only to anchors that include example.com in their href value:

config.js

module.exports = {
  urlParameters: {
    _options: {
      tags: ['a[href*="example.com"]'],
    },
    utm_source: 'maizzle',
  }
}

strict

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

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

config.js

module.exports = {
  urlParameters: {
    _options: {
      strict: false,
    },
    foo: 'bar'
  }
}

Input:

<a href="example.com">test</a>

Result:

<a href="example.com?foo=bar">test</a>

qs

Options to pass to the query-string library.

For example, Maizzle disables encoding by default, but you can enable it:

config.js

module.exports = {
  urlParameters: {
    _options: {
      qs: {
        encode: true
      }
    },
    foo: '@Bar@'
  }
}

Result:

https://example.com/?foo=%40Bar%40

API

app.js

const {addURLParams} = require('@maizzle/framework')

const html = await addURLParams('<a href="https://example.com">test</a>', {utm_source: 'maizzle'})