cc6284d18f
This pull request significantly expands and clarifies the documentation for the al-folio Jekyll theme, focusing on improved file structure explanations, enhanced quick reference guides, and the addition of a comprehensive analytics setup guide. The changes make it easier for users and contributors to understand the project organization, available features, and configuration options, especially regarding CV formats, teaching pages, and analytics integration. **Key documentation and structure improvements:** *Expanded file and collection structure:* - The file structure documentation in `.github/agents/customize.agent.md` and `.github/agents/docs.agent.md` now details all major directories, including new and existing collections such as `_books/`, `_teachings/`, `_scripts/`, `_plugins/`, and expanded `assets/` subdirectories. It also covers new configuration and utility files, making it easier for users to locate and understand the purpose of each file or folder. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58) *Documentation and quick reference enhancements:* - The quick reference table in `.github/agents/customize.agent.md` has been updated to include new actions like adding teaching pages, setting up analytics, improving SEO, and ensuring accessibility, with more precise documentation links. - The documentation map now lists all major guides (e.g., `QUICKSTART.md`, `INSTALL.md`, `TROUBLESHOOTING.md`, `ACCESSIBILITY.md`, `ANALYTICS.md`, `SEO.md`), providing a clearer overview of available resources. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L58-R110) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58) **Feature and configuration documentation updates:** *CV/resume format guidance:* - The CV documentation now clarifies that users can maintain both RenderCV and JSONResume formats simultaneously, with clear instructions on switching between them and deleting unused files if desired. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L139-R185) [[2]](diffhunk://#diff-52f2a9488bfe4177d1f1d01120859dad0b3e2d087283ded68f72d47b4f183391L291-R291) *Teaching pages and new collections:* - Adds documentation for the new `_teachings/` collection, including required frontmatter and support for course materials, as well as updates to enable/disable teaching and books pages via `_config.yml`. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66) *Analytics integration:* - Introduces a new `ANALYTICS.md` guide with detailed setup instructions for Google Analytics, privacy-friendly alternatives (Plausible, Pirsch, Openpanel, GoAccess), GDPR considerations, and a comparison table to help users choose the right analytics provider. - The configuration documentation now references analytics setup and related configuration options. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L479-R550) These updates collectively make the documentation more comprehensive, actionable, and user-friendly for both new and advanced users. **References:** [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L58-R110) [[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L139-R185) [[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252) [[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L479-R550) [[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58) [[7]](diffhunk://#diff-0967e840631a541bb95e057e1c6d4884274cf56d5a217d7fee2eb7223b6b4c0dR1-R268) [[8]](diffhunk://#diff-52f2a9488bfe4177d1f1d01120859dad0b3e2d087283ded68f72d47b4f183391L291-R291) --------- Signed-off-by: George Araújo <george.gcac@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
269 lines
7.5 KiB
Markdown
269 lines
7.5 KiB
Markdown
# Analytics Setup Guide
|
|
|
|
This guide helps you add website analytics to track visitor statistics and behavior.
|
|
|
|
<!--ts-->
|
|
|
|
- [Analytics Setup Guide](#analytics-setup-guide)
|
|
- [Overview](#overview)
|
|
- [Google Analytics](#google-analytics)
|
|
- [Setup Steps](#setup-steps)
|
|
- [Configuration](#configuration)
|
|
- [Privacy-Friendly Alternatives](#privacy-friendly-alternatives)
|
|
- [Plausible Analytics](#plausible-analytics)
|
|
- [GoAccess (Self-hosted)](#goaccess-self-hosted)
|
|
- [Pirsch Analytics](#pirsch-analytics)
|
|
- [Openpanel Analytics](#openpanel-analytics)
|
|
- [Other Analytics Services](#other-analytics-services)
|
|
- [Cronitor](#cronitor)
|
|
- [GDPR and Privacy Considerations](#gdpr-and-privacy-considerations)
|
|
- [Comparing Analytics Services](#comparing-analytics-services)
|
|
<!--te-->
|
|
|
|
## Overview
|
|
|
|
Analytics help you understand your website visitors: where they come from, which pages they visit, and how they interact with your content. al-folio supports multiple analytics providers.
|
|
|
|
**Available analytics in al-folio:**
|
|
|
|
- **Google Analytics** (free, feature-rich, but privacy concerns)
|
|
- **Plausible Analytics** (paid, privacy-first, GDPR-compliant)
|
|
- **Pirsch Analytics** (freemium, GDPR-compliant, European servers)
|
|
- **Openpanel Analytics** (open-source, self-hosted option)
|
|
- **Cronitor** (uptime monitoring + RUM analytics)
|
|
|
|
---
|
|
|
|
## Google Analytics
|
|
|
|
Google Analytics is free and widely used. It provides detailed insights into visitor behavior but collects more user data.
|
|
|
|
### Setup Steps
|
|
|
|
1. **Create a Google Analytics account:**
|
|
- Visit [Google Analytics](https://analytics.google.com)
|
|
- Sign in with your Google account
|
|
- Click **Start measuring** → **Create account**
|
|
|
|
2. **Create a property for your website:**
|
|
- Enter your website name and URL
|
|
- Accept terms and continue
|
|
- Choose your timezone and currency
|
|
|
|
3. **Get your Measurement ID:**
|
|
- In the left sidebar, go to **Admin** → **Properties**
|
|
- Click **Data Streams** → **Web** (or your existing stream)
|
|
- Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)
|
|
|
|
4. **Add to your site:**
|
|
- Open `_config.yml` in your repository
|
|
- Find the `google_analytics:` line and add your ID:
|
|
```yaml
|
|
google_analytics: G-XXXXXXXXXX
|
|
```
|
|
- Commit and push
|
|
- Wait for deployment to complete
|
|
|
|
5. **Verify it's working:**
|
|
- Visit your website
|
|
- Go back to Google Analytics → **Real-time** tab
|
|
- You should see your visit appear within a few seconds
|
|
|
|
### Configuration
|
|
|
|
Google Analytics is auto-injected into your site once you set `google_analytics` in `_config.yml`. No additional code needed.
|
|
|
|
**Note:** Google Analytics takes 24-48 hours to start showing data trends.
|
|
|
|
---
|
|
|
|
## Privacy-Friendly Alternatives
|
|
|
|
If you're concerned about user privacy or GDPR compliance, consider these alternatives:
|
|
|
|
### Plausible Analytics
|
|
|
|
**Best for:** Privacy-conscious academics and researchers
|
|
|
|
**Features:**
|
|
|
|
- ✅ GDPR and privacy laws compliant
|
|
- ✅ No cookie consent banner needed
|
|
- ✅ Clear, simple dashboard
|
|
- ✅ Email reports
|
|
- ❌ Paid service ($9-20/month)
|
|
|
|
**Setup:**
|
|
|
|
1. Create an account at [Plausible.io](https://plausible.io)
|
|
2. Add your domain
|
|
3. Add this script to your site's `<head>` tag
|
|
4. Plausible provides installation instructions for Jekyll
|
|
|
|
**For al-folio:**
|
|
|
|
- Edit `_includes/head.liquid`
|
|
- Add the Plausible script before the closing `</head>` tag (around line 185)
|
|
- Or use a custom analytics integration (see below)
|
|
|
|
---
|
|
|
|
### GoAccess (Self-hosted)
|
|
|
|
**Best for:** Cost-conscious users with access to server logs
|
|
|
|
**Features:**
|
|
|
|
- ✅ Completely free
|
|
- ✅ No privacy concerns (analyze your own logs)
|
|
- ✅ Self-hosted
|
|
- ❌ Requires server/GitHub Pages access
|
|
- ❌ Less user-friendly than cloud services
|
|
|
|
**How it works:**
|
|
|
|
- Analyzes your web server access logs
|
|
- Generates HTML dashboard
|
|
- Run locally on your machine
|
|
- Script available in `_scripts/` directory
|
|
|
|
**See also:** [GoAccess documentation](https://goaccess.io/)
|
|
|
|
---
|
|
|
|
### Pirsch Analytics
|
|
|
|
**Best for:** GDPR-compliant analytics without complex setup
|
|
|
|
**Features:**
|
|
|
|
- ✅ GDPR compliant
|
|
- ✅ European servers
|
|
- ✅ Free tier available
|
|
- ✅ Simple integration
|
|
- ✅ No cookie consent needed
|
|
|
|
**Setup:**
|
|
|
|
1. Sign up at [Pirsch.io](https://pirsch.io)
|
|
2. Add your domain
|
|
3. Copy the tracking code
|
|
4. In `_config.yml`, add:
|
|
```yaml
|
|
pirsch_analytics: YOUR_SITE_ID # Format: 32 characters
|
|
```
|
|
5. Commit and push
|
|
|
|
(The site ID appears in your Pirsch dashboard.)
|
|
|
|
---
|
|
|
|
### Openpanel Analytics
|
|
|
|
**Best for:** Open-source and privacy-conscious developers
|
|
|
|
**Features:**
|
|
|
|
- ✅ Open-source
|
|
- ✅ Self-hosted option available
|
|
- ✅ Privacy-focused
|
|
- ✅ Modern dashboard
|
|
- ❌ Younger project (fewer features)
|
|
|
|
**Setup:**
|
|
|
|
1. Sign up at [Openpanel.dev](https://openpanel.dev)
|
|
2. Create a project for your website
|
|
3. Get your **Client ID**
|
|
4. In `_config.yml`, add:
|
|
```yaml
|
|
openpanel_analytics: YOUR_CLIENT_ID # Format: UUID
|
|
```
|
|
5. Commit and push
|
|
|
|
---
|
|
|
|
## Other Analytics Services
|
|
|
|
### Cronitor
|
|
|
|
Cronitor is an **uptime monitoring** service with RUM (Real User Monitoring) analytics.
|
|
|
|
**Best for:** Tracking if your site is online + basic performance metrics
|
|
|
|
**Setup:**
|
|
|
|
1. Create account at [Cronitor.io](https://cronitor.io)
|
|
2. Get your **Site ID**
|
|
3. In `_config.yml`, add:
|
|
```yaml
|
|
cronitor_analytics: YOUR_SITE_ID
|
|
```
|
|
4. Commit and push
|
|
|
|
---
|
|
|
|
## GDPR and Privacy Considerations
|
|
|
|
If you're in the European Union or serve EU visitors, consider GDPR requirements:
|
|
|
|
### GDPR Checklist
|
|
|
|
- [ ] If using Google Analytics: Add cookie consent banner
|
|
- [ ] Display a privacy policy explaining what analytics you use
|
|
- [ ] Allow users to opt-out if using tracking cookies
|
|
- [ ] Use privacy-first alternatives when possible
|
|
|
|
### Privacy-first services (No GDPR cookie banner needed)
|
|
|
|
- ✅ Plausible Analytics
|
|
- ✅ Pirsch Analytics
|
|
- ✅ Openpanel Analytics
|
|
- ✅ GoAccess
|
|
|
|
### Services requiring cookie consent
|
|
|
|
- ❌ Google Analytics (EU users must consent first)
|
|
|
|
### Simple Privacy Policy Template
|
|
|
|
Add a privacy policy page at `_pages/privacy.md`:
|
|
|
|
```markdown
|
|
---
|
|
layout: page
|
|
title: Privacy Policy
|
|
permalink: /privacy/
|
|
---
|
|
|
|
## Analytics
|
|
|
|
This website uses [Service Name] to understand visitor behavior. [Service Name] is GDPR-compliant and does not use cookies.
|
|
|
|
For more information, see [Service Name's privacy policy](link-to-privacy-policy).
|
|
```
|
|
|
|
---
|
|
|
|
## Comparing Analytics Services
|
|
|
|
| Service | Free | GDPR | Setup | Features | Best for |
|
|
| -------------------- | ------------ | ------------------- | ------ | ---------------- | --------------- |
|
|
| **Google Analytics** | ✅ | ⚠️ Requires consent | Easy | Detailed reports | Large sites |
|
|
| **Plausible** | ❌ | ✅ | Easy | Simple, clear | Privacy-focused |
|
|
| **Pirsch** | ✅ Free tier | ✅ | Easy | Balanced | GDPR compliance |
|
|
| **Openpanel** | ✅ | ✅ | Medium | Modern dashboard | Developers |
|
|
| **Cronitor** | Paid | ✅ | Easy | Uptime + RUM | Monitoring |
|
|
| **GoAccess** | ✅ | ✅ | Hard | Self-hosted logs | Cost-conscious |
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Choose a service** based on your needs (privacy, features, budget)
|
|
2. **Follow the setup guide** for your chosen service
|
|
3. **Verify it's working** by visiting your site and checking the analytics dashboard
|
|
4. **(Optional) Add a privacy policy** to your website
|
|
|
|
For more customization help, see [CUSTOMIZE.md](CUSTOMIZE.md) or use the **GitHub Copilot Customization Agent**.
|