Docusaurus

Name: Rybbit
Author: Rybbit

This guide explains how to integrate Rybbit with your Docusaurus v2+ website for analytics tracking. Docusaurus is a static site generator that builds a single-page application with React.

How to Add Rybbit to Your Docusaurus Site

Docusaurus provides a configuration option to add scripts or tags to the <head> of every page, which is the recommended way to include Rybbit.

1. Retrieve Your Tracking Script Details

Navigate to your Rybbit dashboard to obtain your Site ID. The script source will be https://app.rybbit.io/api/script.js.

2. Modify `docusaurus.config.js`

Open your docusaurus.config.js (or docusaurus.config.ts if using TypeScript) file, which is typically located at the root of your Docusaurus project.

You can add the Rybbit script using the scripts array or the headTags array within your site configuration. Using scripts is often cleaner for simple script additions.

Using the scripts configuration:

docusaurus.config.js


// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion
 
/** @type {import('@docusaurus/types').Config} */
const config = {
  // ... other configurations (title, tagline, favicon, url, baseUrl, organizationName, projectName, etc.)
 
  presets: [
    // ... your presets
  ],
 
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // ... your themeConfig
    }),
 
  // Add Rybbit script here
  scripts: [
    {
      src: 'https://app.rybbit.io/api/script.js',
      async: true,
      defer: true,
      'data-site-id': 'YOUR_SITE_ID', // Replace with your actual Site ID
    },
    // You can add other scripts here if needed
  ],
 
  // Alternatively, using headTags (more verbose for simple scripts):
  // headTags: [
  //   {
  //     tagName: 'script',
  //     attributes: {
  //       async: true,
  //       defer: true,
  //       src: 'https://app.rybbit.io/api/script.js',
  //       'data-site-id': 'YOUR_SITE_ID', // Replace
  //     },
  //   },
  // ],
};
 
module.exports = config;

Make sure to replace YOUR_SITE_ID with your actual Site ID from your Rybbit dashboard.

3. Verify Installation

After rebuilding and deploying your Docusaurus site (e.g., npm run build and npm run serve, or your deployment process), open your Rybbit dashboard to check if data is being received. You can also inspect your browser’s network tab to confirm that script.js is loaded on your pages.

Page View Tracking: Docusaurus builds a Single Page Application (SPA). Rybbit’s tracking script is designed to automatically detect route changes in SPAs and track them as page views. If you find that page views are not being tracked correctly after client-side navigation (which is uncommon), you might need to manually trigger page views. Docusaurus uses React Router internally. You could potentially use a client module or swizzle a component to tap into navigation events if manual tracking is absolutely necessary, but test the default behavior first. If manual tracking is required, you would call window.rybbit.trackPageview() after a route change.

Custom Event Tracking

Since Docusaurus uses React, you can track custom events from any of your custom React components or by using client modules.

Example in a custom React component used in Docusaurus:


// src/components/MyCustomButton.jsx
import React from 'react';
 
export default function MyCustomButton({ children, eventName, eventData }) {
  const handleClick = () => {
    if (typeof window !== 'undefined' && window.rybbit) {
      window.rybbit.trackEvent(eventName || 'docusaurus_custom_click', eventData || {});
    }
  };
 
  return (
    <button onClick={handleClick} className="button button--primary margin--sm">
      {children}
    </button>
  );
}

You can then use this component in your MDX files:


import MyCustomButton from '@site/src/components/MyCustomButton';
 
<MyCustomButton eventName="learn_more_clicked" eventData={{ page: 'introduction' }}>
  Learn More
</MyCustomButton>

Using Client Modules: Docusaurus allows you to run JavaScript on page load using Client Modules . You could use this to set up global event listeners or track specific initial interactions.

src/client-modules/rybbit-events.js


// Example: Track when a user clicks on any external link
export function onRouteUpdate({location, previousLocation}) {
  // This function runs after Docusaurus finishes navigating to a new route.
  // You could also use onRouteDidUpdate if you need the DOM to be fully updated.
 
  if (typeof window !== 'undefined' && window.rybbit && location.pathname !== previousLocation?.pathname) {
    // Rybbit should auto-track pageviews, but if needed:
    // window.rybbit.trackPageview();
  }
 
  // Example: Add event listeners for specific elements
  document.querySelectorAll('a[target="_blank"]').forEach(link => {
    link.addEventListener('click', () => {
      if (window.rybbit) {
        window.rybbit.trackEvent('external_link_click', { href: link.href });
      }
    });
  });
}

Always ensure window.rybbit is available before calling its methods in client-side scripts.