DataSag guides · Updated 27 October 2026

Load analytics without blocking rendering on VitePress

Use the platform's non-blocking external script mechanism and install the tracker once. Measure the published page before and after the change; script size alone cannot predict the effect on your website. This guide applies to VitePress.

Start with the VitePress installation

Merge a script tuple into the global VitePress head array. Include the external src, an empty-string defer attribute and the public data-datasag-key. Preserve other head entries, build the documentation and inspect its published HTML. Global config covers ordinary pages generated from that site.

VitePress also supports page-level head entries in frontmatter and custom theme code. A global script plus page or theme insertion can execute twice. Browser APIs belong in browser interaction code, not the Node-evaluated site configuration or an SSR render.

Use the public project key from the DataSag project you are inspecting. A test on a preview domain does not confirm that the production domain has the same code or settings.

Load analytics without blocking rendering in VitePress

  1. Preserve defer as an attribute in the global head script tuple and keep the public key on that element. Check custom theme loaders first so a timing experiment does not accidentally add another executing copy.
  2. Measure the generated documentation on a representative long page using fixed network and cache conditions. Compare tracker timing with hydration and documentation assets rather than using the development server as a public-page speed baseline.
  3. Test sidebar navigation and an early actionable component after the first load. If a later custom loader reduces startup work, record any initial interactions it cannot capture; heading-anchor clicks do not prove that another document loaded.

The global deferred script is measured in production output with early actions and client navigation included in the coverage check.

Complete the collection checks

  1. Record a baseline of the published page using the same browser, device emulation and network settings you will use for comparison. Include a representative content page, not only the homepage.
  2. Use defer for a normal external HTML script, or the framework-specific loading strategy shown in the installation example. Do not add a parser-blocking synchronous script as a shortcut.
  3. Keep one installation in the shared document or layout. Duplicate execution adds work even if the browser reuses the downloaded file.
  4. Inspect the Network waterfall for tracker.js and /api/track. Compare transfer size, timing and request count on a cold load and a cached load.
  5. Check that measurement still starts at the intended point. Loading only after idle or interaction can omit short visits and early clicks; performance and coverage must be evaluated together.
  6. Repeat the measurements and record variability. Report measured results for your page rather than claiming a universal speed improvement or zero performance cost.
// Browser Console, after loading the published page:
performance.getEntriesByType('resource')
  .filter(entry => entry.name.includes('/tracker.js'))
  .map(entry => ({ url: entry.name, durationMs: entry.duration }));
// Cross-origin transfer details may be unavailable.

What a successful check looks like

The script uses a non-blocking loading mechanism, appears once and records the intended visits. Any performance claim comes from repeatable measurements of the actual site.

Record the public path you tested, the browser state, the approximate time and the observed request. Check one direct page load and one later navigation so the result covers more than the homepage.

Common mistake

A faster lab result does not prove every visitor has a faster experience. Avoid mixing a warm-cache result with a cold-load baseline.

Installation snippet for VitePress

The shared installation belongs in the head array in .vitepress/config.ts or its configured equivalent. Use this as the installation reference while checking the procedure above.

// Merge into the existing .vitepress config.
export default {
  head: [["script", {
    src: "https://www.datasag.com/tracker.js",
    defer: "",
    "data-datasag-key": "YOUR_PUBLIC_KEY"
  }]]
};

Related VitePress guides

Full VitePress setup guide · Search and AI visibility

References

Official VitePress documentation covers the integration point. For DataSag data handling, read the privacy policy. Use support if a request fails after these checks.