Analytics for Open Source Project Docs

What a docs site is actually for

A README gets a reader to the door. The docs site decides whether they walk through it. For many open source projects it is the busiest surface after the repository itself, and the only one you fully control: the layout, the search box, the install instructions, the migration guides. That makes it the one place where analytics can change what you ship.

The questions a maintainer asks are narrower than the ones a marketing team asks. Nobody on a docs team needs a funnel across sessions or an audience segment. They need to know whether the quickstart is read, whether the guide they rewrote last month is still being reached, and whether a page they assume is popular actually is. Those are counting questions over pages and referrers, and a cookieless tool answers them completely.

There is also a values fit. Developers are the readers most likely to run an ad blocker, to read your privacy policy and to notice a consent banner on a docs site. A project that ships a cookie prompt on its installation guide sends a signal, and it is rarely the one the maintainers intended. If you want the legal background, our cookie banner guide covers when consent is generally required and when it is not.

The five signals worth tracking

Every item below maps to a panel that exists in GhostMetrics today. Where a signal needs a workaround, the section says so.

1. Top docs pages

The Top Pages panel ranks paths by pageviews. For docs this is your reading list in order of demand. Two patterns show up quickly. First, a small number of pages carry most of the traffic, typically installation, quickstart and the top-level API reference. Those are the pages where a typo or an outdated flag costs the most readers, so they deserve the review time. Second, pages you consider central may sit far down the list, which usually means they are hard to find rather than unimportant.

2. Entry pages, your search-entry signal

Entry Pages shows which page a visit started on. On a docs site, a visit that starts deep in the tree, on a specific API method or an error explanation, almost always came from a search engine or a link, not from your homepage. Combine that with the Referrers panel, which classifies each visit as search, social, direct or referral, and you can see which pages act as your real front doors. Those pages should each state what the project is, link to the quickstart and carry a working install snippet, because for many readers they are the first page they will ever see.

One limit to know: GhostMetrics records the source type and the referring site, not the search query text. You learn that a page earns search traffic, not the exact words people typed. Your own docs search box is a separate matter and is covered under custom events below.

3. Referrers: GitHub, Hacker News, Reddit

The Referrers panel lists referring sites by name with visit counts. For an open source project it is a launch-day instrument. When a release post reaches Hacker News or a subreddit, you see the referrer name climb within the day, along with the entry page those visitors landed on. Watch the entry page for that traffic: if a visitor from a link aggregator lands on a deep API page rather than your overview, the post linked to the wrong URL.

Be precise about what this tells you. A visit with no referrer header is counted as direct. GhostMetrics cannot separate a typed URL from a stripped referrer, and privacy-stripped browsers, some chat and email apps, and https-to-http hops all arrive with none. Direct traffic on a docs site also includes every developer who opened the docs from a terminal, an IDE link or a bookmark. If the source matters, put UTM parameters on links you control: release notes, the README badge, the newsletter. See the UTM parameters guide for a naming scheme. GhostMetrics stores utm_source, utm_medium and utm_campaign, first-touch within the tab session, and nothing across sessions.

4. Exit pages, the closest thing to a broken-page report

The Exit Pages panel shows where sessions end. A high exit count on a page is not automatically bad: a reader who copies the install command and leaves has succeeded. It becomes useful when the exit page is a step in the middle of a tutorial, or an error page. If you keep a custom 404 page and it carries the tag, test it yourself by visiting a made-up URL and checking whether that path appears in your page list. Treat the result as your own check rather than an assumption, because how a docs host serves its 404 varies. GhostMetrics has no dedicated broken-link report, so a link checker in CI remains the right tool for finding dead links.

5. Real-user vitals

Docs pages are heavier than they look: syntax highlighting, search indexes, embedded playgrounds, big API tables. GhostMetrics captures First Contentful Paint, Largest Contentful Paint, Cumulative Layout Shift and Time to First Byte from real visitors through PerformanceObserver and Navigation Timing, and shows them per page. Interaction to Next Paint is not captured. TTFB follows Google's definition (responseStart from navigation start, so redirects, DNS, connection setup and server time all count) and is rated against the 800 ms good threshold. A per-page table is what a docs team needs: it shows whether the API reference that everyone reads is also the slowest page. Our Core Web Vitals guide goes deeper on reading those numbers.

