al-folio

al-folio is a free, open-source Jekyll starter for academic websites that generates a full homepage, publications list, CV, blog, and lab pages from data files and BibTeX.

What is al-folio?

al-folio is a simple, clean, and responsive Jekyll starter for academic websites, maintained by Maruan Al-Dhedivat and a team including Rohan Deb Sarkar, Amir Pourmand, and George. In v1.x it is a thin starter rather than a monolithic theme: runtime features ship as independently versioned Ruby gem plugins, so sites pick up fixes by bumping a pinned version in the Gemfile instead of merging theme internals. It takes content in the form of YAML data files, Markdown posts, and BibTeX bibliographies, and outputs a static site ready to deploy on GitHub Pages or any static host.

Key Features

• Thin-starter plugin ecosystem — Runtime features are split across versioned plugin gems like al-folio-core, al-folio-cv, al-search, and al-citations, letting you add or remove features by editing the Gemfile.
• Publications from BibTeX — A publications page is generated automatically from your bibliography using jekyll-scholar, including citation counts and altmetric/dimensions badges via al-citations.
• Content-driven CV — The CV renders from a single cv.yml or resume.json file using the al-folio-cv plugin.
• Distill-style posts — Blog posts can use the distill.pub layout for interactive, visually clean long-form content.
• Math, TikZ, and charts — Posts support MathJax, TikZ diagrams, mermaid, and plotly charts through the al_math and al_charts plugins.
• Search and navigation — Full-text site search triggered with ctrl+k is provided by al-search, plus light/dark mode following the visitor's system preference with a manual toggle.
• Integrations ready to configure — Analytics (Google, Cronitor, Pirsch, Openpanel, Cloudflare, Simple), Giscus/Disqus comments, GDPR cookie consent, and newsletter signup are bundled as plugins you switch on by adding keys in _config.yml.
• Open Graph and SEO — Includes Open Graph/schema.org previews, a responsive image pipeline, an Atom feed at /feed.xml, and a Google Scholar citation-refresh workflow.

Who should use al-folio?

• PhD students and postdocs — stand up a personal academic homepage with publications, CV, and blog in a single afternoon.
• Professors and faculty — create lab pages and course websites using the bundled collections for news, projects, books, and teachings.
• Researchers who write regularly — publish distill-style posts, code explainers, and math-heavy content with Jupyter notebook support.
• Conference and workshop organizers — build a conference website from the same starter, as the page notes it's used for conferences and meetups.

What can you do with al-folio?

• Create a publications list from BibTeX — paste your bibliography and the site generates a searchable publications page with citation badges.
• Build a lab or research group page — use the people page populated from _data, plus projects and news collections.
• Maintain a blog with rich content — write posts with math, TikZ diagrams, charts, image galleries, video and audio embeds, and syntax-highlighted code.
• Deploy on GitHub Pages — follow the quick start to deploy automatically via the provided GitHub Actions workflow.

How does al-folio work?

al-folio is installed by clicking "Use this template" on GitHub rather than forking, which prevents accidental pull requests. Setup steps are in docs/QUICKSTART.md — you edit _config.yml, data files, and posts, then commit; a GitHub Actions workflow builds and deploys the static site. For existing customized forks, the recommended path is an agent-assisted migration using the al-folio v1 migration skill and the al_folio_upgrade audit.

Pricing

al-folio is free and open source under the MIT License.

FAQ

Is al-folio free?

Yes, al-folio is released under the MIT License, so it's free to use, modify, and redistribute. You only pay for hosting if you choose a non-GitHub-Pages provider.

Should I fork al-folio or use the template?

Use the "Use this template" button on GitHub. Forking keeps a link to the main repository and risks accidentally pushing your personal changes to alshedivat/al-folio as pull requests. If you already forked, work on a dedicated branch and never create PRs to the main repo.

What pages does al-folio include out of the box?

The starter ships with home, publications, CV, projects, people, repositories, and blog pages. Publications are generated from BibTeX, the CV from cv.yml or resume.json, and people from _data — content is driven by data files rather than template edits.

Can I add comments or analytics to my site?

Yes. Comments via Giscus or Disqus, analytics via Google, Cronitor, Pirsch, Openpanel, Cloudflare, or Simple, and GDPR cookie consent are bundled as plugins. Most are "setup" rows, meaning you must supply your own key or ID in _config.yml before they render anything.

Does al-folio support dark mode?

The theme follows the visitor's system preference and offers a sun/moon toggle in the navbar that persists across visits. Both light and dark modes are included in the starter's al-folio-core plugin.