Academic Website Template

A simple, config-driven academic website template that generates HTML from content and site config (no HTML editing needed).

📢 Latest (v1.5.0): Template/personal branch separation — master is now a clean, one-click GitHub Template with fictitious demo data; personal content lives in a separate branch. Scholar sync workflow updated to target the personal branch. See CHANGELOG.md for details.

🎯 Features

Academic-focused features:

TL;DR popovers — hover (desktop) / tap-to-expand (mobile) for quick skimming
Publication-first layout — auto-generated publication list from config
Mobile-friendly — responsive reading, back-to-top
Config-driven content — no HTML editing; update content.json / site.yaml
Optional AI agent skills — Cursor / Windsurf skills for adding papers and deploying

📖 Want more details? Detailed guide · examples and tips.

🚀 Quick Start

(Optional) Step 0: Let an AI agent set things up

If you use an AI-enabled editor such as Cursor, Antigravity, or Codex, you can let an agent do most of the initial setup for you:

Open this repo in your editor and enable its AI agent.
Ask the agent to use the init-template-setup skill for this project.
Answer its questions about your name, affiliation, SEO, deployment choice, and favicon/logo.
The agent will read README.md, config/README.md, docs/FAVICON_SETUP.md, and the intro blog post, then edit config/site.yaml and config/content.json for you following the docs.

You can still follow the manual steps below, but the AI-assisted flow is often faster for first-time users.

Step 1: Create Your Repository

Recommended: Click the green "Use this template" button at the top of this repository → "Create a new repository".

This gives you a clean copy of the template (only the master branch, no history) — the fastest way to start.

Alternatively, you can Fork the repository if you want to receive upstream template updates via pull requests.

Step 2: Rename Your Repository

In your forked repository, go to Settings
Scroll down to "Repository name"
Change it to yourusername.github.io (replace with your actual GitHub username)
Click "Rename"

Step 3: Choose Your Deployment Method

This template supports two common deployment options. You can pick the one that fits your setup, or switch later if needed.

Option A: GitHub Pages only (no Cloudflare)

In your repository, go to Settings → Pages
Under Source, select "Deploy from a branch"
Choose your default branch (e.g. master or main) and the "/ (root)" folder
Click Save

GitHub Actions workflows (such as build-website.yml and sync-scholar.yml) will run automatically, generate static files, and your site will be served via GitHub Pages, for example:
https://yourusername.github.io

Option B: Cloudflare Pages only (recommended)

In Cloudflare Pages, create a new project and connect it to your GitHub repository
Select the branch you want to deploy (usually main or master)
Set the Build command:
```
npm ci && npm run build
```
Set the Build output directory to the folder where your static files are generated (for this template, if the output is at the repository root, you can leave it empty or /)
(Optional) Bind your own custom domain in Cloudflare
(Optional) If you don’t need GitHub Pages anymore, you can disable it in Settings → Pages to avoid having two public sites from the same repository

For both options:

The GitHub Actions workflows in this repo (build-website.yml, sync-scholar.yml, deploy-waline.yml, etc.) will continue to work for generating pages, syncing Google Scholar, and deploying the comment system.
Template users only need to choose either GitHub Pages or Cloudflare Pages as their final public site.

Step 4: Clone to Your Computer

You need to clone the repository to your local computer so you can edit config/site.yaml (one-time setup) and config/content.json (your content). You can also edit files directly on GitHub.

git clone https://github.com/yourusername/yourusername.github.io.git
cd yourusername.github.io

Step 5: Update Required Configuration

All configuration files live in the config/ directory. This keeps the repo root clean.

File	Purpose	When to edit
config/meta.json	Template internals, Scholar sync status	Do not edit (used by scripts)
config/site.yaml	One-time setup: SEO, visitor map, short URL redirects	Set once when forking
config/content.json	Your content: bio, news, publications, experience, education	Edit whenever you update the site
config/config.json	Legacy merge of meta + site (written by Scholar sync)	Do not edit by hand

5.1 One-time site setup: `config/site.yaml`

SEO & identity — Edit the seo section with your website URL, name, description, keywords, and author / organization (used in meta tags and JSON-LD).

Visitor map — Paste your ClustrMaps domain_id only (get it from clustrmaps.com after creating a map). Other fields use defaults:

visitor_map:
  domain_id: "YOUR_CLUSTRMAPS_ID"   # ← paste your ID here

Redirects (optional) — Add short URLs, e.g. /mmtok → /projects/mmtok.html:

redirects:
  - alias: mmtok
    target: /projects/mmtok.html

