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