academic-site-template — Next.js Portfolio Template

SHA-256: 549355fcaaee191aa401bc74be413568a4e7c50ec1b58588076221fedfe116dd

2026-10-14T23:54:55.416Z

# Academic Site Template

A personal website for researchers, PhD students and academics: publications with a topic graph,
a blog, a CV/resume built from the same data, and a site that search engines and LLMs can read.
Built with Next.js 16, React 19 and Bootstrap. Everything you write goes in one folder, `content/`,
which `npm run setup` creates for you from [`examples/content/`](examples/content). The template
itself never ships a `content/` folder, so updates to the site code can't conflict with yours.

[![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github&logoColor=white)](https://github.com/kunpai/academic-site-template/generate)
[![Deploy with Vercel](https://img.shields.io/badge/Deploy_with_Vercel-000000?style=for-the-badge&logo=vercel&logoColor=white)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fkunpai%2Facademic-site-template)
[![Live demo](https://img.shields.io/badge/Live_demo-2f6fed?style=for-the-badge&logo=googlechrome&logoColor=white)](https://academic-site-template.vercel.app)

[![The template's homepage in light and dark mode, on desktop and mobile](docs/images/hero.png)](https://academic-site-template.vercel.app)

The demo at [academic-site-template.vercel.app](https://academic-site-template.vercel.app) is
built from this repository with the example content for the fictional Jane Doe.

## Updates without merge conflicts

Your content lives in your own `content/` folder, and the template only ships site code, so taking
a new release is one command. This is a real run on a site made with **Use this template**:

![npm run update merging 24 changed template files into a customised site with 0 conflicts](docs/images/update.gif)

See [Getting updates](#getting-updates) for how it works.

## Features

- **Everything personal lives in `content/`**: config, data (JSON), about page, blog posts.
  Setup creates it from the example; photos and PDFs go in `public/`.
- **Sections you can switch off.** Turning off `projects`, `blogs` and so on removes the page (it
  returns 404), its nav link, its homepage block, and its entries in the sitemap, RSS and
  `llms.txt`.
- **Publications** with tabs by type, a topic graph built from your tags, BibTeX, and your name
  highlighted in author lists.
- **Blog** in Markdown (GitHub-flavoured, raw HTML allowed), with reading time and an RSS feed.
- **CV and resume PDFs** generated with LaTeX from the same data. A GitHub Action rebuilds them
  when you push.
- **Readable by search engines and LLMs:** JSON-LD, a sitemap, and `llms.txt` / `llms-full.txt`.
- **Checked content:** JSON Schemas give editor autocomplete, and `npm run validate` runs before
  every build.
- Light and dark mode, a configurable accent colour and heading font.
- Optional link pages for posters and talks (`linktree`, off by default).

## Compared to al-folio, academicpages and HugoBlox

[al-folio](https://github.com/alshedivat/al-folio),
[academicpages](https://github.com/academicpages/academicpages.github.io) and
[HugoBlox](https://github.com/HugoBlox/hugo-theme-academic-cv) (formerly Wowchemy) are the most
popular academic site templates. All three are mature and free to host. This template makes
different trade-offs:

| | This template | al-folio | academicpages | HugoBlox |
|---|---|---|---|---|
| **Stack** | Next.js 16 (React 19), Node | Jekyll (Ruby) | Jekyll (Ruby), based on Minimal Mistakes | Hugo (Go), Tailwind CSS |
| **Your content** | One folder, `content/`, checked against JSON Schemas | Spread across `_pages/`, `_posts/`, `_bibliography/`, `_config.yml` | Spread across `_pages/`, `_publications/`, `_talks/`, `_config.yml` | Markdown in `content/`, plus `config/_default/*.yaml` and `data/authors/` |
| **Updating** | `npm run update` merges the new template; only site code changes, so your content never conflicts | Merge upstream; files you customised can conflict | Fork; no separate update path | `npx hugoblox@latest upgrade`, which applies migrations automatically |
| **Publications** | JSON with a BibTeX entry each, plus an interactive topic graph | A BibTeX file, rendered with jekyll-scholar | One Markdown file per paper (scripts can generate them from TSV/BibTeX) | A folder per paper (`index.md` + `cite.bib`); a CLI imports BibTeX |
| **CV** | CV and short resume compiled to PDF with LaTeX from the same data, locally or by a GitHub Action | CV page from JSON Resume or YAML; you supply the PDF | CV page in Markdown; you supply the PDF | CV page built from a YAML profile; you supply the PDF |
| **Deploy target** | Vercel (or any Next.js host) | GitHub Pages | GitHub Pages | Netlify, GitHub Pages, Vercel, Cloudflare Pages |

Choose al-folio or academicpages if you want Jekyll and GitHub Pages, and HugoBlox if you want
Hugo and its large library of page blocks. Choose this one if you'd rather work in React, keep
your content cleanly separated, and have your CV PDF built from the same data as the site.

## Quickstart

1. Click **Use this template** on GitHub (or clone the repo), then:
   ```bash
   npm install
   npm run setup     # creates content/ from examples/ and asks for your name, links, sections
   npm run dev       # http://localhost:3000
   ```
2. Replace the example entries in `content/data/*.json` with yours. See
   [docs/CONTENT.md](docs/CONTENT.md) for every field.
3. Deploy: import the repository in [Vercel](https://vercel.com). The default Next.js settings
   work as they are.

Until `content/` exists, `npm run dev` and `npm run build` use the example site in `examples/`.
So a fresh clone, or the Deploy button above, shows a working demo straight away.

## What lives where

`content/` isn't in this repository: `npm run setup` creates it by copying
[`examples/content/`](examples/content), the fictional Jane Doe site in the demo. Browse that folder
to see what goes where.

| Path | What it is |
|---|---|
| `content/config.json` | Name, links, SEO, feature flags, theme, UI labels |
| `content/data/*.json` | Publications, education, experience, projects, skills, awards, news, talks, service |
| `content/about.md` | The About page |
| `content/blogs/*.md` | Blog posts (front matter: `title`, `date`, `tags`, `authors`, `image`) |
| `public/` | Your photo, images, and CV/resume PDFs, served as-is |
| `examples/` | The starter content that `npm run setup` copies |
| `schemas/` | JSON Schemas for everything in `content/` |
| `components/`, `pages/`, `lib/`, `styles/`, `scripts/` | Site code |

Your editor (VS Code, via `.vscode/settings.json`) autocompletes and checks `content/` files
against `schemas/`.

## Customising

**Sections.** Set `features.<name>` to `false` in `content/config.json`:

```json
"features": { "projects": false, "blogs": true, "talks": false }
```

All sections are on by default except `linktree`. The full table is in
[docs/CONTENT.md](docs/CONTENT.md#feature-flags).

**Look.** Pick any Google Fonts family for headings, and optionally an accent colour:

```json
"theme": { "headingFont": "Audiowide", "accentColor": "#0d6efd", "gradientStart": "#0d6efd", "gradientEnd": "#00d2ff" }
```

Without colours the site uses Bootstrap's default palette. Setting `gradientStart` and
`gradientEnd` adds a gradient to your name in the hero.

**Wording.** Button and heading text can be overridden under `labels`, for example
`"labels": { "resumeButton": "Download CV" }`.

**Homepage.** Work and project entries appear on the homepage unless they set
`"show_on_homepage": false`. The full pages always list everything.

## CV and resume

```bash
python3 scripts/generate_resumes.py   # needs a LaTeX install (MacTeX, TeX Live)
```

This writes the PDFs named by `resume` and `resume_short` in your config into `public/`. Entries
opt in or out with `show_in_resume` and `show_in_resume_short`. On GitHub, the **Build Resumes**
workflow does the same on every push that changes `content/`.

## Scripts

| Command | What it does |
|---|---|
| `npm run setup` | First-time setup and identity wizard |
| `npm run dev` | Development server (regenerates `llms.txt` and RSS first) |
| `npm run validate` | Check `content/` against the schemas |
| `npm run build` | Validate, generate `llms.txt`/RSS, build, write the sitemap |
| `npm run update` | Merge the latest template into your site ([details](#getting-updates)) |
| `npm run indexnow` | After a deploy, tell Bing and others about your pages |

**Environment variables:** none are required. `SITE_URL` optionally overrides `siteUrl` for the
sitemap.

## Getting updates

Your content lives in `content/` and `public/`, and template updates only touch site code. To
pull the latest version, commit your work and run:

```bash
npm run update
```

This fetches the template and merges it. You only get conflicts in site files you edited yourself
(say, a component you customised), never in your content. [CHANGELOG.md](CHANGELOG.md) lists what
each release changes and anything you need to do.

Why a script: **Use this template** gives your repository fresh history with no commit in common
with the template, so a plain `git merge` would conflict on every file the template changed. Each
release carries a `.template-version` stamp. On the first update, the script uses it to find the
version you started from and links the two histories, so later merges are ordinary merges.

## Show your site

Built something with this template? Share it in the
[Show your site](https://github.com/kunpai/academic-site-template/discussions/1) discussion.
Questions go in [Discussions](https://github.com/kunpai/academic-site-template/discussions), and bugs in
[Issues](https://github.com/kunpai/academic-site-template/issues).

## Credits

<!-- credits:start -->
This template grew out of [Kunal Pai's website](https://www.kunpai.space), which he first built
with help from [Parth Shah](https://helloparthshah.vercel.app/) and
[Harshil Patel](https://harshilpatel.vercel.app/). All three of their sites are built on it.
<!-- credits:end -->

## License

The code is under the [MIT License](LICENSE). The example content in `examples/` is yours to
replace.