Guide · Open source
How to use al-folio: set up an academic Jekyll site
Updated · written with AI from the project's own documentation and checked against our catalogue data
al-folio is a free, MIT-licensed Jekyll starter for building a personal academic website with a clean, responsive layout. It is aimed at academics and researchers who are comfortable with configuration files, Git and GitHub. After this guide you will know how to create your own copy of the project, where the setup and customization documentation lives, and what to watch for when you update the site.
al-folioalshedivat/al-folio · ★ 16.3k · MIT Install options & downloads Quick start
- 1Confirm the fit. Make sure you are comfortable with Jekyll, Git and GitHub before you start, since the setup has no no-code path.
- 2Create your copy. Click Use this template on the al-folio repository to make an independent copy, rather than forking it.
- 3Clone locally. Run git clone https://github.com/alshedivat/al-folio, or clone your own copy, to work on the site on your machine.
- 4Follow the install guide. Use docs/INSTALL.md to build the site and set up deployment, including GitHub Pages.
- 5Customize. Edit content and settings following docs/CUSTOMIZE.md, and keep runtime changes in plugins rather than copied files.
- 6Update through the Gemfile. Bump the pinned plugin version in your Gemfile to receive fixes and features in v1.x.
Check whether al-folio fits your setup
al-folio is built on Jekyll, a static site generator, so you create your site from the template and then edit its content and settings. Setup involves Jekyll, Ruby gems and Git. The README describes agent-assisted setup but does not describe a no-code path, so it is not a drop-in website builder.
- You need Git and a GitHub account for the recommended workflow and for GitHub Pages hosting.
- You should be willing to edit configuration files.
- If you already have a customized fork, the README recommends a dedicated migration path rather than a simple update.
Create your own copy with Use this template
The README recommends clicking "Use this template" rather than forking. This creates a clean copy that is independent from the main al-folio repository, so changes to your site are not accidentally submitted to al-folio as pull requests.
If you have already forked, you can still work with the fork. Make changes on a dedicated branch such as my-site-updates, always verify you are pushing to your own repository, and do not open pull requests to alshedivat/al-folio unless you are intentionally contributing improvements.
Clone the repository
If you want a local copy to build and edit, the README lists the clone command below. Replace the URL with your own repository if you created the site from the template.
git clone https://github.com/alshedivat/al-folioInstall and deploy the site
Installation and deployment details are in docs/INSTALL.md in the repository. The README points there rather than listing every step, so follow that document for the build and GitHub Pages setup. For a shorter route, the README also links to docs/QUICKSTART.md.
Customize your content and settings
Customization details are in docs/CUSTOMIZE.md. The README also notes that the bundled demo pages are configured in the repository, for example the plugin catalog page sits outside the navbar through nav: false, so you reach it through its links rather than the menu.
In v1.x, al-folio is a thin starter rather than a full theme. Runtime features come from separately versioned Ruby gem plugins, and you pick up fixes by bumping a pinned version in your Gemfile instead of merging theme internals into your site. Plugin-owned changes belong in the owning al-org-dev plugin repository, not in copies of runtime assets in your starter.
- al-folio-core: shared layouts, includes, style and runtime primitives
- al-folio-cv: CV rendering
- al-folio-distill: Distill layouts and runtime assets
- al-search: search runtime
- al-citations: publication and citation helpers
- al-analytics, al-comments, al-math, al-charts and al-newsletter: feature-specific behavior
Add plugins with care
Featured plugins and bundled starter plugins are different tracks. Bundling a plugin requires explicit updates to the Gemfile and _config.yml, so check which gems a feature needs before you rely on it. The plugin catalog is in _data/featured_plugins.yml and is rendered on the project's plugins page.
Use AI agents for setup and migration
The README says v1.x is designed for agent-assisted setup and migration. Agents should read AGENTS.md first, then docs/BOUNDARIES.md to route changes to the starter or the owning plugin repository. For customized forks, the README recommends asking an agent to use the al-folio v1 migration skill, because it covers creating a disposable migration branch, running al_folio_upgrade and auditing local overrides.
- Codex: start with the al-folio bootstrap skill to configure a new site.
- Claude: start from CLAUDE.md, which imports the agent instructions.
What people use it for
- A researcher publishing a personal homepage with a clean, responsive layout
- An academic hosting a static site on GitHub Pages
- A lab member maintaining a site through Git commits and configuration files
- A scholar adding a CV page through the al-folio-cv plugin
Frequently asked questions
Is al-folio free to use?
al-folio is released under the MIT licence, as listed on the project page. The README does not describe any paid tier, so the project as documented is free to use and modify under that licence.
Do I need to know Ruby to use al-folio?
The setup involves Jekyll and Ruby gems, and the README describes agent-assisted setup rather than a no-code path. You should be comfortable editing configuration files and following install instructions.
Should I fork al-folio or use this template?
The README recommends Use this template, which creates a copy independent from the main repository. Forking keeps a link to the main repo, which makes it easy to submit personal site changes as contributions by accident.
Can I host al-folio on GitHub Pages?
Yes. The README lists GitHub Pages hosting as a reason to have a GitHub account, and deployment details are in docs/INSTALL.md.
How do I update al-folio in v1.x?
In v1.x, runtime features ship as plugin gems. You update by bumping a pinned version in your Gemfile instead of merging theme internals. For an existing customized fork, the README recommends the migration skill rather than a simple update.
What are the alternatives to al-folio?
The project lists Jekyll Minimal Mistakes, Hugo Academic (Wowchemy), Jekyll Chirpy and Academic Pages as comparable projects. Choose based on whether you want Jekyll, which framework you know, and how much configuration you are willing to do.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
al-folio suits academics and researchers who want a clean, responsive personal site on GitHub Pages and are comfortable with Git and Jekyll configuration. If you want a no-code website builder, or you have a heavily customized fork that needs migrating, pick a different route or plan for the migration path the README describes.
Install options & downloads