jekyll-privatus-analytics 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b60c001e65be88754b3059dbd76bcff86a12294dc2342e312e510bcf2f9c4c3
+  data.tar.gz: b64e4965df21ebf2db19513b66c7a9bcf551ae11731eac16b05652d36dbc713a
+SHA512:
+  metadata.gz: e2e06265a7859a5f30e655c7ca92def88a0fc45d94a8536270696eedce07f4085d8ebe1baf62e948ccfbfe09d803bd07e88636d1c23ac23b8f45c16c3fb63376
+  data.tar.gz: c6ec30b675124db9f75bd994d26c425d560a292db796ec839655d38ed5c0c528bf7e2f56f5d8f93df7f6dcfd95be23d28a48c2f7433d0710344d0e2bf1499f2a

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0 - 2026-10-25
+
+- Initial release.
+- `{% privatus_analytics %}` Liquid tag, with per-call settings.
+- `{% privatus_event %}` for custom events and `{% privatus_click %}` for click map names.
+- Optional `auto_inject` that adds the tag to the head of every page and document.
+- Settings under `privatus_analytics` in _config.yml. The tag is on only when `JEKYLL_ENV` is
+  `production`, unless `enabled` is set.
+- Page props from `props` in _config.yml, merged with `privatus_props` from front matter.
+- With `queue_stub: true`, `{% privatus_analytics %}` now prints the queue stub and nothing else when the
+  tag is off (development, `enabled: false` or no site id), so `privatus.track` calls never fail. Before, it
+  printed nothing.
+- With `queue_stub: true`, automatic injection (`auto_inject: true`) now also adds the queue stub alone to
+  every page when the tag is off (no tracker, no page props script). A page that already prints the stub with
+  `{% privatus_analytics %}` does not get a second one. With the queue stub off nothing is added, as before.
+- `example/`: a tiny site for the Privatus conformance tests, built with the plugin and served by nginx.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Two Phase LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,397 @@
+# Privatus Analytics for Jekyll
+
+A [Jekyll](https://jekyllrb.com) plugin that adds the cookieless
+[Privatus Analytics](https://privatusanalytics.com) tracking script to your
+site with a Liquid tag, or adds it to every page for you. It also has Liquid
+tags for custom events and click maps.
+
+Privatus Analytics counts visits, sources, pages and conversions without
+cookies, local storage or fingerprinting, so analytics does not need a consent
+banner by itself. Check with your own counsel for your country.
+
+The plugin only prints the browser script and HTML attributes. It never sends
+events from your computer or build server and sets no cookies. You need a
+Privatus Analytics account to see reports, and there is a free plan. Sign up at
+https://privatusanalytics.com.
+
+## Requirements
+
+* Ruby 3.1 or later.
+* Jekyll 3.10 to 4.x.
+* A Privatus Analytics site id (it starts with `pa_`). You find it under
+  Site settings, Tracking.
+
+### A note on GitHub Pages
+
+The classic GitHub Pages build (the one that runs when you pick a branch under
+Settings, Pages, with no workflow of your own) only runs a short, fixed list of
+plugins. This plugin is not on that list, so **it does not run in classic
+GitHub Pages builds**. Your site still builds, but without the tag.
+
+You can still host on GitHub Pages. Build the site with GitHub Actions instead:
+in your repository go to Settings, Pages, and set Source to "GitHub Actions",
+then use the Jekyll starter workflow GitHub offers there. With Actions, any
+plugin in your `Gemfile` runs. The starter workflow already sets
+`JEKYLL_ENV=production`, which this plugin needs (see below).
+
+If you must stay on the classic build, paste the plain script tag from your
+Privatus site settings into your layout's `<head>` instead.
+
+## Install
+
+Add the gem to the plugins group of your `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-privatus-analytics"
+end
+```
+
+Then run `bundle install`. Gems in the `jekyll_plugins` group load by
+themselves. If you do not use that group, list the plugin in `_config.yml`
+instead:
+
+```yaml
+plugins:
+  - jekyll-privatus-analytics
+```
+
+For the full setup guide and every tracker option, see the [Privatus Analytics
+docs](https://privatusanalytics.com/docs).
+
+Set your site id in `_config.yml`:
+
+```yaml
+privatus_analytics:
+  site_id: pa_YOURSITEID
+```
+
+or with an environment variable on your build machine:
+
+```sh
+PRIVATUS_SITE_ID=pa_YOURSITEID
+```
+
+## Add the tag
+
+Put the tag in the `<head>` of your layout, for example `_layouts/default.html`
+(or `_includes/head.html` in many themes):
+
+```liquid
+<head>
+  <title>{{ page.title }}</title>
+  {% privatus_analytics %}
+</head>
+```
+
+When you build with `JEKYLL_ENV=production` it prints:
+
+```html
+<script defer src="https://privatusstats.com/js/pa.js" data-site="pa_YOURSITEID"></script>
+```
+
+```sh
+JEKYLL_ENV=production bundle exec jekyll build
+```
+
+The tag prints nothing when there is no site id, and nothing outside the
+production environment. Plain `jekyll serve` and `jekyll build` run in the
+`development` environment, so your own visits while you write are never
+counted. (With `queue_stub: true` it still adds the small queue stub, see
+below.)
+
+### Or let the plugin add it
+
+If you would rather not touch your layouts (for example with a theme from a
+gem), switch on automatic injection:
+
+```yaml
+privatus_analytics:
+  site_id: pa_YOURSITEID
+  auto_inject: true
+```
+
+After each page and post is rendered, the plugin adds the tag just before
+`</head>`. It skips files that are not HTML, pages without a `<head>`, and
+pages that already have the tag in their head. Static files (files without
+front matter) are copied as they are, so they do not get the tag.
+
+## Configuration
+
+Every setting is optional except the site id.
+
+```yaml
+privatus_analytics:
+  site_id: pa_YOURSITEID          # or the PRIVATUS_SITE_ID environment variable
+  script_host: https://privatusstats.com # or PRIVATUS_SCRIPT_HOST
+  modules: [engage, auto, vitals, clicks, ask]
+  excluded_paths: [/drafts/*]
+  domains: [www.example.com]
+  spa: auto                       # auto, history, hash or off
+  manual: false                   # true turns off the automatic pageview
+  enabled_environments: [production]
+  enabled:                        # true or false forces the tag on or off
+  auto_inject: false
+  extra_attributes:
+    data-mask: /orders/*->/orders/:id
+  props:
+    site_section: docs
+  queue_stub: false
+  nonce:
+```
+
+| Setting | Default | What it does |
+|---|---|---|
+| `site_id` | `PRIVATUS_SITE_ID` | The `data-site` attribute. Nothing prints without it |
+| `script_host` | `https://privatusstats.com` | Where `/js/pa.js` is served. Change it only if you host your own copy |
+| `modules` | tracker default (`engage`) | The `data-modules` attribute. Setting it replaces the default, so keep `engage` for time on page and scroll depth. `[]` loads none |
+| `excluded_paths` | none | The `data-exclude` attribute. Path patterns the tracker never counts |
+| `domains` | all hosts | The `data-domains` attribute. Count only these hostnames |
+| `spa` | `auto` | The `data-spa` attribute |
+| `manual` | `false` | The `data-manual` attribute |
+| `enabled_environments` | `[production]` | Values of `JEKYLL_ENV` that get the tag |
+| `enabled` | not set | `true` or `false` forces the tag on or off in every environment |
+| `auto_inject` | `false` | Adds the tag to the head of every page for you |
+| `extra_attributes` | `{}` | Any other `data-*` attribute |
+| `props` | `{}` | Page props sent with every pageview and event. See below |
+| `queue_stub` | `false` | Prints a small script first, so `privatus.track` calls made before the tracker loads are kept and sent later |
+| `nonce` | none | A Content Security Policy nonce for the tags. Static sites rarely have one |
+
+Each tracker attribute is explained in the [script attributes
+reference](https://privatusanalytics.com/docs/tracker/attributes), and the
+modules in [Modules](https://privatusanalytics.com/docs/tracker/modules).
+
+You can also override a setting for one layout or page. Lists are written with
+commas:
+
+```liquid
+{% privatus_analytics modules="engage,auto" excluded_paths="/preview/*" queue_stub=true %}
+```
+
+### Development and test
+
+Builds that are not `JEKYLL_ENV=production` do not get the tag, so your own
+clicking around never reaches your reports. To see the tag while you build,
+set `enabled: true` (or use a separate config file, like
+`jekyll serve --config _config.yml,_config.dev.yml`). The tracker also ignores
+`localhost` unless you pass `data-allow-local` or `data-debug` (see [Debug
+mode](https://privatusanalytics.com/docs/tracker/debug)):
+
+```yaml
+privatus_analytics:
+  enabled: true
+  extra_attributes:
+    data-debug: "true"
+```
+
+### Leaving people out
+
+Use `excluded_paths` for pages you do not want counted, like drafts. The
+`domains` setting makes sure only your real site is counted, not previews or
+copies on other hosts.
+
+## Product analytics: see which features people use
+
+Privatus can show which buttons, links and forms people really use. You add a
+few attributes to your HTML. The tracker reads them in the browser and sends
+the events. Your build still sends nothing.
+
+### Name events well
+
+Use a short "Noun verb" name, like `Report exported` or `Newsletter joined`.
+Put the details in props, not in the name. So write `Report exported` with
+`format="csv"`, not `Report exported as CSV`. Then all exports add up in one
+place, and you can split them by format.
+
+### Events on buttons, links and forms
+
+`{% privatus_event %}` prints the attributes inside a tag you write yourself:
+
+```liquid
+<button {% privatus_event "Report exported" format="csv" source="toolbar" %}>Export</button>
+```
+
+It prints:
+
+```html
+<button data-privatus-event="Report exported" data-privatus-prop-format="csv" data-privatus-prop-source="toolbar">Export</button>
+```
+
+Values in quotes are text. `true`, `false` and numbers stay as they are.
+Anything else is read as a Liquid variable, so you can use page data:
+
+```liquid
+<a href="{{ page.pdf }}" {% privatus_event "Download started" format="pdf" guide=page.slug %}>Download</a>
+```
+
+On a form, the event is sent when the form is submitted:
+
+```liquid
+<form action="https://example.com/join" {% privatus_event "Newsletter joined" list="weekly" %}>
+```
+
+The rules:
+
+* The name is trimmed and cut to 120 characters. An empty name prints nothing.
+* Prop keys are made lowercase. Anything that is not a letter, a digit or `_`
+  becomes `_`, so `report-type` becomes `report_type`. Keys are cut to 64
+  characters.
+* At most 30 props. Values become text: `true`, `false`, numbers as written,
+  lists joined with commas. Empty (`nil`) values are left out. Values are cut
+  to 500 characters.
+* Everything is escaped for HTML.
+* The attributes print in every environment, even when the tag is off. They do
+  nothing without the tracker, so your pages look the same in development and
+  production.
+
+The tags work in HTML files and in Markdown pages, as long as they sit inside
+HTML you write in the page.
+
+### Click maps
+
+A click map shows where people click on a page. Give the important parts a
+name so they stay easy to find, even when the page changes:
+
+```liquid
+<a href="/pricing" {% privatus_click "pricing.cta" %}>See plans</a>
+```
+
+A name may use letters, digits and `_ . : -`, up to 100 characters. Anything
+else prints nothing, and in development the plugin writes a warning to the
+build log.
+
+### Page props: section, version and other groups
+
+Page props are sent with every pageview and event on the page. Use them to
+split your reports by section, product, docs version or language.
+
+Set them for the whole site in `_config.yml`:
+
+```yaml
+privatus_analytics:
+  props:
+    site_section: docs
+    docs_version: "2.4"
+```
+
+and change them for one page in its front matter. They are merged over the site
+props, and an empty value removes one:
+
+```yaml
+---
+title: Getting started
+privatus_props:
+  section: tutorials
+  docs_version:
+---
+```
+
+With Jekyll's front matter defaults you can set them for a whole folder:
+
+```yaml
+defaults:
+  - scope:
+      path: blog
+    values:
+      privatus_props:
+        section: blog
+```
+
+The tag then prints a small script before the tracker and points the tracker
+at it:
+
+```html
+<script>window.privatusPageProps=function(){return {"site_section":"docs","section":"tutorials"}}</script>
+<script defer src="https://privatusstats.com/js/pa.js" data-site="pa_YOURSITEID" data-props="privatusPageProps"></script>
+```
+
+Keys follow the same rules as event props. Numbers and true or false stay as
+they are, and lists stay lists (up to 30 items). The props are escaped so they
+are safe inside a script.
+
+**Never put names, emails, user ids or anything that points to one person in
+props.** Privatus counts visitors without any id. Put groups (like the section
+or the plan), not people. The server also removes emails and long ids it
+finds.
+
+### Track from your own JavaScript
+
+For things that are not a click or a submit, call the tracker from your
+JavaScript, as the [JavaScript API
+docs](https://privatusanalytics.com/docs/tracker/javascript-api) explain:
+
+```js
+privatus.track("Feature used", { feature: "search" })
+```
+
+If your code may run before the tracker has loaded, switch on the queue stub.
+It prints a tiny script before the tracker that keeps your calls in a list and
+sends them once the tracker is ready:
+
+```yaml
+privatus_analytics:
+  queue_stub: true
+```
+
+or for one layout: `{% privatus_analytics queue_stub=true %}`. The stub is
+added even when the tag is off (in development, with `enabled: false` or with
+no site id), so your `privatus.track` calls never fail in development: they
+wait in the list and are never sent. Then only the stub is added, with no
+tracker and no page props. This works with the `{% privatus_analytics %}` tag
+and with automatic injection (`auto_inject: true`). A page that uses both
+still gets the stub only once. With the queue stub off, nothing is added when
+the tag is off.
+
+### See the results
+
+* [Funnels](https://privatusanalytics.com/docs/features/funnels): how many
+  people go from one step to the next.
+* [Click maps](https://privatusanalytics.com/docs/features/click-maps): where
+  people click.
+* [Goals](https://privatusanalytics.com/docs/features/goals): turn an event
+  into a goal to count conversions.
+* [Events](https://privatusanalytics.com/docs/events): every custom event and
+  its props.
+
+## Privacy
+
+The script sets no cookies and stores nothing in the browser. The event, click
+and props tags only print HTML attributes and a small script. Keep people out
+of your props and event props: no names, emails or user ids. See the [privacy
+documentation](https://privatusanalytics.com/docs/privacy) for what is
+collected.
+
+If you have a privacy policy, it should say which tools handle your visitors' data. You can paste this:
+
+> This website uses [Privatus Analytics](https://privatusanalytics.com/privacy-analytics) to count visits. It
+> does not use cookies and does not follow you from one website to another. Your IP address is used for a moment
+> to count visits and is never stored.
+
+Change it to fit your site. The [privacy policy generator](https://privatusanalytics.com/tools/privacy-policy-generator)
+makes a longer version with your site's name in it.
+
+## Development
+
+The tests run in Docker so your local Ruby does not matter:
+
+```sh
+./run-docker.sh
+```
+
+It runs the Minitest suite (with real builds of tiny Jekyll sites), RuboCop,
+and `gem build`.
+
+The `example/` folder holds a tiny site for the [conformance
+tests](https://github.com/Privatus-Analytics/conformance), which open it in a
+real browser with the real tracker. Run them from a copy of that repo with
+`./run.sh ../jekyll`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+https://github.com/Privatus-Analytics/jekyll.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt). Privatus Analytics is a product of Two
+Phase LLC, Wyoming, USA.

data/lib/jekyll-privatus-analytics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "jekyll_privatus_analytics/version"
+require "jekyll_privatus_analytics/attributes"
+require "jekyll_privatus_analytics/page_props"
+require "jekyll_privatus_analytics/configuration"
+require "jekyll_privatus_analytics/tag"
+require "jekyll_privatus_analytics/arguments"
+require "jekyll_privatus_analytics/liquid_tags"
+require "jekyll_privatus_analytics/injector"
+
+# Adds the cookieless Privatus Analytics tracking script to Jekyll sites.
+#
+# The plugin only prints the browser script and HTML attributes. It never sends events from the build.
+module JekyllPrivatusAnalytics
+end

data/lib/jekyll_privatus_analytics/arguments.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JekyllPrivatusAnalytics
+  # Reads Liquid tag arguments like: "Export CSV" format="csv" rows=page.rows beta=true
+  #
+  # Quoted text stays text. true, false, nil and numbers become those values.
+  # Anything else is looked up as a Liquid variable, like page.title.
+  class Arguments
+    TOKEN = /(?:([A-Za-z0-9_-]+)\s*=\s*)?("(?:[^"]*)"|'(?:[^']*)'|[^\s"']+)/
+    NUMBER = /\A-?\d+(\.\d+)?\z/
+    LITERALS = { "true" => true, "false" => false, "nil" => nil, "null" => nil }.freeze
+
+    attr_reader :positional, :named
+
+    def initialize(markup)
+      @positional = []
+      @named = []
+      markup.to_s.scan(TOKEN) do |key, value|
+        key ? @named << [key, value] : @positional << value
+      end
+    end
+
+    # The first unnamed argument, resolved.
+    def first(context)
+      positional.empty? ? nil : resolve(positional.first, context)
+    end
+
+    # The named arguments as a hash, resolved.
+    def options(context)
+      named.to_h { |key, value| [key, resolve(value, context)] }
+    end
+
+    private
+
+    def resolve(token, context)
+      return token[1..-2] if token.start_with?('"', "'")
+      return LITERALS[token] if LITERALS.key?(token)
+      return (token.include?(".") ? token.to_f : token.to_i) if token.match?(NUMBER)
+
+      context[token]
+    end
+  end
+end

data/lib/jekyll_privatus_analytics/attributes.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module JekyllPrivatusAnalytics
+  # Builds the data attributes the tracker reads for custom events and click maps.
+  module Attributes
+    MAX_NAME = 120
+    MAX_KEY = 64
+    MAX_PROPS = 30
+    MAX_VALUE = 500
+    CLICK_NAME = /\A[A-Za-z0-9_.:-]{1,100}\z/
+
+    module_function
+
+    # { "data-privatus-event" => name, "data-privatus-prop-<key>" => value, ... }, or {} for an empty name.
+    def event(name, props = {})
+      name = name.to_s.strip[0, MAX_NAME].to_s.strip
+      return {} if name.empty?
+
+      attrs = { "data-privatus-event" => name }
+      normalize(props).each { |key, value| attrs["data-privatus-prop-#{key}"] = string_value(value) }
+      attrs
+    end
+
+    # { "data-privatus-click" => name }, or {} when the name is not valid.
+    def click(name)
+      valid_click?(name) ? { "data-privatus-click" => name.to_s } : {}
+    end
+
+    # Whether a click map name is valid: letters, digits, _ . : - and at most 100 characters.
+    def valid_click?(name)
+      name.to_s.match?(CLICK_NAME)
+    end
+
+    # Turns an attribute hash into HTML, with every value escaped.
+    def to_html(attrs)
+      attrs.map { |name, value| %(#{name}="#{CGI.escapeHTML(value.to_s)}") }.join(" ")
+    end
+
+    # Lowercases keys, swaps anything outside a-z 0-9 _ for _, cuts them to 64 characters,
+    # drops nil values and keeps the first 30 props.
+    def normalize(props)
+      clean = {}
+      (props || {}).to_h.each do |key, value|
+        key = normalize_key(key)
+        clean[key] = value unless key.empty? || value.nil?
+      end
+      clean.first(MAX_PROPS).to_h
+    end
+
+    def normalize_key(key)
+      key.to_s.downcase.gsub(/[^a-z0-9_]/, "_")[0, MAX_KEY]
+    end
+
+    def string_value(value)
+      text = value.is_a?(Array) ? value.compact.join(",") : value.to_s
+      text[0, MAX_VALUE]
+    end
+  end
+end

data/lib/jekyll_privatus_analytics/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module JekyllPrivatusAnalytics
+  # Reads the `privatus_analytics:` settings from _config.yml.
+  class Configuration
+    DEFAULT_HOST = "https://privatusstats.com"
+    SPA_MODES = %w[auto history hash off].freeze
+    DEFAULT_ENVIRONMENTS = %w[production].freeze
+
+    def self.for_site(site)
+      new(site.config["privatus_analytics"])
+    end
+
+    def initialize(settings = {})
+      @settings = settings.is_a?(Hash) ? settings.transform_keys(&:to_s) : {}
+    end
+
+    # A raw setting, for example self["modules"].
+    def [](name)
+      @settings[name.to_s]
+    end
+
+    # The site id (starts with pa_). Falls back to ENV["PRIVATUS_SITE_ID"].
+    def site_id
+      value = self["site_id"].to_s.strip
+      value = ENV.fetch("PRIVATUS_SITE_ID", "").strip if value.empty?
+      value.empty? ? nil : value
+    end
+
+    # Origin that serves /js/pa.js. Falls back to ENV["PRIVATUS_SCRIPT_HOST"].
+    def script_host
+      value = self["script_host"].to_s.strip
+      value = ENV.fetch("PRIVATUS_SCRIPT_HOST", "").strip if value.empty?
+      value = DEFAULT_HOST if value.empty?
+      value.chomp("/")
+    end
+
+    # `enabled: true` or `false` forces it. Otherwise on when JEKYLL_ENV is in enabled_environments.
+    def enabled?(environment = Jekyll.env)
+      enabled = self["enabled"]
+      return enabled == true unless enabled.nil?
+
+      environments = self["enabled_environments"]
+      environments = DEFAULT_ENVIRONMENTS if environments.nil?
+      Array(environments).map(&:to_s).include?(environment.to_s)
+    end
+
+    def auto_inject?
+      self["auto_inject"] == true
+    end
+
+    def extra_attributes
+      value = self["extra_attributes"]
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def props
+      value = self["props"]
+      value.is_a?(Hash) ? value : {}
+    end
+  end
+end

data/lib/jekyll_privatus_analytics/injector.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module JekyllPrivatusAnalytics
+  # Adds the tag just before </head> in every HTML page and document.
+  # Off unless `auto_inject: true` is set under privatus_analytics in _config.yml.
+  module Injector
+    HEAD_CLOSE = %r{</head>}i
+    # A real queue stub script (with or without a nonce). Shown as text in a code block,
+    # the "<script" is escaped, so it does not match.
+    STUB_SCRIPT = /<script\b[^>]*>#{Regexp.escape(Tag::QUEUE_STUB[0, 40])}/
+
+    module_function
+
+    def call(item)
+      configuration = Configuration.for_site(item.site)
+      return unless configuration.auto_inject? && html?(item)
+
+      tag = Tag.new(configuration, "page_props" => item.data["privatus_props"])
+      # When the tag is off, to_s is the queue stub alone (queue_stub on) or "", and props are not used.
+      item.output = inject(item.output, tag.to_s)
+    end
+
+    def html?(item)
+      item.output.is_a?(String) && item.output_ext == ".html"
+    end
+
+    # Only the head is checked for the tag, so a page that shows the snippet as text still gets it.
+    # The queue stub alone (the tag is off) is skipped when the page already prints a stub anywhere,
+    # for example from {% privatus_analytics %}, so a page never gets two.
+    def inject(html, tag)
+      match = HEAD_CLOSE.match(html)
+      return html if tag.empty? || match.nil? || match.pre_match.include?(Tag::MARKER)
+      return html if !tag.include?(Tag::MARKER) && html.match?(STUB_SCRIPT)
+
+      "#{match.pre_match}#{tag}\n#{match}#{match.post_match}"
+    end
+  end
+end
+
+Jekyll::Hooks.register [:pages, :documents], :post_render do |item|
+  JekyllPrivatusAnalytics::Injector.call(item)
+end

data/lib/jekyll_privatus_analytics/liquid_tags.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JekyllPrivatusAnalytics
+  # {% privatus_analytics %} prints the script tag. Named arguments override settings for this call:
+  #   {% privatus_analytics modules="engage,auto" queue_stub=true %}
+  class AnalyticsTag < Liquid::Tag
+    def initialize(tag_name, markup, parse_context)
+      super
+      @arguments = Arguments.new(markup)
+    end
+
+    def render(context)
+      site = context.registers[:site]
+      page = context.registers[:page] || {}
+      overrides = @arguments.options(context)
+      overrides["page_props"] = page["privatus_props"]
+      Tag.new(Configuration.for_site(site), overrides).to_s
+    end
+  end
+
+  # {% privatus_event "Export CSV" format="csv" source="toolbar" %} prints the event data attributes.
+  # They print in every environment. They do nothing without the tracker.
+  class EventTag < Liquid::Tag
+    def initialize(tag_name, markup, parse_context)
+      super
+      @arguments = Arguments.new(markup)
+    end
+
+    def render(context)
+      Attributes.to_html(Attributes.event(@arguments.first(context), @arguments.options(context)))
+    end
+  end
+
+  # {% privatus_click "pricing.cta" %} prints the click map name attribute, or nothing when not valid.
+  class ClickTag < Liquid::Tag
+    def initialize(tag_name, markup, parse_context)
+      super
+      @arguments = Arguments.new(markup)
+    end
+
+    def render(context)
+      name = @arguments.first(context)
+      return Attributes.to_html(Attributes.click(name)) if Attributes.valid_click?(name)
+
+      unless Jekyll.env == "production"
+        Jekyll.logger.warn("Privatus:", "click map name #{name.inspect} is not valid. Use letters, digits " \
+                                        "and _ . : - only, at most 100 characters. Nothing was printed.")
+      end
+      ""
+    end
+  end
+end
+
+Liquid::Template.register_tag("privatus_analytics", JekyllPrivatusAnalytics::AnalyticsTag)
+Liquid::Template.register_tag("privatus_event", JekyllPrivatusAnalytics::EventTag)
+Liquid::Template.register_tag("privatus_click", JekyllPrivatusAnalytics::ClickTag)

data/lib/jekyll_privatus_analytics/page_props.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JekyllPrivatusAnalytics
+  # Turns page props (docs version, section and so on) into JSON that is safe inside a <script>.
+  # Keys follow the same rules as event props. Numbers, booleans and lists keep their JSON types.
+  module PageProps
+    MAX_ITEMS = 30
+    UNSAFE = /[<>&

]/
+
+    module_function
+
+    # A JSON object string, or nil when there are no props to send.
+    def json(props)
+      clean = Attributes.normalize(props).filter_map do |key, value|
+        value = json_value(value)
+        [key, value] unless value.nil?
+      end
+      return nil if clean.empty?
+
+      JSON.generate(clean.to_h).gsub(UNSAFE) { |char| format("\\u%04x", char.ord) }
+    end
+
+    def json_value(value)
+      return value.compact.first(MAX_ITEMS).filter_map { |item| scalar(item) } if value.is_a?(Array)
+
+      scalar(value)
+    end
+
+    def scalar(value)
+      case value
+      when nil then nil
+      when true, false, Integer then value
+      when Float then value.finite? ? value : nil
+      else value.to_s.scrub[0, Attributes::MAX_VALUE]
+      end
+    end
+  end
+end

data/lib/jekyll_privatus_analytics/tag.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module JekyllPrivatusAnalytics
+  # Builds the script tag. When the tag is off it prints only the queue stub (with queue_stub), or nothing.
+  #
+  # Before the tracker tag it can also print the queue stub (queue_stub) and the
+  # page props script (props), each with the nonce when there is one.
+  class Tag
+    LIST_OPTIONS = { "modules" => "data-modules", "excluded_paths" => "data-exclude",
+                     "domains" => "data-domains" }.freeze
+    PROPS_FUNCTION = "privatusPageProps"
+    MARKER = "/js/pa.js"
+    QUEUE_STUB = "window.privatus=window.privatus||{q:[]};['track','pageview','props','optOut','optIn','ready']" \
+                 ".forEach(function(m){window.privatus[m]=window.privatus[m]||function(){window.privatus.q.push(" \
+                 "[m,Array.prototype.slice.call(arguments)])}})"
+
+    # overrides: any setting by name, plus "page_props" (the page's privatus_props front matter).
+    # Props are merged in this order: _config.yml, front matter, the "props" override. nil removes one.
+    def initialize(configuration, overrides = {})
+      @configuration = configuration
+      @overrides = (overrides || {}).transform_keys(&:to_s)
+    end
+
+    def render?
+      !site_id.nil? && enabled?
+    end
+
+    # The tag is off (disabled, or no site id): only the queue stub when queue_stub is on, else "".
+    # Then privatus.track calls in your own JavaScript queue up and never fail. Props are not used.
+    def to_s
+      return off_html unless render?
+
+      props_json = PageProps.json(page_props)
+      html = []
+      html << inline_script(QUEUE_STUB) if option("queue_stub") == true
+      html << inline_script("window.#{PROPS_FUNCTION}=function(){return #{props_json}}") if props_json
+      html << script_tag(props_json ? { "data-props" => PROPS_FUNCTION } : {})
+      html.join("\n")
+    end
+
+    def attributes
+      attrs = { "defer" => true, "src" => "#{script_host}#{MARKER}", "data-site" => site_id }
+      add_options(attrs)
+      @configuration.extra_attributes.each { |name, value| attrs[name.to_s] = value unless value.nil? }
+      attrs["nonce"] = nonce if nonce
+      attrs
+    end
+
+    def page_props
+      [@configuration.props, @overrides["page_props"], @overrides["props"]].reduce({}) do |merged, layer|
+        merged.merge(keyed(layer))
+      end
+    end
+
+    def off_html
+      option("queue_stub") == true ? inline_script(QUEUE_STUB) : ""
+    end
+
+    private
+
+    def site_id
+      value = @overrides["site_id"].to_s.strip
+      value.empty? ? @configuration.site_id : value
+    end
+
+    def script_host
+      value = @overrides["script_host"].to_s.strip
+      value.empty? ? @configuration.script_host : value.chomp("/")
+    end
+
+    def enabled?
+      @overrides.key?("enabled") ? @overrides["enabled"] == true : @configuration.enabled?
+    end
+
+    def nonce
+      value = option("nonce").to_s
+      value.empty? ? nil : value
+    end
+
+    def script_tag(more)
+      parts = attributes.merge(more).map do |name, value|
+        value == true ? name : %(#{name}="#{CGI.escapeHTML(value.to_s)}")
+      end
+      "<script #{parts.join(' ')}></script>"
+    end
+
+    def inline_script(code)
+      opening = nonce ? %(<script nonce="#{CGI.escapeHTML(nonce)}">) : "<script>"
+      "#{opening}#{code}</script>"
+    end
+
+    def keyed(props)
+      return {} unless props.is_a?(Hash)
+
+      props.transform_keys { |key| Attributes.normalize_key(key) }
+    end
+
+    def add_options(attrs)
+      LIST_OPTIONS.each do |name, attribute|
+        values = list(option(name))
+        # nil keeps the tracker default. An empty modules list loads none.
+        attrs[attribute] = values.join(",") if values && (name == "modules" || !values.empty?)
+      end
+      spa = option("spa").to_s
+      attrs["data-spa"] = spa if Configuration::SPA_MODES.include?(spa) && spa != "auto"
+      attrs["data-manual"] = "true" if option("manual") == true
+    end
+
+    def option(name)
+      @overrides.key?(name) ? @overrides[name] : @configuration[name]
+    end
+
+    # nil stays nil. Anything else becomes a clean array of strings.
+    def list(value)
+      return nil if value.nil?
+
+      Array(value).flat_map { |item| item.to_s.split(",") }.map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/jekyll_privatus_analytics/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllPrivatusAnalytics
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-privatus-analytics
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Two Phase LLC
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: Liquid tags for the Privatus Analytics tracking script, custom events
+  and click maps, with optional automatic injection into every page. The script sets
+  no cookies, so analytics does not need a consent banner by itself.
+email:
+- james@privatusanalytics.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-privatus-analytics.rb
+- lib/jekyll_privatus_analytics/arguments.rb
+- lib/jekyll_privatus_analytics/attributes.rb
+- lib/jekyll_privatus_analytics/configuration.rb
+- lib/jekyll_privatus_analytics/injector.rb
+- lib/jekyll_privatus_analytics/liquid_tags.rb
+- lib/jekyll_privatus_analytics/page_props.rb
+- lib/jekyll_privatus_analytics/tag.rb
+- lib/jekyll_privatus_analytics/version.rb
+homepage: https://privatusanalytics.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://privatusanalytics.com
+  source_code_uri: https://github.com/Privatus-Analytics/jekyll
+  changelog_uri: https://github.com/Privatus-Analytics/jekyll/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Privatus-Analytics/jekyll/issues
+  documentation_uri: https://privatusanalytics.com/docs
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Cookieless Privatus Analytics tracking script for Jekyll sites.
+test_files: []