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:
Make changes on a dedicated branch (e.g., my-site-updates)
When pushing changes, always verify you're pushing to your own repository, not the main al-folio repository
Never create pull requests to alshedivat/al-folio unless you're intentionally contributing improvements that benefit all users
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-<feature> repos and al_folio_<feature> gem/plugin ids.
Reusable plugins can use al-<feature> or neutral naming.
Featured plugins and bundled starter plugins are different tracks. Bundling requires explicit updates to Gemfile and _config.yml.
Plugin-owned changes should be made in the owning al-org-dev plugin repository, not by copying runtime assets into this starter.
The bundled v1 plugin repos are:
al-folio-core: shared layouts, includes, style/runtime primitives, and upgrade contracts
al-folio v1.x is designed for agent-assisted setup and migration. Agents should read AGENTS.md first, then use docs/BOUNDARIES.md to route changes to the starter or the owning plugin repo.
For existing customized forks, the recommended migration path is to ask an agent to use the al-folio v1 migration skill. The skill walks through creating a disposable migration branch, bringing site-owned content/config/data onto the v1 starter contract, running al_folio_upgrade, auditing local overrides, and validating the build. This is preferred over a manual file-by-file upgrade because v1 runtime ownership moved into plugins and local overrides need explicit drift tracking.
The canonical skills live in .agents/skills/. They are also exposed through .codex/skills/ and .claude/skills/ symlinks for agents that discover skills from tool-specific directories.
"Use the al-folio bootstrap skill to configure my new site."
"Use the al-folio v1 migration skill to migrate this customized fork and run the override audit."
Claude
Claude should start from CLAUDE.md, which imports AGENTS.md. For setup or migration tasks, use the matching skill from .claude/skills/, which points to the canonical .agents/skills/ directory.
Copilot And Other Agents
Copilot should follow .github/copilot-instructions.md and the specialized agents in .github/agents/. Other agents should follow the same rule: keep starter work in this repo, route runtime behavior to the owning al-org-dev plugin, and run bundle exec al-folio upgrade overrides audit whenever local overrides are added or retained.
Documentation
Comprehensive guides for all aspects of your al-folio website:
Everything below ships with the starter. Rows marked setup render nothing until you supply a key, ID or credential — bundling a plugin is not the same as switching the feature on. Each feature is owned by a versioned plugin — see docs/BOUNDARIES.md for the full ownership table, and Plugin Ecosystem for how to add or remove one.
Also included: Open Graph and schema.org previews, an Atom feed at /feed.xml, related posts, tabbed content, typograms, responsive image generation, and a Google Scholar citation-refresh workflow.
Light and dark mode
The theme follows the visitor's system preference and can be toggled with the sun/moon control in the navbar. The choice persists across visits.
The pages you get out of the box
Publications are generated from your BibTeX bibliography, the CV from a single cv.yml or resume.json, and the people page from _data. Everything is content-driven — you edit data files, not templates.
Projects are one of four Jekyll collections the starter ships (news, projects, books, teachings). You can add your own for courses, talks, or anything else — see Adding Collections.
Writing
Posts support the distill.pub layout, MathJax and TikZ, syntax-highlighted code, Jupyter notebooks, charts, image galleries, video and audio embeds.
GitHub repositories and stats
The /repositories/ page renders repository and profile cards via github-stats-extended. Profile trophies via github-profile-trophy are supported but off by default, because that project's free public instance is currently disabled — see docs/CUSTOMIZE.md to self-host and re-enable.
Academics around the world use al-folio for their homepages, blogs, and lab pages, as well as webpages for courses, workshops, conferences, meetups, and more.
Want your site listed? Post a request in the Showcase category of GitHub Discussions — we review and add entries periodically. Please do not open a pull request for this.
For frequently asked questions, please refer to docs/FAQ.md.
Contributing
Contributions to al-folio are very welcome! Before you get started, please take a look at the guidelines.
If you would like to improve documentation or fix a minor inconsistency or bug, please feel free to send a PR directly to main. For more complex issues/bugs or feature requests, please open an issue using the appropriate template.
al-folio is available as open source under the terms of the MIT License.
Originally, al-folio was based on the *folio theme (published by Lia Bogoev and under the MIT license). Since then, it got a full re-write of the styles and many additional cool features.
al-folio (alshedivat/al-folio)
Choose a tag and it will appear here. With no tags selected, all catalog projects are shown.
Searching Database…
Choose a tag and it will appear here. With no tags selected, all catalog projects are shown.
al-folio 是一个开源的 Jekyll 起始模板，用来搭建简洁、快速、响应式的学术网站：个人主页、博客、简历，以及实验室或课程页面。