Hexo

Hexo 5 and later ship an injector API that adds HTML to the <head> of every generated page from a small file in your site's scripts/ directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.

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 the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Hexo

Add your site ID to the site _config.yml at the root of your project (not the theme config). instance_url is only needed if you self-host:
_config.yml
```
rybbit:
  site_id: "YOUR_SITE_ID"
  instance_url: "https://app.rybbit.io"
```

Create scripts/rybbit.js (create the scripts/ directory if it does not exist). Hexo loads every file in this directory at startup with the hexo object in scope:

scripts/rybbit.js

const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =
  hexo.config.rybbit || {};

if (siteId) {
  hexo.extend.injector.register(
    "head_end",
    `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`
  );
}

head_end places the tag right before </head>. With no third argument the injector applies to every page type.

Open your theme's head partial and paste the snippet before </head>. For the default Landscape theme that file is themes/landscape/layout/_partial/head.ejs; other themes keep an equivalent partial under layout/.

themes/landscape/layout/_partial/head.ejs

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

Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.

Regenerate and deploy the public/ directory:

hexo clean && hexo generate

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.

Troubleshooting

hexo.extend.injector is undefined: the injector API arrived in Hexo 5.0. Check hexo version and upgrade, or use the theme layout method.
Tag missing after adding the script: run hexo clean before hexo generate; Hexo caches rendered output in db.json and can serve stale pages.
Local previews are tracked: hexo server runs the same injector as hexo generate. Leave site_id empty in a local copy of _config.yml, or accept the local pageviews.
Theme config vs site config: hexo.config reads the root _config.yml, not themes/<name>/_config.yml. Put the rybbit block in the root file.

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 Hexo

Verify installation

Troubleshooting

Next steps

On this page