Adaptations:
{% assign page_adaptations = page.adaptations | split: ' ' %}
{% for adaptation in page_adaptations %}
{{ adaptation }}
{% unless forloop.last %},{% endunless %}
{% endfor %}
{% endif %}
```
**File: `_config.yml` (jekyll-archives section)**
```yaml
jekyll-archives:
books:
enabled:
- year
- categories
- tags
- adaptations
permalinks:
year: "/:collection/:year/"
categories: "/:collection/:type/:name/"
tags: "/:collection/:type/:name/"
adaptations: "/:collection/:type/:name/"
```
After rebuilding, users can browse books by adaptation at `/books/adaptations/movie/`, etc.
## Adding a new publication
To add publications create a new entry in the [\_bibliography/papers.bib](_bibliography/papers.bib) file. You can find the BibTeX entry of a publication in Google Scholar by clicking on the quotation marks below the publication title, then clicking on "BibTeX", or also in the conference page itself. By default, the publications will be sorted by year and the most recent will be displayed first. You can change this behavior and more in the `Jekyll Scholar` section in [\_config.yml](_config.yml) file.
You can add extra information to a publication, like a PDF file in the `assets/pdfs/` directory and add the path to the PDF file in the BibTeX entry with the `pdf` field. Some of the supported fields are: `abstract`, `altmetric`, `annotation`, `arxiv`, `bibtex_show`, `blog`, `code`, `dimensions`, `doi`, `eprint`, `hal`, `html`, `isbn`, `pdf`, `pmid`, `poster`, `slides`, `supp`, `video`, and `website`.
### Author annotation
In publications, the author entry for yourself is identified by string array `scholar:last_name` and string array `scholar:first_name` in [\_config.yml](_config.yml). For example, if you have the following entry in your [\_config.yml](_config.yml):
```yaml
scholar:
last_name: [Einstein]
first_name: [Albert, A.]
```
If the entry matches one form of the last names and the first names, it will be underlined. Keep meta-information about your co-authors in [\_data/coauthors.yml](_data/coauthors.yml) and Jekyll will insert links to their webpages automatically. The co-author data format is as follows, with the last names lower cased and without accents as the key:
```yaml
"adams":
- firstname: ["Edwin", "E.", "E. P.", "Edwin Plimpton"]
url: https://en.wikipedia.org/wiki/Edwin_Plimpton_Adams
"podolsky":
- firstname: ["Boris", "B.", "B. Y.", "Boris Yakovlevich"]
url: https://en.wikipedia.org/wiki/Boris_Podolsky
"rosen":
- firstname: ["Nathan", "N."]
url: https://en.wikipedia.org/wiki/Nathan_Rosen
"bach":
- firstname: ["Johann Sebastian", "J. S."]
url: https://en.wikipedia.org/wiki/Johann_Sebastian_Bach
- firstname: ["Carl Philipp Emanuel", "C. P. E."]
url: https://en.wikipedia.org/wiki/Carl_Philipp_Emanuel_Bach
```
If the entry matches one of the combinations of the last names and the first names, it will be highlighted and linked to the url provided. Note that the keys **MUST BE** lower cased and **MUST NOT** contain accents. This is because the keys are used to match the last names in the BibTeX entries, considering possible variations (see [related discussion](https://github.com/alshedivat/al-folio/discussions/2213)).
### Buttons (through custom bibtex keywords)
There are several custom bibtex keywords that you can use to affect how the entries are displayed on the webpage:
- `abbr`: Adds an abbreviation to the left of the entry. You can add links to these by creating a venue.yaml-file in the \_data folder and adding entries that match.
- `abstract`: Adds an "Abs" button that expands a hidden text field when clicked to show the abstract text
- `altmetric`: Adds an [Altmetric](https://www.altmetric.com/) badge (Note: if DOI is provided just use `true`, otherwise only add the altmetric identifier here - the link is generated automatically)
- `annotation`: Adds a popover info message to the end of the author list that can potentially be used to clarify superscripts. HTML is allowed.
- `arxiv`: Adds a link to the Arxiv website (Note: only add the arxiv identifier here - the link is generated automatically)
- `bibtex_show`: Adds a "Bib" button that expands a hidden text field with the full bibliography entry
- `blog`: Adds a "Blog" button redirecting to the specified link
- `code`: Adds a "Code" button redirecting to the specified link
- `dimensions`: Adds a [Dimensions](https://www.dimensions.ai/) badge (Note: if DOI or PMID is provided just use `true`, otherwise only add the Dimensions' identifier here - the link is generated automatically)
- `hal`: Adds a link to the HAL website (Note: only add the hal identifier (hal-xxx or tel-xxx) here - the link is generated automatically)
- `html`: Inserts an "HTML" button redirecting to the user-specified link
- `pdf`: Adds a "PDF" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory)
- `poster`: Adds a "Poster" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory)
- `slides`: Adds a "Slides" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory)
- `supp`: Adds a "Supp" button to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory)
- `website`: Adds a "Website" button redirecting to the specified link
You can implement your own buttons by editing the [\_layouts/bib.liquid](_layouts/bib.liquid) file.
## Changing theme color
A variety of beautiful theme colors have been selected for you to choose from. The default is purple, but you can quickly change it by editing the `--global-theme-color` variable in the [\_sass/\_themes.scss](_sass/_themes.scss) file. Other color variables are listed there as well. The stock theme color options available can be found at [\_sass/\_variables.scss](_sass/_variables.scss). You can also add your own colors to this file assigning each a name for ease of use across the template.
## Customizing layout and UI
You can customize the layout and user interface in [\_config.yml](_config.yml):
```yaml
back_to_top: true
footer_fixed: true
max_width: 930px
navbar_fixed: true
```
- `back_to_top`: Displays a "back to top" button in the footer. When clicked, it smoothly scrolls the page back to the top.
- `footer_fixed`: When `true`, the footer remains fixed at the bottom of the viewport. When `false`, it appears at the end of the page content.
- `max_width`: Controls the maximum width of the main content area in pixels. The default is `930px`. You can adjust this to make your content wider or narrower.
- `navbar_fixed`: When `true`, the navigation bar stays fixed at the top of the page when scrolling. When `false`, it scrolls with the page content.
## Adding social media information
Social media information is managed through the [`jekyll-socials` plugin](https://github.com/george-gca/jekyll-socials). To add your social media links:
1. Edit [`_data/socials.yml`](_data/socials.yml) to add your social profiles
2. The plugin will automatically display the social icons based on the order they are defined in the file (see the comments at the top of `_data/socials.yml`)
The template supports icons from:
- [Academicons](https://jpswalsh.github.io/academicons/)
- [Font Awesome](https://fontawesome.com/)
- [Scholar Icons](https://louisfacun.github.io/scholar-icons/)
Social media links will appear at the bottom of the `About` page and in the search results by default. You can customize this behavior in [`_config.yml`](_config.yml):
- `enable_navbar_social: true` β Display social links in the navigation bar
- `socials_in_search: false` β Remove social links from search results
For more details, see the [`jekyll-socials` documentation](https://github.com/george-gca/jekyll-socials).
## Adding a newsletter
You can add a newsletter subscription form by adding the specified information at the `newsletter` section in the [\_config.yml](_config.yml) file. To set up a newsletter, you can use a service like [Loops.so](https://loops.so/), which is the current supported solution. Once you have set up your newsletter, you can add the form [endpoint](https://loops.so/docs/forms/custom-form) to the `endpoint` field in the `newsletter` section of the [\_config.yml](_config.yml) file.
Depending on your specified footer behavior, the sign up form either will appear at the bottom of the `About` page and at the bottom of blogposts if `related_posts` are enabled, or in the footer at the bottom of each page.
## Configuring search features
The theme includes a powerful search functionality that can be customized in [\_config.yml](_config.yml):
```yaml
bib_search: true
posts_in_search: true
search_enabled: true
socials_in_search: true
```
- `bib_search`: Enables search within your publications/bibliography. When enabled, a search box appears on the publications page, allowing visitors to filter publications by title, author, venue, or year.
- `posts_in_search`: Includes blog posts in the search index. Users can search for posts by title, content, or tags.
- `search_enabled`: Enables the site-wide search feature. When enabled, a search box appears in the navigation bar, allowing users to search across your site content.
- `socials_in_search`: Includes your social media links and contact information in search results. This makes it easier for visitors to find ways to connect with you.
All these search features work in real-time and do not require a page reload.
## Social media previews
**al-folio** supports Open Graph (OG) meta tags, which create rich preview objects when your pages are shared on social media platforms like Twitter, Facebook, LinkedIn, and others. These previews include your site's image, title, and description.
### How to enable
To enable social media previews:
1. Open `_config.yml` and set:
```yaml
serve_og_meta: true
```
2. Rebuild your site:
```bash
docker compose down && docker compose up
# or
bundle exec jekyll serve
```
Once enabled, all your site's pages will automatically include Open Graph meta tags in the HTML head element.
### Configuring preview images
You can configure what image displays in social media previews on a per-page or site-wide basis.
**Site-wide default image:**
Add the following to `_config.yml`:
```yaml
og_image: /assets/img/your-default-preview-image.png
```
Replace the path with your actual image location in `assets/img/`.
**Per-page custom image:**
To override the site-wide default for a specific page, add `og_image` to the page's frontmatter:
```yaml
---
layout: page
title: My Page
og_image: /assets/img/custom-preview-image.png
---
```
### Preview image best practices
- **Dimensions:** Use 1200Γ630 pixels for optimal display on most social media platforms
- **Format:** PNG or JPG formats work best
- **Size:** Keep file size under 5MB
- **Content:** Ensure the image clearly represents your page content
When a page is shared on social media, the platform will display your configured image along with the page title, description (from your site title or page description), and URL.
---
## Related posts
The theme can automatically display related posts at the bottom of each blog post. These are selected by finding the most recent posts that share common tags with the current post.
### How it works
- By default, the most recent posts that share at least one tag with the current post are displayed
- You can customize how many posts are shown and how many tags must match
- You can disable related posts for individual posts or across your entire site
### Configuration
To customize related posts behavior, edit the `related_blog_posts` section in `_config.yml`:
```yaml
related_blog_posts:
enabled: true
max_related: 5
```
- `enabled`: Set to `true` (default) to show related posts, or `false` to disable them site-wide
- `max_related`: Maximum number of related posts to display (default: 5)
The theme also uses tags to find related content. Make sure your blog posts include relevant tags in their frontmatter:
```yaml
---
layout: post
title: My Blog Post
tags: machine-learning python
---
```
### Disable related posts for a specific post
To hide related posts on an individual blog post, add this to the post's frontmatter:
```yaml
---
layout: post
title: My Blog Post
related_posts: false
---
```
### Additional configuration in \_config.yml
You can also customize related posts behavior with these settings:
```yaml
related_blog_posts:
enabled: true
max_related: 5
```
These settings control:
- Which posts are considered "related" (based on shared tags)
- How many related posts to display
- The algorithm used to calculate post similarity (uses the `classifier-reborn` gem)
---
## Managing publication display
The theme offers several options for customizing how publications are displayed:
```yaml
enable_publication_thumbnails: true
max_author_limit: 3
more_authors_animation_delay: 10
```
- `enable_publication_thumbnails`: When `true`, displays preview images for publications (if specified in the BibTeX entry with the `preview` field). Set to `false` to disable thumbnails for all publications.
- `max_author_limit`: Sets the maximum number of authors shown initially for each publication. If a publication has more authors, they are hidden behind a "more authors" link. Leave blank to always show all authors.
- `more_authors_animation_delay`: Controls the animation speed (in milliseconds) when revealing additional authors. A smaller value means faster animation.
To add a thumbnail to a publication, include a `preview` field in your BibTeX entry:
```bibtex
@article{example2024,
title={Example Paper},
author={Author, First and Author, Second},
journal={Example Journal},
year={2024},
preview={example_preview.png}
}
```
Place the image file in `assets/img/publication_preview/`.
## Adding a Google Calendar
You can embed a Google Calendar on any page by using the `calendar.liquid` include.
### Basic usage
Add the following to your page's Markdown file (for example, in `_pages/teaching.md`):
```liquid
{% include calendar.liquid calendar_id='your-calendar-id@group.calendar.google.com' timezone='Your/Timezone' %}
```
Replace:
- `your-calendar-id@group.calendar.google.com` with your actual Google Calendar ID (found in Google Calendar Settings β Integrate calendar β Calendar ID)
- `Your/Timezone` with your timezone (e.g., `UTC`, `Asia/Shanghai`, `America/New_York`). The default is `UTC`.
### Enable the calendar script for your page
To enable the calendar on your page, add `calendar: true` to the frontmatter:
```yaml
---
layout: page
title: teaching
calendar: true
---
```
This setting prevents unnecessary script loading for pages that don't display a calendar.
### Optional: Customize the calendar style
You can optionally customize the iframe styling using the `style` parameter:
```liquid
{% include calendar.liquid calendar_id='your-calendar-id@group.calendar.google.com' timezone='UTC' style='border:0; width:100%; height:800px;' %}
```
The default style is `border:0; width:100%; height:600px;`.
## Updating third-party libraries
The theme uses various third-party JavaScript and CSS libraries. You can manage these in the `third_party_libraries` section of [\_config.yml](_config.yml):
```yaml
third_party_libraries:
download: false
bootstrap-table:
version: "1.22.4"
url:
css: "https://cdn.jsdelivr.net/npm/bootstrap-table@{{version}}/dist/bootstrap-table.min.css"
js: "https://cdn.jsdelivr.net/npm/bootstrap-table@{{version}}/dist/bootstrap-table.min.js"
integrity:
css: "sha256-..."
js: "sha256-..."
```
- `download`: When `false` (default), libraries are loaded from CDNs. When `true`, the specified library versions are downloaded during build and served from your site. This can improve performance but increases your repository size.
- `version`: Specifies which version of each library to use. Update this to use a newer version.
- `url`: Template URLs for loading the library. The `{{version}}` placeholder is replaced with the version number automatically.
- `integrity`: [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes ensure that the library hasn't been tampered with. When updating a library version, you should also update its integrity hash.
To update a library:
1. Change the `version` number
2. Obtain the new integrity hash for the updated library version and update the `integrity` field with the new hash. You can:
- Check if the CDN provider (e.g., jsDelivr, cdnjs, unpkg) provides the SRI hash for the file. Many CDN sites display the SRI hash alongside the file URL.
- Generate the SRI hash yourself using a tool such as [SRI Hash Generator](https://www.srihash.org/) or by running the following command in your terminal:
```bash
curl -sL [FILE_URL] | openssl dgst -sha384 -binary | openssl base64 -A
```
Replace `[FILE_URL]` with the URL of the library file. Then, prefix the result with `sha384-` and use it in the `integrity` field.
For detailed instructions on updating specific libraries, see the FAQ:
- [How can I update Academicons version](FAQ.md#how-can-i-update-academicons-version-on-the-template)
- [How can I update Font Awesome version](FAQ.md#how-can-i-update-font-awesome-version-on-the-template)
## Removing content
Since this template has a lot of content, you may want to remove some of it. The easiest way to achieve this and avoid merge conflicts when updating your code (as [pointed by CheariX ](https://github.com/alshedivat/al-folio/pull/2933#issuecomment-2571271117)) is to add the unwanted files to the `exclude` section in your `_config.yml` file instead of actually deleting them, for example:
```yml
exclude:
- _news/announcement_*.md
- _pages/blog.md
- _posts/
- _projects/?_project.md
- assets/jupyter/blog.ipynb
```
Here is a list of the main components that you may want to delete, and how to do it. Don't forget if you delete a page to update the `nav_order` of the remaining pages.
### Removing the blog page
To remove the blog, you have to:
- delete [\_posts](_posts/) directory
- delete blog page [\_pages/blog.md](_pages/blog.md)
- remove reference to blog page in our [\_pages/dropdown.md](_pages/dropdown.md)
- remove the `latest_posts` part in [\_pages/about.md](_pages/about.md)
- remove the `Blog` section in the [\_config.yml](_config.yml) file and the related parts, like the `jekyll-archives`
You can also:
- delete [\_includes/latest_posts.liquid](_includes/latest_posts.liquid)
- delete [\_includes/related_posts.liquid](_includes/related_posts.liquid)
- delete [\_layouts/archive.liquid](_layouts/archive.liquid) (unless you have a custom collection that uses it)
- delete [\_plugins/external-posts.rb](_plugins/external-posts.rb)
- remove the `jekyll-archives-v2` gem from the [Gemfile](Gemfile) and the `plugins` section in [\_config.yml](_config.yml) (unless you have a custom collection that uses it)
- remove the `classifier-reborn` gem from the [Gemfile](Gemfile)
### Removing the news section
To remove the news section, you can:
- delete the [\_news](_news/) directory
- delete the file [\_includes/news.liquid](_includes/news.liquid) and the references to it in the [\_pages/about.md](_pages/about.md)
- remove the `announcements` part in [\_pages/about.md](_pages/about.md)
- remove the news part in the `Collections` section in the [\_config.yml](_config.yml) file
### Removing the projects page
To remove the projects, you can:
- delete the [\_projects](_projects/) directory
- delete the projects page [\_pages/projects.md](_pages/projects.md)
- remove reference to projects page in our [\_pages/dropdown.md](_pages/dropdown.md)
- remove projects part in the `Collections` section in the [\_config.yml](_config.yml) file
You can also:
- delete [\_includes/projects_horizontal.liquid](_includes/projects_horizontal.liquid)
- delete [\_includes/projects.liquid](_includes/projects.liquid)
### Removing the publications page
To remove the publications, you can:
- delete the [\_bibliography](_bibliography/) directory
- delete the publications page [\_pages/publications.md](_pages/publications.md)
- remove reference to publications page in our [\_pages/dropdown.md](_pages/dropdown.md)
- remove `Jekyll Scholar` section in the [\_config.yml](_config.yml) file
You can also:
- delete the [\_layouts/bib.liquid](_layouts/bib.liquid) file
- delete [\_includes/bib_search.liquid](_includes/bib_search.liquid)
- delete [\_includes/citation.liquid](_includes/citation.liquid)
- delete [\_includes/selected_papers.liquid](_includes/selected_papers.liquid)
- delete [\_plugins/google-scholar-citations.rb](_plugins/google-scholar-citations.rb)
- delete [\_plugins/hide-custom-bibtex.rb](_plugins/hide-custom-bibtex.rb)
- delete [\_plugins/inspirehep-citations.rb](_plugins/inspirehep-citations.rb)
- remove the `jekyll-scholar` gem from the [Gemfile](Gemfile) and the `plugins` section in [\_config.yml](_config.yml)
### Removing the repositories page
To remove the repositories, you can:
- delete the repositories page [\_pages/repositories.md](_pages/repositories.md)
- delete [\_includes/repository/](_includes/repository/) directory
### You can also remove pages through commenting out front-matter blocks
For `.md` files in [\_pages](_pages/) directory, if you do not want to completely edit or delete them but save for later use, you can temporarily disable these variables. But be aware that Jekyll only recognizes front matter when it appears as uncommented. The layout, permalink, and other front-matter behavior are disabled for that file.
For example, books.md do:
```md
> What an astonishing thing a book is. It's a flat object made from a tree with flexible parts on which are imprinted lots of funny dark squiggles. But one glance at it and you're inside the mind of another person, maybe somebody dead for thousands of years. Across the millennia, an author is speaking clearly and silently inside your head, directly to you. Writing is perhaps the greatest of human inventions, binding together people who never knew each other, citizens of distant epochs. Books break the shackles of time. A book is proof that humans are capable of working magic.
>
> -- Carl Sagan, Cosmos, Part 11: The Persistence of Memory (1980)
## Books that I am reading, have read, or will read
```
## Adding Token for Lighthouse Badger
To add secrets for [lighthouse-badger](https://github.com/alshedivat/al-folio/actions/workflows/lighthouse-badger.yml), create a [personal access token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) and add it as a [secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-encrypted-secrets-for-a-repository) named `LIGHTHOUSE_BADGER_TOKEN` to your repository. The [lighthouse-badger documentation](https://github.com/MyActionWay/lighthouse-badger-workflows#lighthouse-badger-easyyml) specifies using an environment variable, but using it as a secret is more secure and appropriate for a PAT.
Also In case you face the error: "Input required and not supplied: token" in the Lighthouse Badger action, this solution resolves it.
### Personal Access Token (fine-grained) Permissions for Lighthouse Badger:
- **contents**: access: read and write
- **metadata**: access: read-only
Due to the necessary permissions (PAT and others mentioned above), it is recommended to use it as a secret rather than an environment variable.
## Customizing fonts, spacing, and more
The `_sass/` directory contains specialized SCSS files organized by feature and usage. To customize fonts, spacing, colors, and other styles, edit the relevant file based on what you're modifying:
- **Typography:** Edit `_typography.scss` to change fonts, heading styles, links, tables, and blockquotes.
- **Navigation:** Edit `_navbar.scss` to customize the navigation bar and dropdown menus.
- **Colors and themes:** Edit `_themes.scss` to change theme colors and `_variables.scss` for global variables.
- **Blog styles:** Edit `_blog.scss` to customize blog post listings, tags, and pagination.
- **Publications:** Edit `_publications.scss` to modify bibliography and publication display styles.
- **Components:** Edit `_components.scss` to customize reusable components like cards, profiles, and projects.
- **Code and utilities:** Edit `_utilities.scss` for code highlighting, forms, modals, and animations.
- **Layout:** Edit `_layout.scss` for overall page layout styles.
The easiest way to preview changes in advance is by using [Chrome dev tools](https://developer.chrome.com/docs/devtools/css) or [Firefox dev tools](https://firefox-source-docs.mozilla.org/devtools-user/). Inspect elements to see which styles apply and experiment with changes before editing the SCSS files. For more information on how to use these tools, check [Chrome](https://developer.chrome.com/docs/devtools/css) and [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html) how-tos, and [this tutorial](https://www.youtube.com/watch?v=l0sgiwJyEu4).
## Scheduled Posts
`al-folio` contains a workflow which automatically publishes all posts scheduled at a specific day, at the end of the day (23:30). By default the action is disabled, and to enable it you need to go to `.github/workflows/` and find the file called `schedule-posts.txt`. This is the workflow file. For GitHub to recognize it as one (or to enable the action), you need to rename it to `schedule-posts.yml`.
In order to use this you need to save all of your "Completed" blog posts which are scheduled to be uploaded on a specific date, in a folder named `_scheduled/` in the root directory.
> Incomplete posts should be saved in `_drafts/`
### Name Format
In this folder you need to store your file in the same format as you would in `_posts/`
> Example file name: `2024-08-26-This file will be uploaded on 26 August.md`
### Important Notes
- The scheduler uploads posts everyday at π 23:30 UTC
- It will only upload posts at 23:30 UTC of their respective scheduled days, It's not uploaded in 23:59 in case there are a lot of files as the scheduler must finish before 00:00
- It will only upload files which follow the pattern `yyyy-mm-dd-title.md`
- This means that only markdown files will be posted
- It means that any markdown which do not follow this pattern will not be posted
- The scheduler works by moving posts from the `_scheduled/` directory to `_posts/`, it will not post to folders like `_projects/` or `_news/`
- The date in the name of the file is the day that file will be uploaded on
- `2024-08-27-file1.md` will not be posted before or after 27-August-2024 (Scheduler only works for posts scheduled on the present day)
- `2025-08-27-file2.md` will be posted exactly on 27-August-2025
- `File3.md` will not be posted at all
- `2026-02-31-file4.md` is supposed to be posted on 31-February-2026, but there is no 31st in February hence this file will never be posted either
## GDPR Cookie Consent Dialog
**al-folio** includes a built-in GDPR-compliant cookie consent dialog to help you respect visitor privacy and comply with privacy regulations (GDPR, CCPA, etc.). The feature is powered by [Vanilla Cookie Consent](https://cookieconsent.orestbida.com/) and integrates with all analytics providers.
### How it works
- A consent dialog appears on the visitor's first visit to your site
- Visitors can **accept all**, **reject all**, or **customize preferences** for analytics cookies
- Analytics scripts (Google Analytics, Cronitor, Pirsch, Openpanel) are **blocked by default** and only run after explicit consent
- Google Consent Mode ensures Google services operate in privacy mode before consent is granted
- User preferences are saved in their browser and respected on subsequent visits
- The dialog is mobile-responsive and supports multiple languages
### When to use
- β
**Required** if your site serves EU visitors and uses any analytics
- β
Recommended for any website using analytics, tracking, or marketing tools
- β Not needed if your site doesn't use any analytics providers
### How to enable
1. Open `_config.yml` and locate the following line:
```yaml
enable_cookie_consent: false
```
2. Change it to:
```yaml
enable_cookie_consent: true
```
3. Rebuild your site:
```bash
docker compose down && docker compose up
# or
bundle exec jekyll serve
```
4. The consent dialog will automatically appear on your site's homepage on first visit
### Customizing the consent dialog
The consent dialog configuration and messages are defined in [`_scripts/cookie-consent-setup.js`](_scripts/cookie-consent-setup.js). You can customize:
- Dialog titles and button labels
- Cookie categories and descriptions
- Contact information links (points to `#contact` by default)
- Language translations
To modify the dialog, edit the `language.translations.en` section in `_scripts/cookie-consent-setup.js`. For example, to change the consent dialog title:
```javascript
consentModal: {
title: 'Your custom title here',
description: 'Your custom description...',
// ... other options
}
```
### Supported analytics providers
When cookie consent is enabled, these analytics providers are automatically blocked until the user consents:
- **Google Analytics (GA4)** β Uses Google Consent Mode for privacy-first operation before consent
- **Cronitor RUM** β Real User Monitoring for performance tracking
- **Pirsch Analytics** β GDPR-compliant analytics alternative
- **Openpanel Analytics** β Privacy-focused analytics platform
Each provider only collects data if:
1. It's enabled in `_config.yml` (e.g., `enable_google_analytics: true`)
2. The user has granted consent to the "analytics" category in the consent dialog
### How it integrates with analytics
When `enable_cookie_consent: true`, the template automatically:
1. Adds `type="text/plain" data-category="analytics"` to all analytics script tags
2. This tells the cookie consent library to block these scripts until consent is granted
3. Loads the consent library and initializes Google Consent Mode
4. Updates consent preferences when the user changes them in the dialog
You don't need to modify any analytics configurationβit works automatically.
### For developers
If you want to programmatically check consent status or react to consent changes, the library exposes the following:
```javascript
// Check if user has granted analytics consent
window.CookieConsent.getCategories().analytics; // returns true or false
// Listen for consent changes
window.CookieConsent.onChange(function (consentData) {
// Handle consent change
});
```
For more API details, see [Vanilla Cookie Consent documentation](https://cookieconsent.orestbida.com/).
---
## Setting up a Personal Access Token (PAT) for Google Scholar Citation Updates
> [!TIP]
> After setting up al-folio you may want to run `python3 bin/update_citations.py` to fill the `_data/citations.yml` file with your Google Scholar citation counts.
This project includes an automated workflow to update the citation counts for your publications using Google Scholar.
The workflow commits changes to `_data/citations.yml` directly to the `main` branch.
By default, the `GITHUB_TOKEN` will be used to commit the changes.
However, this token does not have permission to trigger subsequent workflows, such as the site rebuild workflow.
In order to deploy the changes from `main`, you can manually trigger the `deploy` workflow.
> [!TIP]
> To ensure that these commits can trigger further GitHub Actions workflows (such as site rebuilds), you can use a Personal Access Token (PAT) instead of the default GitHub Actions token.
> If you have set up a PAT, citation updates will trigger further workflows (such as site rebuilds) after committing changes. In order to run the action with a PAT, you need to uncomment the following lines from the workflow file (`update-citations.yml`):
>
> ```yaml
> with:
> token: ${{ secrets.PAT }}
> ```
### Why is a PAT required?
GitHub restricts the default `GITHUB_TOKEN` from triggering other workflows when a commit is made from within a workflow. Using a PAT overcomes this limitation and allows for full automation.
### How to set up the PAT
1. **Create a Personal Access Token**
- Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens).
- Click "Generate new token" (classic or fine-grained).
- Grant at least the following permissions:
- `repo` (for classic tokens if repo is private), `public_repo` (for classic tokens if repo is public) or `contents: read/write` (for fine-grained tokens)
- Save the token somewhere safe.
2. **Add the PAT as a repository secret**
- Go to your repository on GitHub.
- Navigate to `Settings` > `Secrets and variables` > `Actions` > `New repository secret`.
- Name the secret `PAT` (must match the name used in the workflow).
- Paste your PAT and save.
3. **Workflow usage**
The workflow `.github/workflows/update-citations.yml` uses this PAT to commit updates to `_data/citations.yml`.