# Academic Pages: a Jekyll template for academic portfolios on GitHub Pages > Academic Pages is a GitHub Pages template built on Jekyll and Minimal Mistakes, aimed at researchers who want a publications list, talks and CV on a domain they control. The setup is a template copy plus a _config.yml edit, and the Docker path avoids installing Ruby locally. **academicpages/academicpages.github.io** — Github Pages template based upon HTML and Markdown for personal, portfolio-based websites. - Repository: https://github.com/academicpages/academicpages.github.io - Website: https://academicpages.github.io - Stars: 17,683 · Forks: 9,462 - Language: SCSS - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/academicpages-academicpages-github-io ## The problem Academic Pages solves for researchers Most academics need a small set of pages: a biography, a publication list, talks, teaching, and a CV file that can be linked from a grant application or an email signature. A content management system is heavier than that job needs, and a hand-written site means rebuilding the publication list every time a paper is accepted. Academic Pages targets exactly this gap. It is a GitHub Pages template, described in the README as "a GitHub Pages template for personal and professional portfolio-oriented websites", and it ships with pre-made collections for publications, talks, teaching, portfolio items and posts. The audience is narrow on purpose: PhD students, postdocs and faculty who are comfortable editing Markdown and YAML, and who would rather own a repository than rent a page builder. If you want a drag-and-drop editor or a hosted dashboard, this is the wrong layer of the stack. The repository topics list confirms the intent: academic-website, github-pages, jekyll, jekyll-theme, markdown, personal-website, portfolio-website. ## How the template turns Markdown and TSV into a site The repository is a Jekyll site, not a packaged gem theme. The top-level entries show the structure: _config.yml for site-wide settings, _data/ for structured content, and one directory per content type (_publications/, _talks/, _teaching/, _portfolio/, _posts/, _pages/). Layouts and components live in _layouts/ and _includes/, with styling in _sass/. That layout matters because it defines the update model. Because the theme is copied rather than installed as a dependency, your customizations sit in the same files as upstream changes, which the README acknowledges: synchronizing a customized copy "will probably get merge conflicts". The README also documents a second data path. The markdown_generator folder holds Jupyter notebooks and Python scripts that generate Markdown files for publications and talks from a TSV file, so a bibliography maintained in a spreadsheet can be converted into the _publications/ collection instead of being typed by hand. A talkmap.py script and talkmap.ipynb sit at the repository root, alongside talkmap/ and talkmap_out.ipynb, which suggests a separate mapping step for talk locations; the README does not describe this workflow, so treat it as undocumented until you read the notebook yourself. Client-side JavaScript is bundled through npm: package.json declares jquery and plotly.js-dist-min as dependencies and an uglify script that concatenates jQuery, the greedy-navigation plugin, _main.js and theme.js into assets/js/main.min.js. ## Install Academic Pages locally and preview it on localhost:4000 The README's getting-started path is GitHub-first: register an account, click "Use this template", name the new repository [your GitHub username].github.io, then edit _config.yml so that url and repository match that name. Files you upload to the files/ directory are served at https://[your GitHub username].github.io/files/example.pdf. Build status appears in the repository settings under the GitHub pages section. For local previews the README requires ruby-dev, bundler and nodejs. On most Linux distributions and WSL the documented command is: ```bash sudo apt install ruby-dev ruby-bundler nodejs ``` If that fails with "Unable to locate package ruby-bundler", the README says to run sudo apt update && sudo apt upgrade -y and retry. On macOS the equivalent is brew install ruby, brew install node, then gem install bundler. After the toolchain is in place, install the Ruby dependencies: ```bash bundle install ``` If bundle install fails on permissions, the README recommends installing gems locally with bundle config set --local path 'vendor/bundle' and running bundle install again; a successful run leaves a vendor folder and a .bundle folder. Then serve the site: ```bash bundle exec jekyll serve -l -H localhost ``` The server listens on localhost:4000 and rebuilds on changes to Markdown and HTML files. Changes to _config.yml or the core template require stopping and restarting Jekyll, which is the first thing that surprises people who expect a full hot-reload loop. On Linux the README notes that build-essential, gcc and make may be needed first. If you would rather not install Ruby at all, the repository ships a Dockerfile and a docker-compose.yaml. The compose file builds a service called jekyll-site, maps port 4000, mounts the repository into /usr/src/app, runs as user 1000:1000 and starts Jekyll with the command jekyll serve -H 0.0.0.0 -w --config _config.yml,_config_docker.yml. The README's invocation is: ```bash chmod -R 777 . docker compose up ``` The site should then be reachable at localhost:4000. Note that the Dockerfile pins ruby:3.2, installs bundler:2.3.26 and connection_pool:2.5.0, and runs as a non-root user. VS Code users get a third path: the .devcontainer/ configuration can be opened with F1, then DevContainer: Reopen in Container, which hosts the page on http://localhost:4000 with live updates. ## Where Academic Pages breaks down or is the wrong choice The update model is the main cost. Because you copy the template instead of depending on a versioned theme, pulling upstream fixes means rebasing or cherry-picking commits, and the README states plainly that a customized copy will probably hit merge conflicts. The documented fallback is blunt: back up your .yml and Markdown files, delete the repository, and fork again. If you have accumulated dozens of publication entries, that is a real migration, not a convenience. The README also says additional maintainers would be welcome, which is worth reading as a statement about capacity rather than a marketing line. The second constraint is the rendering pipeline. GitHub Pages builds the site for you, so you inherit its Ruby and plugin environment rather than choosing your own. Anything requiring server-side code, form handling, authentication or a database is out of scope for a static template, and the documentation does not describe rollback, staging environments or preview deployments for pull requests. The local preview caveat is easy to underestimate too: Markdown edits reload, but _config.yml edits do not, so a wrong value in site-wide configuration can look like a caching bug until you restart the server. Finally, the talkmap tooling at the repository root has no README section explaining its inputs or outputs, so if you need a talk-location map, budget time to read talkmap.py and the notebooks before assuming it works out of the box. ## Academic Pages compared with a Minimal Mistakes theme install The closest alternative is using the upstream Minimal Mistakes Jekyll theme directly, which the README identifies as the project Academic Pages was forked from and then detached from. The difference is architectural, not cosmetic. Minimal Mistakes is distributed as a theme gem, so your site keeps a short Gemfile entry and a remote_theme or theme key, and upgrading means changing a version and running bundle update. Your customizations live in your own overrides and configuration, which the theme's upgrade path expects. Academic Pages inverts that: the theme files are in your repository, so you can edit any layout or include directly, and you get academic-specific collections (publications, talks, teaching) plus the markdown_generator scripts and the Docker and DevContainer setups that Minimal Mistakes does not ship for this use case. You trade a clean upgrade path for direct control over every template file. If you plan to customize heavily and never want to rebase, the template copy is the better fit. If you want upstream fixes to arrive as a one-line version bump, the gem theme is the better fit, and you will need to build the publication and talk collections yourself. ## Maintenance, licence and the real upgrade cost The repository is not archived and the last push was on 2026-09-19, two days before this writing, so upstream is moving. Releases are infrequent and versioned: v0.9 on 2026-06-24, v0.8.4 on 2025-06-27, v0.8.3 on 2025-02-02. That cadence tells you what to expect: bug fixes and enhancements arrive as commits and occasional tagged releases, and the README asks for bug reports and feature requests through GitHub issues, with styling questions directed to GitHub discussions. Bugfix contributions require forking rather than using the template button, precisely so that you can synchronize later. On licensing, both the LICENSE file and package.json identify MIT, and the README states that the project was forked from Minimal Mistakes, which is copyright 2016 Michael Rose and released under the MIT License. MIT is permissive, but the details of attribution and redistribution are a legal question rather than an editorial one; read LICENSE.md in your copy and, if your institution has rules about third-party code in published artifacts, ask them rather than treating a template copy as automatically cleared. Practically, the maintenance burden is yours: Ruby, Bundler and Node versions drift, the Dockerfile pins ruby:3.2 and bundler:2.3.26, and a Gemfile.lock that stops resolving is the most common way a working site stops building. The README's own remedy for dependency errors is to delete Gemfile.lock and run bundle install again. ## Conclusion Adopt Academic Pages if you want a static academic site whose publications, talks and teaching pages are plain Markdown in a repository you control, and you accept that template updates arrive as merge conflicts rather than as a versioned dependency. Skip it if you need a database, server-side forms or an editorial workflow, or if you are unwilling to keep a Ruby and Bundler toolchain working for local previews. Before committing, verify three things in your copy: that url and repository in _config.yml match your [username].github.io repository, that the GitHub Pages build in repository settings succeeds on the master branch, and that your fork or template copy can be rebased onto upstream without losing your edits. ## FAQ ### How do I run Academic Pages locally? Install ruby-dev, bundler and nodejs, run bundle install, then run bundle exec jekyll serve -l -H localhost. The site is served from localhost:4000, and Markdown or HTML changes rebuild automatically while changes to _config.yml require restarting Jekyll. The README also documents a Docker path with docker compose up after chmod -R 777 . ### Is Academic Pages free to use? The repository is licensed MIT, and the README notes it was forked from the Minimal Mistakes Jekyll Theme, which is copyright 2016 Michael Rose and also MIT licensed. The template itself is hosted on GitHub Pages, so what you pay depends on your GitHub account rather than on the template. ### How do I update Academic Pages after I have customized it? The README warns that synchronizing a customized copy will probably produce merge conflicts, and suggests rebasing the changes from the template or cherry-picking the relevant commits. If you are not comfortable with the Git command line, the documented fallback is to save your .yml and Markdown files, delete the repository, and fork it again. ### Can I generate my publication list from a spreadsheet instead of writing Markdown by hand? Yes. The markdown_generator folder contains Jupyter notebooks and Python scripts that the README says generate Markdown files for publications and talks from a TSV file. The README does not document the exact column format, so you will need to read the scripts before relying on them. ### Where do I put PDFs and other files so they can be linked from my pages? Upload them to the files/ directory. The README states they will then appear at https://[your GitHub username].github.io/files/example.pdf, which is the URL you would link from a publication or CV entry. ## Sources - [academicpages/academicpages.github.io on GitHub](https://github.com/academicpages/academicpages.github.io) - [License: MIT](https://github.com/academicpages/academicpages.github.io/blob/master/LICENSE) - [Project website](https://academicpages.github.io) - [README](https://github.com/academicpages/academicpages.github.io/blob/master/README.md) - [Releases](https://github.com/academicpages/academicpages.github.io/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/academicpages-academicpages-github-io