5.2 Personal information (REQUIRED) — `config/content.json`

Update the personal section:

"personal": {
  "name": "Your Name",  // ← Change
  "email": "your.email@university.edu",  // ← Change
  "cv_link": "files/your-cv.pdf",  // ← Change to your CV file
  "profile_image": "images/your-photo.jpg",  // ← Change to your photo
  "links": [
    // ← Update all your social links
  ]
}

Step 6: Generate Favicons

You need to replace the favicon files with your own logo. Here are the methods:

Method 1: Using the Built-in Script (Recommended)

If you have a logo image at images/pagelogo_round.png:

python scripts/generate_favicons.py

This will automatically generate all required favicon files:

favicon.ico
favicon-16x16.png
favicon-32x32.png
apple-touch-icon.png

Method 2: Using Online Generators

Favicon.io (https://favicon.io/)
- Upload your logo image
- Download the generated favicon package
- Extract and place files in the root directory
RealFaviconGenerator (https://realfavicongenerator.net/)
- More comprehensive favicon generation
- Handles all device types and sizes

Method 3: Manual Creation

If you have image editing software:

favicon-32x32.png: Resize your logo to 32x32 pixels, save as PNG
favicon-16x16.png: Resize your logo to 16x16 pixels, save as PNG
apple-touch-icon.png: Resize your logo to 180x180 pixels, save as PNG
favicon.ico: Convert your 32x32 PNG to ICO format using an online converter

Required Files:

favicon.ico (32x32px, ICO format)
favicon-16x16.png (16x16px, PNG)
favicon-32x32.png (32x32px, PNG)
apple-touch-icon.png (180x180px, PNG)

All files should be placed in the root directory of your website.

Step 7: Add Your Content

Publications

Add your papers in the publications section:

"publications": {
  "2024": [
    {
      "title": "Your Paper Title",
      "authors": ["Your Name", "Collaborator 1", "Collaborator 2"],
      "venue": "CVPR 2024",
      "venue_type": "conference",
      "image": "teaser/your-paper.jpg",
      "featured": true,
      "tldr": "One sentence summary that appears on hover/tap.",
      "links": [
        {"name": "Paper", "url": "https://arxiv.org/abs/...", "icon": "ai ai-arxiv"},
        {"name": "Code", "url": "https://github.com/...", "icon": "fab fa-github"}
      ]
    }
  ]
}

💡 TL;DR Popovers: Adding a tldr field to any publication automatically enables an interactive summary tooltip — displayed as a glassmorphism popover on desktop (hover), and a tap-to-expand accordion on mobile.

News Updates

Add recent news:

"news": [
  {
    "date": "Dec 2024",
    "content": "Paper accepted to <strong>CVPR 2024</strong>!",
    "category": "papers"
  }
]

Experience and Education

Update your background:

"experience": [
  {
    "position": "Research Intern",
    "company": "Company Name",
    "period": "Summer 2024",
    "description": "Brief description...",
    "logo": "images/company-logo.jpg"
  }
],
"education": [
  {
    "degree": "PhD in Computer Science",
    "institution": "Your University",
    "period": "2024 - Present",
    "details": "Focus: Computer Vision and AI"
  }
]

Step 8: Add Your Images

Profile photo: Add your photo as images/your-photo.jpg
Paper teasers: Add teaser images to teaser/ directory
Company logos: Add logos to images/ directory
CV: Add your CV to files/ directory

Step 9: Deploy

git add config/content.json config/site.yaml
git add images/  # if you added new images
git add favicon* apple-touch-icon.png  # if you added favicons
git commit -m "Update personal information and configuration"
git push

That's it! GitHub Actions will automatically build and deploy your site in 1-2 minutes.

📝 Adding Blog Posts

Create .md files in blog/ directory:

---
title: "Your Blog Post Title"
date: "2024-01-01"
description: "Brief description"
tags: ["Research", "AI"]
image: "teaser/preprint.jpg"
---

# Your Blog Post

Write your content here in Markdown...

Push the file to GitHub - the blog will update automatically.

🔧 Local Development (Optional)

To preview changes locally before pushing:

# Install dependencies and build (Node)
npm ci
npm run build

# Or build with Python
python scripts/build_local.py

# Start local server
python scripts/local_server.py

# Visit http://localhost:8000

📋 Configuration Reference

News Categories

"papers": For publication news
"career": For job/position updates
"projects": For project announcements

Publication Types

"conference": Blue badge (published papers)
"under-review": Gray badge (under review)
"preprint": Orange badge (preprints)

Link Icons

For Publications:

Usage	Icon Code	Color Code
Paper (arXiv)	`"ai ai-arxiv"`	`#b91c1c`
Code	`"fab fa-github"`	`#333`
Dataset	`"fas fa-database"`	`#28a745`
Video (YouTube)	`"fab fa-youtube"`	`#ff0000`
Video (Bilibili)	`"fas fa-tv"`	`#fb7299`
Homepage	`"fas fa-home"`	`#2563eb`
Blog	`"fas fa-blog"`	`#2563eb`
Zhihu (Documentation)	`"fas fa-book-open"`	`#007bff`

For Social Links:

Usage	Icon Code	Color Code
Email	`"fas fa-envelope"`	`#dc3545`
Google Scholar	`"fas fa-graduation-cap"`	`#4285f4`
GitHub	`"fab fa-github"`	`#333`
Twitter	`"fab fa-twitter"`	`#1da1f2`
LinkedIn	`"fab fa-linkedin"`	`#1666C5`
Zhihu	`"fas fa-book"`	`#0084ff`

Example:

"links": [
  {
    "name": "Paper",
    "url": "https://arxiv.org/abs/2204.01018",
    "icon": "ai ai-arxiv"
  },
  {
    "name": "Scholar",
    "url": "https://scholar.google.com/citations?user=YOUR_ID",
    "icon": "fas fa-graduation-cap",
    "color": "#4285f4"
  },
]

❓ Troubleshooting

Website showing README instead of homepage

Make sure you pushed changes to config/content.json (and config/site.yaml if you use it)
Check GitHub Actions tab for build errors
Wait 1-2 minutes for deployment

Images not showing

Ensure image files are committed and pushed
Check file paths in config/content.json
Use relative paths from website root

Build errors

Validate JSON syntax in config/content.json and YAML in config/site.yaml
Check GitHub Actions logs for specific errors
Ensure all required fields are present

Visitor map not showing

Check that visitor_map.enabled is set to true
Verify your ClustrMaps domain_id is correct
Make sure you've signed up at clustrmaps.com and created a map

🎨 Customization

Colors / Dark Mode: Edit CSS variables in assets/css/styles.css — light theme under :root, dark theme under [data-theme="dark"]
Fonts: Change Google Fonts link in build scripts
Layout: Modify scripts in .github/scripts/

📞 Getting Help

📖 Read the detailed guide: How to Use This Template - comprehensive documentation with examples and troubleshooting tips (continuously updated)
💬 Have questions? Open an Issue - we're happy to help!
🔍 Review example config/content.json and config/site.yaml for reference
📋 Check GitHub Actions logs for build errors

📄 License

MIT License - free to use and modify!

Created by Sixun Dong - Independent Researcher

This template is designed to be simple and practical. Start with the basics and customize as needed.

Name		Name	Last commit message	Last commit date
Latest commit History 345 Commits
.agents		.agents
.github		.github
assets		assets
blog		blog
config		config
docs		docs
images		images
scripts		scripts
teaser		teaser
.gitignore		.gitignore
.nojekyll		.nojekyll
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
_redirects		_redirects
apple-touch-icon.png		apple-touch-icon.png
blog.html		blog.html
favicon-16x16.png		favicon-16x16.png
favicon-32x32.png		favicon-32x32.png
favicon.ico		favicon.ico
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
publications.html		publications.html

Folders and files

Latest commit

History

Repository files navigation

Academic Website Template

🎯 Features

🚀 Quick Start

(Optional) Step 0: Let an AI agent set things up

Step 1: Create Your Repository

Step 2: Rename Your Repository

Step 3: Choose Your Deployment Method

Option A: GitHub Pages only (no Cloudflare)

Option B: Cloudflare Pages only (recommended)

Step 4: Clone to Your Computer

Step 5: Update Required Configuration

5.1 One-time site setup: config/site.yaml

5.2 Personal information (REQUIRED) — config/content.json

Step 6: Generate Favicons

Method 1: Using the Built-in Script (Recommended)

Method 2: Using Online Generators

Method 3: Manual Creation

Step 7: Add Your Content

Publications

News Updates

Experience and Education

Step 8: Add Your Images

Step 9: Deploy

📝 Adding Blog Posts

🔧 Local Development (Optional)

📋 Configuration Reference

News Categories

Publication Types

Link Icons

❓ Troubleshooting

Website showing README instead of homepage

Images not showing

Build errors

Visitor map not showing

🎨 Customization

📞 Getting Help

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

5.1 One-time site setup: `config/site.yaml`

5.2 Personal information (REQUIRED) — `config/content.json`

Packages