al-folio v1.x: A Thin Jekyll Starter for Academic Websites

What al-folio is for, and who it is not for

al-folio is a Jekyll starter aimed at academics who need a personal website: a CV page, a publications list, news posts, project pages and teaching pages. The repository ships `_bibliography/`, `_books/`, `_news/`, `_pages/`, `_posts/`, `_projects/` and `_teachings/` directories, so the content model is already laid out for that kind of site rather than for a general blog.

The README is explicit that in `v1.x` al-folio is a thin starter, not a theme. That distinction is the whole story of this release line. The runtime ships as independently versioned plugin gems, so you pick up fixes by bumping a pinned version in your `Gemfile` instead of merging theme internals into your site. If you expected the classic Jekyll theme experience, where you add `remote_theme` and override a few files, this is a different arrangement.

It is the wrong tool if you want to own every layout file. The README states that plugin-owned changes should be made in the owning `al-org-dev` plugin repository, not by copying runtime assets into the starter. A site that needs a structurally different layout is fighting the design.

The plugin split: how the runtime is actually assembled

The starter repository holds content, configuration and a Gemfile. The runtime behaviour comes from gems. The README lists the bundled v1 plugin repositories: `al-folio-core` for shared layouts, includes and style/runtime primitives, `al-folio-cv` for CV rendering, `al-folio-distill` for Distill layouts, `al-folio-bootstrap-compat` as a temporary Bootstrap compatibility runtime, `al-folio-upgrade` for upgrade audit and codemods, `al-icons` for icon loading, `al-search` for search, `al-citations` for publication and citation helpers, and `al-ext-posts` for external post ingestion.

Naming follows a convention. Theme-coupled plugins use `al-folio-<feature>` repos and `al_folio_<feature>` gem or plugin ids, while reusable plugins can use `al-<feature>` or neutral naming. Featured plugins and bundled starter plugins are separate tracks, and the README says bundling requires explicit updates to `Gemfile` and `_config.yml`.

The plugin catalog lives at `_data/featured_plugins.yml` with a rendered page whose source is `_pages/plugins.md`. That page is deliberately kept out of the navbar with `nav: false` so the demo site's chrome stays unchanged. The practical consequence is that your upgrade surface is a list of gem versions, and your customisation surface is content plus configuration, not the layouts.

Installing al-folio and rendering the site locally

The README points to `docs/INSTALL.md` for installation and deployment details, so the repository treats that file as the authority. The quickest local path shown in the repository is Docker Compose, which uses a prebuilt image from Docker Hub.

services:
  jekyll:
    image: amirpourmand/al-folio:latest
    command: /srv/jekyll/bin/entry_point.sh
    ports:
      - 8080:8080
      - 35729:35729
    volumes:
      - .:/srv/jekyll
    environment:
      - JEKYLL_ENV=development

Run `docker compose up` from the repository root. The site is served on port 8080 and LiveReload on port 35729, with the working directory bind-mounted at `/srv/jekyll`. The Compose file notes that if you hit a `Permission denied @ rb_sysopen - /srv/jekyll/.jekyll-cache/.gitignore` error, you should fill in the build args with the output of `id -g`, `id -gn`, `id -u` and `echo $USER`.

Before any of that, the README's first instruction is not a command. It is to click "Use this template" rather than fork, because a fork keeps a link to the upstream repository and makes it easy to accidentally submit personal site changes as pull requests. If you already forked, the README says to work on a dedicated branch such as `my-site-updates` and never open pull requests against `alshedivat/al-folio` unless you intend to contribute an improvement.

The Dockerfile itself is based on `ruby:slim` and installs build tools, ImageMagick, Node.js and Python, then sets `EXECJS_RUNTIME=Node` and `JEKYLL_ENV=production`. That is a heavier image than a plain Jekyll container, which is the cost of the citation and notebook tooling.

Upgrades are gem bumps, and that is a real constraint

