Docusaurus

Docusaurus has a scripts option in its config that adds a <script> tag to every page, so you do not need to swizzle the theme.

Copy your tracking snippet

In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:

<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>

YOUR_SITE_ID is the numeric ID of your site.

Add the snippet to Docusaurus

Open docusaurus.config.js (or .ts) and add the script to scripts:

docusaurus.config.js

const config = {
  // ... title, url, baseUrl, presets, themeConfig

  scripts: [
    {
      src: "https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID",
      async: true,
    },
  ],
};

module.exports = config;

If you already manage tags through headTags, this is equivalent:

docusaurus.config.js

headTags: [
  {
    tagName: "script",
    attributes: {
      src: "https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID",
      async: "true",
    },
  },
],

Rebuild with npm run build and deploy. A running npm run start session does not pick up the change until you restart it.

Docusaurus is a single-page app on React Router. OnyxMetric detects client-side route changes and records them as pageviews, so navigation needs no extra code.

Check that it works

Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.

If nothing arrives:

View the page source and search for script.js?siteId= to confirm the tag is present.
In the browser's Network tab, check that script.js returns 200 and that requests go to /api/track.
Turn off ad blockers, or proxy the script through your own domain.
Read script troubleshooting for other causes.

Track custom events

Docusaurus pages are React, so wrap window.onyx.event() in a component and use it from MDX:

src/components/TrackedButton.jsx

export default function TrackedButton({ children, eventName, eventData }) {
  return (
    <button
      className="button button--primary"
      onClick={() => window.onyx?.event(eventName, eventData)}
    >
      {children}
    </button>
  );
}

<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>
  Learn more
</TrackedButton>

For site-wide listeners use a client module. Its onRouteDidUpdate runs after every navigation once the DOM is ready:

src/client-modules/onyx-events.js

export function onRouteDidUpdate() {
  document.querySelectorAll('a[target="_blank"]').forEach((link) => {
    link.addEventListener("click", () => {
      window.onyx?.event("external_link_click", { href: link.href });
    });
  });
}

Register it with clientModules: [require.resolve("./src/client-modules/onyx-events.js")] in the config. Client modules also run during server-side rendering, so keep window access inside handlers like this one.

Next steps

Track custom events such as signups, purchases, and clicks.
Identify users to tie sessions to accounts.
Proxy the script through your own domain to get past ad blockers.
Script attributes let you skip or mask URLs and tag events.

Copy your tracking snippet

Add the snippet to Docusaurus

Check that it works

Track custom events

Next steps

On this page