Custom events for docs: the install button and the search box

Pageviews tell you a reader arrived. An event tells you they did the thing the page exists for. On a docs site the highest-value action is almost always copying the install command, followed by clicking through from a quickstart to the first tutorial.

GhostMetrics records clicks declaratively. Add a data-gm-event attribute to any element and each click is stored with the page path and any session UTM. A single delegated listener handles it, so buttons rendered after page load, such as a tabbed install widget that swaps content client-side, are covered without re-binding anything.

<button class="copy" data-gm-event="copy-install-command">
  npm install my-project
</button>

For actions that are not a plain click, call the tracker from your own code. Only a section field is stored as metadata:

window.ghostmetrics.track('docs-search-used', { section: 'api-reference' });

The Custom Events panel lists each event name with its count and last-fired time. Two honest limits: there is no numeric value field, and the panel has no per-page drill-down. To see which pages produce the most install-button clicks, export the raw rows (CSV from the dashboard, JSON from the API, on every plan) and group by page path. The wider pattern is in our guide to custom events without Google Analytics.

A note on what the click event does not see. It counts clicks on the element you tagged. A reader who selects the command by hand and copies it, or uses a keyboard shortcut in a code block's own copy widget that you did not tag, will not register. Treat the count as a floor, and compare it week over week rather than reading it as an absolute number of installs. The real install count lives in your package registry.

No cookie banner on docs

GhostMetrics sets no cookies, uses no localStorage, stores no IP addresses (they are hashed) and keeps no cross-session identifier. The only browser storage it touches is a per-tab sessionStorage entry for a scroll counter and the first UTM set seen, which clears when the tab closes. It honors Global Privacy Control and Do Not Track by collecting nothing. Because nothing personal is stored and no visitor can be recognised on a later day, there is no cookie consent choice for the analytics to present, and the docs load without an overlay covering the first paragraph of your quickstart.

Contrast that with a cookie-based tool. GA4 sets _ga cookies by default, so consent is generally required for readers in the EU and UK, and gtag.js measures about 150 KB compressed against about 3 KB for the GhostMetrics script (our own measurement). On a docs site where readers arrive from a search result and want a command, that difference is visible in load time. The consent-free analytics guide covers the compliance side in more detail.

Readers who block scripts will not be counted by any script-based tool. That is a property of the method, and it is worth remembering when you compare your numbers with a registry download count or a repository traffic graph. They measure different things, and they will not match.

Which tool fits an open source project

The honest split is about the project's values and how much you want to operate. Some maintainers will only run open source tooling. Others just want the answer without a server to patch. The table sticks to facts that are stable.

Plausible is the natural first look for a project that wants open source tooling, since its code is public and the Community Edition can be self-hosted. It does not have a free hosted plan; check the Community Edition docs for what it includes compared with the hosted product. Our Plausible alternatives page has the wider comparison.

Umami suits a team that already operates a small server and would rather keep the database in its own hands. You take on the upgrades, the backups and the uptime. The tradeoff is real for a volunteer-run project: an analytics server is one more thing that needs an owner, and an unmaintained one is worse than none. See Umami alternatives.

Cloudflare Web Analytics is free, cookieless and reports visits, pageviews, top pages, referrers, countries, browsers, devices and Core Web Vitals. It has no custom events and no UTM breakdown, so the install button stays uncounted. Its data is reachable through Cloudflare's GraphQL Analytics API rather than a CSV button. Details in the Cloudflare Web Analytics comparison.

GhostMetrics is the hosted option with the most on the free plan: one website, unlimited pageviews, a real-time dashboard, every view, full history, and raw CSV or JSON export on every plan. It is closed source and cannot be self-hosted. If your project's rules say open source only, that settles it, and one of the two tools above is your answer.

How to add GhostMetrics to a docs site

