Docusaurus

Docusaurus has a scripts option in docusaurus.config.js that adds a <script> tag to the <head> of every page, so no theme swizzling is needed.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is your site's ID, a 12-character string such as a1b2c3d4e5f6. Older sites may use a numeric ID, which still works. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Docusaurus

Open docusaurus.config.js (or docusaurus.config.ts) at the root of your project and add the script to the scripts array:

docusaurus.config.js

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ... title, url, baseUrl, presets, themeConfig

  scripts: [
    {
      src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
      defer: true,
    },
  ],
};

module.exports = config;

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

docusaurus.config.js

headTags: [
  {
    tagName: "script",
    attributes: {
      src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
      defer: "true",
    },
  },
],

Rebuild with npm run build and deploy. The tag is not hot-reloaded into a running npm run start session until you restart it.

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

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Track custom events

Docusaurus pages are React, so you can fire events from a component and use it in MDX:

src/components/TrackedButton.jsx

import React from "react";

export default function TrackedButton({ children, eventName, eventData }) {
  const handleClick = () => {
    window.rybbit?.event(eventName, eventData);
  };

  return (
    <button onClick={handleClick} className="button button--primary">
      {children}
    </button>
  );
}

import TrackedButton from "@site/src/components/TrackedButton";

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

You don't need a listener for links to other sites. Rybbit records clicks on external links as outbound events by default, controlled by Outbound Links under Site Settings → Tracking.

If you add other site-wide code through a client module, keep in mind that onRouteDidUpdate runs after every navigation while the navbar and footer stay mounted, so listeners attached to them there pile up. Client modules also run during server-side rendering, so guard any window access.

Next steps

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

Get your tracking snippet

Add the snippet to Docusaurus

Verify installation

Track custom events

Next steps

On this page