https://github.com/posthtml/posthtml-url-parameters
Add parameters to URLs with PostHTML.
https://github.com/posthtml/posthtml-url-parameters
posthtml posthtml-plugin query-string url-parameters
Last synced: 3 months ago
JSON representation
Add parameters to URLs with PostHTML.
- Host: GitHub
- URL: https://github.com/posthtml/posthtml-url-parameters
- Owner: posthtml
- License: mit
- Created: 2020-03-27T16:28:29.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-04-11T15:59:22.000Z (3 months ago)
- Last Synced: 2025-04-11T20:52:32.275Z (3 months ago)
- Topics: posthtml, posthtml-plugin, query-string, url-parameters
- Language: JavaScript
- Size: 2.1 MB
- Stars: 3
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
URL Parameters
Add parameters to URLs
[![Version][npm-version-shield]][npm]
[![Build][github-ci-shield]][github-ci]
[![License][license-shield]][license]
[![Downloads][npm-stats-shield]][npm-stats]
## About
This is a PostHTML plugin that allows you to add query string parameters to URLs.
## Install
```
npm i posthtml posthtml-url-parameters
```
## Usage
```js
import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'
posthtml([
urlParams({
parameters: { foo: 'bar', baz: 'qux' }
})
])
.process('Test')
.then(result => console.log(result.html)))
// Test
```
## Configuration
### `parameters`
Type: `Object`\
Default: `undefined`
Object containing parameter name (key) and its value.
Example:
```js
import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'
posthtml([
urlParams({
parameters: {
utm_source: 'Campaign',
'1stDraft': true
}
})
])
.process('Test')
.then(result => console.log(result.html))
```
### `tags`
Type: `Array`\
Default: `['a']`
Array of tag names to process.
By default, only URLs inside [known attributes](#attributes) of tags in this array will be processed.
Example:
```js
import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'
posthtml([
urlParams({
tags: ['a', 'img']
})
])
.process(`
Test
`)
.then(result => console.log(result.html))
```
You may use some CSS selectors when specifying tags:
```js
posthtml([
urlParams({
tags: ['a.button', 'a[href*="example.com"]' 'link'],
})
])
.process(/*...*/)
```
All [`posthtml-match-helper` selectors](https://github.com/posthtml/posthtml-match-helper) 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.
```js
posthtml([
urlParams({
parameters: {foo: 'bar'},
attributes: ['data-href']
})
])
.process('Test')
.then(result => console.log(result.html)))
// Test
```
### `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:
```js
import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'
posthtml([
urlParams({
parameters: { foo: 'bar' },
strict: false,
})
])
.process('Details')
.then(result => console.log(result.html)))
// Details
```
### `qs`
Type: `Object`\
Default: `undefined`
Options to pass to `query-string` - see available options [here](https://github.com/sindresorhus/query-string#stringifyobject-options).
For example, you may disable encoding:
```js
import posthtml from 'posthtml'
import urlParams from 'posthtml-url-parameters'
posthtml([
urlParams({
parameters: { foo: '@Bar@' },
qs: {
encode: false
}
})
])
.process('Test')
.then(result => console.log(result.html)))
// Test
```
[npm]: https://www.npmjs.com/package/posthtml-url-parameters
[npm-version-shield]: https://img.shields.io/npm/v/posthtml-url-parameters.svg
[npm-stats]: http://npm-stat.com/charts.html?package=posthtml-url-parameters
[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-url-parameters.svg
[github-ci]: https://github.com/posthtml/posthtml-url-parameters/actions
[github-ci-shield]: https://github.com/posthtml/posthtml-url-parameters/actions/workflows/nodejs.yml/badge.svg
[license]: ./LICENSE
[license-shield]: https://img.shields.io/npm/l/posthtml-url-parameters.svg