alshedivat /al-folio
A beautiful, simple, clean, and responsive Jekyll theme for academics
★ 16,350⑂ 13,034👁 37⑃ 2,072● 733▤ 46
+4
日增长
+51
周增长
+97
月增长
16,350
stars
13,034
forks
37
watchers
2,072
prs
733
issues
46
releases
README
al-folio
A simple, clean, and responsive Jekyll starter for academic websites.
_In v1.x, al-folio is a thin starter, not a theme: the runtime ships as independently versioned plugin gems, so you pick up fixes and features by bumping a pinned version in your Gemfile instead of merging theme internals into your site._
---
Getting started
⚠️ Important: Use "Use this template" (not fork)
When creating your own website with al-folio, you have two options:
- ✅ Recommended: Click "Use this template" – This creates a clean copy that is independent from the main al-folio repository. Changes you make to your site won't be accidentally submitted to al-folio as pull requests.
- ❌ Not recommended: Forking the repository – This keeps a link to the main al-folio repo, making it easy to accidentally submit your personal site changes as contributions to our project.
If you already forked: Don't worry! You can still work with your fork normally. Just make sure to:
1. Make changes on a dedicated branch (e.g., my-site-updates)
2. When pushing changes, always verify you're pushing to your own repository, not the main al-folio repository
3. Never create pull requests to alshedivat/al-folio unless you're intentionally contributing improvements that benefit all users
For quick setup, see docs/QUICKSTART.md.
Want to learn more about Jekyll? Check out this tutorial. Why Jekyll? Read Andrej Karpathy's blog post! Why write a blog? Read Rachel Thomas blog post.
Table Of Contents
- al-folio
- Getting started
- Table Of Contents
- Installing and Deploying
- Customizing
- Plugin Ecosystem
- Using AI Agents
- Codex
- Claude
- Copilot And Other Agents
- Documentation
- Features
- Light and dark mode
- The pages you get out of the box
- Writing
- GitHub repositories and stats
- User community
- Lighthouse PageSpeed Insights
- Desktop
- Mobile
- FAQ
- Contributing
- Code quality checks
- Maintainers
- All Contributors
- Star History
- License
Installing and Deploying
For installation and deployment details please refer to docs/INSTALL.md.
Customizing
For customization details please refer to docs/CUSTOMIZE.md.
Plugin Ecosystem
al-folio is a thin starter in v1.x. Runtime features are plugin-owned and published as Ruby gems.
- Ownership boundaries: docs/BOUNDARIES.md
- Plugin catalog metadata: _data/featured_plugins.yml
- Rendered plugin catalog: alshedivat.github.io/al-folio/plugins/
- Plugin catalog page source: _pages/plugins.md
The catalog page is deliberately kept out of the navbar (nav: false) so the demo site's chrome stays unchanged; reach it through the links above.
Naming convention:
- Theme-coupled plugins use al-folio- repos and al_folio_ gem/plugin ids.
- Reusable plugins can use al- or neutral naming.
Featured plugins and bundled starter plugins are different tracks. Bundling requires explicit updates to Gemfile and \_config.yml.
Plugin-owneTop issues
#3706[Bug] GitHub Actions deployment fails on Ubuntu 26.04 due to unavailable Ruby 3.3.58 comments · 2026-10-24#2167[Feature Request] automatically generate pulications in the CV from .bib file6 comments · 2024-02-07#3629using github-readme-stats-action and github-stats-extended5 comments · 2026-05-28#2273Adding secondary chapter navigation on left side like just-the-docs jekyll theme 5 comments · 2024-03-13#2531Allow the Table of Contents to be expanded to show subsections and collapsed to hide subsections.3 comments · 2024-06-29#1264Sort publication by abbr property, e.g., journal paper, conf paper, book, and so on3 comments · 2023-03-16#2087Implement `axe` accessibility suggestions2 comments · 2024-01-16#3700Fresh sites get a high-severity Dependabot alert: css_parser < 3.0.0 pinned by jekyll-3rd-party-libraries1 comments · 2026-09-03
Discussions
#3710How to upgrade from pre-v1.0 version when I don't recall if fork or template install was used1 comments · 2026-11-10#3701How to tell which version of al-folio am I using?2 comments · 2026-09-07#3699Massively Speeding up LLM inference with Speculative Diffusion Decoding | Ferdinando (Nando) Fioretto1 comments · 2026-08-15#3691CV Layout: Stray bullet point and layout misalignment in date/location column1 comments · 2026-07-30#3650How to change color3 comments · 2026-06-20#3643Adding new sections to CV when using rendercv0 comments · 2026-06-10#3639Constrained Discrete Diffusion for Language, Chemistry, and Code | Ferdinando (Nando) Fioretto0 comments · 2026-06-05#3637Unexpected popup "https://polyfill.io/" when using an older al-folio template;1 comments · 2026-06-02
Latest release
al-folio v1.2 v1.2 2026-08-09v1.2 is a feature release: three new plugins, two dead third-party services retired, and a batch of fixes for things that were failing silently — a script 404, a favicon 404, a flickering theme switch. As in v1.1, most of the change is in the gems rather than in this repo. bundle update on its own will not upgrade you. The Gemfile pins every plugin to an exact version, and Bundler honours the pin already in _your_ Gemfile — so a v1.1 site runs bundle update and stays exactly where it is, with no error. You must edit the pins first — see Upgrading at the bottom. | gem | v1.1