remark-add-query-param

A remark plugin to add query parameters to links

Bug report · Feature request

---

Why? 🤔

I use Markdown to write content on my website. I wanted to add query parameters to all the links in blog posts so that I can get insights into the traffic sources as well as help other people who are reading my blog posts to know where the link is coming from. I couldn't find any existing plugin that does this, so I created one.

So if you have a markdown file like this:

This is a [link](https://example.com)

And you use this plugin with the query parameter utm_source=remark-add-query-param, the output will be:

This is a [link](https://example.com?utm_source=remark-add-query-param)

Usage 💻

First you need to install the package using npm or yarn or pnpm.

npm install remark-add-query-param

Then you can use it in your remark pipeline like this:

import { remark } from 'remark';
import addQueryParam from 'remark-add-query-param';

const processor = remark().use(addQueryParam, {
  queryParam: 'utm_source=remark-add-query-param',
  externalLinks: true,
  internalLinks: true,
});

processor.process('This is a [link](https://example.com)').then((file) => {
  console.log(String(file)); // This is a [link](https://example.com?utm_source=remark-add-query-param)
});

The plugin also support using multiple query parameters like this:

import { remark } from 'remark';
import addQueryParam from 'remark-add-query-param';

const processor = remark().use(addQueryParam, {
  queryParam: ['utm_source=remark-add-query-param', 'utm_medium=markdown'],
  externalLinks: true,
  internalLinks: true,
});

processor.process('This is a [link](https://example.com)').then((file) => {
  console.log(String(file)); // This is a [link](https://example.com?utm_source=remark-add-query-param&utm_medium=markdown)
});

To ensure the typescript is happy, you can import the types from the package like this:

import type { QueryParam, RemarkAddQueryParamOptions } from 'remark-add-query-param';

const options: RemarkAddQueryParamOptions = {
  queryParam: 'utm_source=remark-add-query-param' as QueryParam,
  externalLinks: true,
  internalLinks: true,
};

// Or for multiple query parameters
const options: RemarkAddQueryParamOptions = {
  queryParam: ['utm_source=remark-add-query-param', 'utm_medium=markdown'] as QueryParam[],
  externalLinks: true,
  internalLinks: true,
};

Integration with Astro

If you are using Astro, you can use this plugin in your astro.config.mjs file like this:

import { defineConfig } from 'astro/config';
import addQueryParam from 'remark-add-query-param';

export default defineConfig({
  markdown: {
    remark: {
      plugins: [
        [
          addQueryParam,
          {
            queryParam: 'utm_source=remark-add-query-param',
            externalLinks: true,
            internalLinks: true,
          },
        ],
      ],
    },
  }
});

Integration with Next.js

If you are using Next.js, you can use this plugin in your next.config.js file like this:

import addQueryParam from 'remark-add-query-param';

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
};

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [
      [
        addQueryParam,
        {
          queryParam: 'utm_source=remark-add-query-param',
          externalLinks: true,
          internalLinks: true,
        },
      ],
    ],
  },
});

export default withMDX(nextConfig);

Configurations ⚙️

You can pass the following options to the plugin:

Option	Type	Description
queryParam	QueryParam or QueryParam[]	The query parameter to add to the links. This is required and should be a valid query parameter string i.e key=value.
externalLinks	boolean	If set to false, the plugin will not add the query parameter to external links. Default is true i.e it will add the query parameter to all external links.
internalLinks	boolean	If set to false, the plugin will not add the query parameter to internal links. Default is true i.e it will add the query parameter to all internal links.

Contributing 🫱🏻‍🫲🏼

Follow the contribution guidelines to contribute to this project.

Bugs or Requests 🐛

If you encounter any problems feel free to open an issue. If you feel the project is missing a feature, please raise a ticket on GitHub and I'll look into it. Pull requests are also welcome.

Where to find me? 👀