Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/academicpages/academicpages.github.io/llms.txt

Use this file to discover all available pages before exploring further.

Academic Pages is designed so that you can go from zero to a live public website without installing any software. All you need is a free GitHub account. The steps below walk you through forking the template, configuring the essential fields in _config.yml, and verifying that GitHub Pages has built and published your site. If you later want to work locally — for faster iteration or to preview changes before pushing — a separate section at the bottom covers that workflow.

​
Create Your Site from the Template

1

Create a GitHub account

If you don’t already have one, register at github.com and confirm your email address. Email confirmation is required before GitHub Pages will activate on your repository.
2

Use the template

Go to github.com/academicpages/academicpages.github.io and click the Use this template button in the top right of the page, then choose Create a new repository.
3

Name your repository

On the “New repository” page, enter your repository name as exactly [yourusername].github.io — replacing [yourusername] with your GitHub username. This naming convention is what tells GitHub Pages to serve the repository as your personal site at that same URL.
The repository name must match your GitHub username precisely (case-sensitive on some systems). If the name doesn’t match, GitHub Pages will still build the site but it will be served at a subpath URL rather than the root yourusername.github.io.
4

Wait for the initial build

After creating the repository, GitHub Pages automatically begins its first build. Navigate to Settings → Pages in your new repository to watch the status. A green check mark next to the latest commit in the repository’s main view also indicates a successful build. The initial build usually completes within one to two minutes.

​
Configure _config.yml

Once the repository exists, edit _config.yml to replace the placeholder values with your own information. This single file controls the site title, your sidebar profile, the base URL, and nearly every site-wide setting.

​
Essential fields to update

The fields below must be changed for your site to work correctly and display your information: 
# _config.yml

# Basic Site Settings
locale    : "en-US"
site_theme: "default"  # "default", "air", "sunrise", "mint", "dirt", "contrast"
title     : "Jane Smith"
name      : &name "Jane Smith"
description: &description "Jane Smith's academic portfolio"
url       : https://janesmith.github.io   # must match your actual repository URL
baseurl   : ""                            # leave blank for a username.github.io repo
repository: "janesmith/janesmith.github.io"
The url field must exactly match the URL GitHub assigned to your Pages site. If it is wrong, links, feeds, and social sharing metadata will all point to the wrong domain. Double-check it in Settings → Pages after your first build.

​
Author sidebar

All of the information shown in the left-hand sidebar — your photo, name, bio, and profile links — comes from the author: block. Only fields with values are rendered; leave a field blank and its icon and link will not appear on the site. 
# _config.yml — author block
author:
  avatar    : "profile.png"          # filename inside /images/
  name      : "Jane Smith"
  pronouns  : "she/her"
  bio       : "Assistant Professor of Computer Science at Example University."
  location  : "Cambridge, MA, USA"
  employer  : "Example University"
  email     : "jane@example.edu"

  # Academic profiles — paste full URLs
  googlescholar : "https://scholar.google.com/citations?user=YOURID"
  orcid         : "https://orcid.org/0000-0000-0000-0000"
  github        : "janesmith"
  linkedin      : "janesmith"

​
Publication categories

The publication_category: block controls how publications are grouped on the Publications page. Edit the category title values to match your preferred headings: 
# _config.yml — publication categories
publication_category:
  books:
    title: 'Books'
  manuscripts:
    title: 'Journal Articles'
  conferences:
    title: 'Conference Papers'
Each publication file in _publications/ references one of these category keys (books, manuscripts, or conferences) via its category: front matter field.

​
Analytics and comments (optional)

Add Google Analytics or a comment provider by filling in the relevant blocks. Leave provider set to "false" to disable each feature: 
# _config.yml — analytics
analytics:
  provider: "google-analytics-4"   # or "false" to disable
  google:
    tracking_id: "G-XXXXXXXXXX"

# _config.yml — comments
comments:
  provider: "disqus"               # or "false" to disable
  disqus:
    shortname: "your-shortname"