The install is one tag in the page head. Docs generators differ only in where they let you put it. Every step below is a config or template edit, not a plugin. The static site guide covers the general case.

1. Create a free account. Sign up at ghostmetrics.nullagency.io/signup. No card is required, and you get a site ID.
2. Find your generator's head hook. Every static docs generator has a way to inject a script into the head. Check its docs for the exact key, since option names change between releases.
3. Add the tag. In Docusaurus, list it under scripts in docusaurus.config.js:

   scripts: [
     {
       src: 'https://ghostmetrics.nullagency.io/gm.js',
       defer: true,
       'data-site': 'YOUR-SITE-ID',
     },
   ],

   In Sphinx, use html_js_files in conf.py:

   html_js_files = [
       ("https://ghostmetrics.nullagency.io/gm.js",
        {"defer": "defer", "data-site": "YOUR-SITE-ID"}),
   ]

   In MkDocs with a custom theme directory, override the head block in overrides/main.html:

   {% extends "base.html" %}
   {% block extrahead %}
   <script defer src="https://ghostmetrics.nullagency.io/gm.js" data-site="YOUR-SITE-ID"></script>
   {% endblock %}

   Anywhere else, paste the plain tag into the head: <script defer src="https://ghostmetrics.nullagency.io/gm.js" data-site="YOUR-SITE-ID"></script>. If your generator processes script tags, mark this one so the data-site attribute is left untouched (in Astro that means is:inline).
4. Confirm it loads. Deploy, open a docs page and check the dashboard. Pageviews appear in the real-time view. Client-side navigation in single-page docs frameworks is counted automatically, because pushState and popstate register as new pageviews.
5. Tag the install button. Add data-gm-event="copy-install-command" to the copy button in your quickstart, redeploy, click it once and confirm the event appears in the Custom Events panel.
6. Test a bad URL. Visit a path that does not exist and check whether it shows up in the page list. Now you know how your host's 404 behaves with the tag on it.
7. Set a review habit. Look at Top Pages, Entry Pages and Referrers after each release. Once a quarter, export the raw data and archive it with the project's other records.

The tag is about 3 KB compressed on the wire (10 KB uncompressed), served from Cloudflare's edge, and it works on any host: GitHub Pages, Netlify, Vercel, Cloudflare Pages or your own server.

Several docs sites, and a page for sponsors

Larger projects rarely have one docs site. There is a main manual, a separate API reference, a blog, perhaps versioned docs on their own domains. The free plan covers exactly one website. Pro is $9.99/mo flat with unlimited pageviews and a 30-day free trial (a card is required to start the trial, nothing is charged for 30 days, cancel anytime). It adds unlimited websites (fair-use ceiling of 250) under one login, each with its own site ID and one-line snippet, plus a public shareable dashboard URL. That is the whole list of what Pro adds. There is no cross-site roll-up view, so each site is read on its own, and the export is available per site.

The public dashboard is the part that suits open source. Sponsors and foundations often ask what the project's reach is, and a screenshot from an unknown month proves little. Publishing a site gives a read-only copy of the same dashboard, every panel and every period, at a public URL with a small "Powered by GhostMetrics" banner. Viewers need no login, and you can unpublish at any time, after which the URL returns a 404. Our own live demo uses that public view on nullagency.io's real traffic. The steps and the risks are in how to share website analytics publicly.

Read the exposure section of that guide before publishing a docs site. Two items matter here. Referrer paths that carry tokens can appear in a public referrers table, and custom event names are visible, so name events like copy-install-command with an audience in mind. On a small project with a few visits a day, the organization panel can point at individual visits, so a low-traffic site may be better off keeping the dashboard private and sharing a periodic CSV summary instead.

FAQ

Keep reading

Disclosure: GhostMetrics is built by Null Agency and we use it on this site, so we are not a neutral party about our own product. We kept the claims to what the free and Pro plans actually do, and pointed to Plausible and Umami where an open source or self-hosted requirement makes them the better fit. Pricing and plan details for third-party products can change, so check the vendor's current pricing and docs before deciding.