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

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-<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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