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? 👀