​
Edit Files Directly on GitHub.com

You do not need to clone the repository or install anything locally to make changes. Every Markdown and YAML file in the repository can be edited right in the browser.
1

Navigate to the file

On your repository’s main page, click through the folder structure to find the file you want to edit — for example, _config.yml in the root, or a file like _publications/2024-01-01-my-paper.md.
2

Open the editor

Click the pencil icon (Edit this file) in the top right of the file preview, to the right of the Raw and History buttons.
3

Make your changes

Edit the file content directly in the browser editor. GitHub provides basic syntax highlighting for Markdown and YAML.
4

Commit the change

Scroll to the bottom of the page, write a short commit message describing what you changed, and click Commit changes. GitHub Pages will automatically trigger a new build within seconds.
You can also create new files (click Add file → Create new file from inside a directory) and upload binary assets like PDFs and images (Add file → Upload files). Files uploaded to the files/ directory are publicly accessible at https://[yourusername].github.io/files/filename.pdf.
To delete a file in the GitHub web interface, open it and click the trash can icon to the right of the pencil icon. Confirm the deletion by committing the change.

​
Edit Files Locally

Working locally gives you live preview with auto-reload, which is especially useful when making many changes at once. You will need Ruby, Bundler, and Node.js installed.
1

Install dependencies (Linux / WSL)

sudo apt install ruby-dev ruby-bundler nodejs
On macOS with Homebrew:
brew install ruby
brew install node
gem install bundler
2

Clone your repository

git clone https://github.com/[yourusername]/[yourusername].github.io.git
cd [yourusername].github.io
3

Install Ruby gems

bundle install
If you see a file permission error, install gems into the project directory instead:
bundle config set --local path 'vendor/bundle'
bundle install
4

Serve the site locally

jekyll serve -l -H localhost
Or, to use the exact gem versions from your lock file:
bundle exec jekyll serve -l -H localhost
The site will be available at http://localhost:4000. The -l flag enables live reload — the browser refreshes automatically when you save a Markdown or HTML file.
Changes to _config.yml are not picked up by the live-reload watcher. Stop the server (Ctrl+C) and restart it after editing that file.
5

Push changes to GitHub

When you are happy with your changes, commit and push them to publish:
git add .
git commit -m "Update publications list"
git push
GitHub Pages will build and deploy the updated site automatically.

​
Using Docker

If you prefer to avoid installing Ruby and Node.js directly on your machine, the repository includes a Dockerfile and a docker-compose.yaml. With Docker installed, run: 
chmod -R 777 .
docker compose up
The site will be accessible at http://localhost:4000.
If you use Visual Studio Code, the repository also ships with a Dev Container configuration. VS Code will prompt you to reopen the project in the container, which automatically installs all dependencies and serves the site at http://localhost:4000 with live reload.

​
Verify Your Live Site

After any push, return to Settings → Pages in your repository to confirm the build succeeded. You can also check the latest commit in the repository’s main file view:
Status indicatorMeaning
Green check mark ✅Build succeeded; site is live
Orange circle 🟠Build in progress
Red X ❌Build failed; check the Actions tab for error details
No iconNot yet built
Once the build is green, your site is live at https://[yourusername].github.io.

​
Next Steps

With your site live and _config.yml configured, the next tasks are adding your actual content:
  • Replace the placeholder files in _publications/, _talks/, _teaching/, and _portfolio/ with your own Markdown files.
  • Update _pages/cv.md with your real CV data, or populate _data/cv.json if you prefer the JSON-driven layout.
  • Add your profile photo as images/profile.png (the filename is set via author.avatar in _config.yml).
  • Upload PDFs (papers, slides, posters) to the files/ directory so they are accessible at https://[yourusername].github.io/files/.
  • Use the scripts in markdown_generator/ to batch-generate publication and talk Markdown files from a CSV or BibTeX file.

Build docs developers (and LLMs) love

Get started for freeTalk to us