Zer0-Mistakes Jekyll theme now includes full PostHog analytics integration with privacy-first design, GDPR/CCPA compliance, and comprehensive event tracking tailored for Jekyll sites.
_config.ymlAdd the following to your _config.yml:
posthog:
enabled: true
api_key: "your-posthog-api-key"
api_host: "https://us.i.posthog.com" # or your self-hosted instance
person_profiles: "identified_only"
autocapture: true
capture_pageview: true
capture_pageleave: true
respect_dnt: true
posthog:
enabled: true
api_key: "phc_your_api_key_here"
api_host: "https://us.i.posthog.com"
person_profiles: "identified_only" # Options: 'always', 'identified_only', 'never'
autocapture: true # Automatically capture clicks, form submissions, etc.
capture_pageview: true # Track page views
capture_pageleave: true # Track when users leave pages
session_recording: false # Enable session recordings (privacy consideration)
disable_cookie: false # Set to true for cookieless tracking
respect_dnt: true # Respect Do Not Track browser setting
cross_subdomain_cookie: false # Enable if you have multiple subdomains
secure_cookie: true # Use secure cookies in production
persistence: "localStorage+cookie" # Options: 'localStorage+cookie', 'cookie', 'memory'
# Custom event tracking configuration
custom_events:
track_downloads: true # Track PDF, ZIP, etc. downloads
track_external_links: true # Track clicks to external websites
track_search: true # Track search queries
track_scroll_depth: true # Track how far users scroll
# Privacy settings
privacy:
mask_all_text: false # Mask all text in session recordings
mask_all_inputs: true # Mask form inputs in session recordings
ip_anonymization: false # Anonymize IP addresses
In _config_dev.yml, analytics are automatically disabled:
# Analytics disabled in development
posthog:
enabled: false
api_key: null
api_host: null
Access consent state in your custom code:
// Check if user has consented to analytics
if (window.cookieManager.hasConsent("analytics")) {
// Analytics are enabled
window.zer0Analytics.track("custom_event", { property: "value" });
}
// Listen for consent changes
document.addEventListener("cookieConsentChanged", function (event) {
console.log("Consent updated:", event.detail);
});
The theme automatically tracks:
| Event | Description | Properties |
|---|---|---|
file_download |
PDF, ZIP, document downloads | file_url, file_name, page_url |
external_link_click |
Clicks to external websites | link_url, link_text, page_url |
search_query |
Search functionality usage | search_term, page_url |
scroll_depth |
Reading engagement (25%, 50%, 75%, 90%) | depth_percentage, page_url, page_title |
code_interaction |
Code block clicks/interactions | interaction_type, page_url |
toc_click |
Table of contents navigation | toc_link, toc_text, page_url |
sidebar_navigation |
Sidebar link clicks | nav_link, nav_text, page_url |
Use the global zer0Analytics object for custom tracking:
// Track a custom event
window.zer0Analytics.track("button_click", {
button_id: "subscribe",
page_section: "header",
user_type: "visitor",
});
// Identify a user (for logged-in users)
window.zer0Analytics.identify("user123", {
email: "user@example.com",
subscription: "pro",
signup_date: "2024-01-15",
});
// Reset user session (for logout)
window.zer0Analytics.reset();
Every event includes Jekyll-specific context:
{
'site_title': 'Your Site Title',
'site_description': 'Your site description',
'jekyll_version': '4.3.2',
'theme': 'bamr87/zer0-mistakes',
'page_layout': 'journals',
'page_collection': 'posts',
'page_categories': ['development', 'jekyll'],
'page_tags': ['tutorial', 'analytics'],
'page_url': '/posts/2024/01/15/analytics-setup/',
'page_title': 'Setting Up Analytics',
'page_author': 'Your Name',
'page_date': '2024-01-15'
}
Different Jekyll collections get specialized tracking:
_posts): Tracks reading time, social shares, related post clicks_docs): Monitors navigation patterns, search usage| Feature | Development | Production |
|---|---|---|
| Analytics Loading | Disabled | Enabled (with consent) |
| Console Logging | Verbose | Minimal |
| Cookie Banner | Hidden | Visible |
| DNT Respect | N/A | Active |
| Session Recording | Disabled | Configurable |
Update your _config.yml with PostHog settings:
posthog:
enabled: true
api_key: "phc_your_api_key_here"
api_host: "https://us.i.posthog.com"
# Add other configuration options as needed
Update your privacy policy to include:
enabled: true in staging configAnalytics not loading
jekyll.environment is set to “production”site.posthog.enabled is trueCookie banner not appearing
localStorage.removeItem('zer0-cookie-consent')Events not tracking
Enable PostHog debug mode in browser console:
posthog.debug(true);
Useful browser console commands:
// Check consent status
console.log(window.cookieManager.getConsent());
// Force show cookie banner
window.cookieManager.showBanner();
// Test analytics
window.zer0Analytics.track("test_event", { source: "manual" });
For issues or questions about PostHog integration:
This integration provides a complete, privacy-compliant analytics solution for Jekyll sites with the flexibility to grow with your needs while respecting user privacy.