The README frames the plugin split as the upgrade story: you bump a pinned version in your `Gemfile` instead of merging theme internals. That is cleaner than a fork-and-merge workflow, but it moves the risk. A gem bump can change shared layouts that your content depends on, and the starter's own files are not the thing being versioned.

The repository ships `al-folio-upgrade` for exactly this, described as a v1 upgrade audit, report and codemod tool. The README does not document a rollback path if a bump breaks rendering, and it does not spell out which gem versions are compatible with which starter revisions beyond the `Gemfile` and `Gemfile.lock` in the repository. Treat `Gemfile.lock` as the record of what you actually run, and check it before and after a bump.

There is a second constraint. `al-folio-bootstrap-compat` is described as a temporary Bootstrap compatibility runtime. Temporary means it is expected to go away, and anything you build against it inherits that expectation. The README does not say when it will be removed or what replaces it.

Writing, citations and the Python side of the build

Posts live in `_posts/`, news items in `_news/`, projects in `_projects/` and teaching material in `_teachings/`. Publications and citations are handled by `al-citations` against the `_bibliography/` directory, and external posts are ingested by `al-ext-posts`.

The Docker image installs Python and `nbconvert`, which is the signal that notebook conversion is part of the intended workflow rather than an add-on. The repository also carries a `requirements.txt` listing `nbconvert`, `pyyaml`, `rendercv[full]` and `scholarly`. Two of those matter for what you can build: `rendercv` renders a CV from structured data, and `scholarly` pulls publication data from Google Scholar.

That dependency list is also a limitation. `scholarly` scraping behaviour depends on a third party's page structure, and the README does not describe a fallback when it fails. If your publication list must be authoritative and stable, plan to maintain the bibliography files directly rather than relying on automated retrieval.

How al-folio compares to a plain Jekyll theme

The alternative most people are weighing is a conventional Jekyll theme installed through `remote_theme` or a gem, where the theme's layouts live in the theme repository and you override individual files in your own site. The difference in approach is ownership. With a conventional theme, upgrading means pulling new theme code and resolving conflicts in the files you overrode. With al-folio v1.x, upgrading means changing a version string and letting the plugin gems change underneath you.

That trade favours al-folio when your customisation is content and configuration, and it favours a conventional theme when your customisation is structural. The README's own instruction not to copy runtime assets into the starter makes that boundary explicit rather than leaving it to judgement.

The other comparison point is a hosted academic profile service. Those remove the build entirely but also remove control over markup, and they do not give you a Jekyll site you can deploy anywhere. al-folio keeps the site in your repository and the build in your hands, which is the reason the plugin boundary exists at all.

Licence, testing and what the repository asks of contributors

al-folio is MIT licensed, which permits reuse and modification with the licence and copyright notice retained. That applies to the starter repository. The README does not state the licence of each plugin gem in the `al-org-dev` organisation, so if you redistribute a built site you should check the licence of each gem you bundle rather than assuming MIT covers the whole runtime.

The repository carries a test setup that is worth knowing about even if you never contribute. `package.json` defines `lint:prettier` for Prettier checks, `lint:style-contract` for a style contract test, and `test:visual` for Playwright visual tests, with `test:visual:update` to refresh snapshots. There is also a `.pre-commit-config.yaml` and a `test/` directory. For a site you maintain yourself, the style contract test is the interesting one: it enforces a contract on styles, which is the kind of check that catches drift after a gem bump. The README does not document how to run these against a copied site rather than the starter itself.

Editorial conclusion

Adopt al-folio if you want a Jekyll-based academic site with a CV page, a bibliography and GitHub Pages deployment, and you are willing to read docs/BOUNDARIES.md before touching anything under _layouts. Do not adopt it if you want a single repository you can freely restructure, because v1.x pushes runtime changes into the al-org-dev plugin repositories. Before you commit, run the upgrade audit command and confirm which gem versions your Gemfile pins.

Frequently asked questions

Official sources

1. alshedivat/al-folio on GitHub
2. License: MIT
3. Project website
4. README
5. Releases