Improve readme, add site-wide CSP (#3485 )

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>

2026-01-28 21:22:27 -03:00

7.5 KiB

Raw Blame History

Analytics Setup Guide

This guide helps you add website analytics to track visitor statistics and behavior.

Analytics Setup Guide

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

Create a Google Analytics account:
- Visit Google Analytics
- Sign in with your Google account
- Click Start measuring → Create account
Create a property for your website:
- Enter your website name and URL
- Accept terms and continue
- Choose your timezone and currency
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)
Add to your site:
- Open _config.yml in your repository
- Find the google_analytics: line and add your ID:
```
google_analytics: G-XXXXXXXXXX
```
- Commit and push
- Wait for deployment to complete
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:

Create an account at Plausible.io
Add your domain
Add this script to your site's <head> tag
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

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:

Sign up at Pirsch.io
Add your domain
Copy the tracking code

In _config.yml, add:

pirsch_analytics: YOUR_SITE_ID # Format: 32 characters

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:

Sign up at Openpanel.dev
Create a project for your website
Get your Client ID

In _config.yml, add:

openpanel_analytics: YOUR_CLIENT_ID # Format: UUID

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:

Create account at Cronitor.io
Get your Site ID
In _config.yml, add:
```
cronitor_analytics: YOUR_SITE_ID
```
Commit and push

If you're in the European Union or serve EU visitors, consider GDPR requirements:

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

✅ Plausible Analytics
✅ Pirsch Analytics
✅ Openpanel Analytics
✅ GoAccess

❌ Google Analytics (EU users must consent first)

Simple Privacy Policy Template

Add a privacy policy page at _pages/privacy.md:

---
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

Choose a service based on your needs (privacy, features, budget)
Follow the setup guide for your chosen service
Verify it's working by visiting your site and checking the analytics dashboard
(Optional) Add a privacy policy to your website

For more customization help, see CUSTOMIZE.md or use the GitHub Copilot Customization Agent.

7.5 KiB Raw Blame History

Analytics Setup Guide

Overview

Google Analytics

Setup Steps

Configuration

Privacy-Friendly Alternatives

Plausible Analytics

GoAccess (Self-hosted)

Pirsch Analytics

Openpanel Analytics

Other Analytics Services

Cronitor

GDPR and Privacy Considerations

GDPR Checklist

Privacy-first services (No GDPR cookie banner needed)

Services requiring cookie consent

Simple Privacy Policy Template

Comparing Analytics Services

Next Steps

7.5 KiB

Raw Blame History