Docusaurus
Integrate analytics-tube Analytics with your Docusaurus v2+ website
This guide explains how to integrate analytics-tube 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 analytics-tube 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 analytics-tube.
Retrieve Your Tracking Script Details
Navigate to your analytics-tube dashboard to obtain your Site ID. The script source will be https://app.analytics.tube/api/script.js.
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 analytics-tube 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:
// @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 analytics-tube script here
scripts: [
{
src: 'https://app.analytics.tube/api/script.js',
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: {
// defer: true,
// src: 'https://app.analytics.tube/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 analytics-tube dashboard.
Verify Installation
After rebuilding and deploying your Docusaurus site (e.g., npm run build and npm run serve, or your deployment process), open your analytics-tube 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). analytics-tube'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.analytics-tube.pageview() 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.analytics-tube) {
window.analytics-tube.event(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.
// 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.analytics-tube && location.pathname !== previousLocation?.pathname) {
// analytics-tube should auto-track pageviews, but if needed:
// window.analytics-tube.pageview();
}
// Example: Add event listeners for specific elements
document.querySelectorAll('a[target="_blank"]').forEach(link => {
link.addEventListener('click', () => {
if (window.analytics-tube) {
window.analytics-tube.event('external_link_click', { href: link.href });
}
});
});
}Always ensure window.analytics-tube is available before calling its methods in client-side scripts.