1   Project Structure Overview

Your website is built with Jekyll and hosted on GitHub Pages. You never touch raw HTML for regular edits — almost everything is controlled by simple text files using YAML (settings) and Markdown (content).

Key folders and files at a glance

Path	What it controls
_config.yml	Global site settings — your name, bio, social links, profile photo filename
_data/navigation.yml	Top navigation bar links and their order
_pages/about.md	Home page body text
_pages/cv.md	CV / Resume page content
_publications/*.md	One file per publication entry
_talks/*.md	One file per talk or presentation
_teaching/*.md	One file per teaching position
_posts/*.md	Blog post entries
images/	Photos and images used anywhere on the site
files/	Downloadable files — PDFs, ZIPs, etc.

---

2   Site-Wide Settings & Profile

File: _config.yml

This single file controls your name, tagline, sidebar bio, profile photo, and all social/academic links. Open it in any text editor and look for the fields described below.

2.1   Your Name & Site Title

• Replace "Your Name / Site Title" with something like "Jane Smith | PhD Researcher".
• The &name syntax is a YAML anchor — changing it here updates every place it is referenced.

2.2   Sidebar Bio & Location

• avatar — the filename of your profile photo. The file must exist in the images/ folder. See Section 5 for how to change it.
• Leave any field blank (just a space after the colon) to hide it from the sidebar entirely.

2.3   Social & Academic Links

Below the author: section you will find fields for every major platform. Paste the full URL (or just a username where indicated):

2.4   Site URL (important before publishing)

---

3   Navigation Bar

File: _data/navigation.yml

This file controls which links appear in the top header bar and in what order.

3.1   Current structure

3.2   How to edit

• To rename a link, change the title: value — e.g. "Blog Posts" → "Articles".
• To reorder links, cut and paste entire - title / url blocks into the desired position.
• To remove a link, comment it out by adding # in front of both lines, or delete the two lines entirely.
• To add a link to an external site, add a new block with the full URL:
  - title: "My Lab"\n url: https://mylab.university.edu
• To add Publications back, uncomment the block that starts with # - title: "Publications".

---

4   Home / About Page

File: _pages/about.md

This is the first page visitors see. It is a standard Markdown file with a small YAML header at the top (called "front matter").

4.1   Front matter (top of file)

4.2   Body text

Everything below the closing --- is the page body written in Markdown. You can:

• Write plain paragraphs — just type and press Enter twice between paragraphs.
• Add headings with #, ##, or ====== underlines.
• Add links: [link text](https://url.com)
• Add bold: **bold text**
• Add bullet lists with - or * at the start of a line.

4.3   Adding an image inline

Place the image file in the images/ folder, then reference it in the Markdown:

To control the size, use an HTML img tag instead:

---

5   Profile Photo & Images

5.1   Changing your profile/sidebar photo

1. Prepare a square photo (recommended minimum 300×300 px). Ideally crop it to a square so it displays correctly in the circular frame.
2. Name the file something simple, e.g. profile.png or photo.jpg.
3. Upload (copy) it into the images/ folder in your project.
4. Open _config.yml and update the avatar field to match your exact filename:
   avatar: "photo.jpg"

5.2   Using images in page content

Any image file placed in images/ can be referenced from any Markdown page:

What you want	Markdown / HTML to write
Basic image	
Image with fixed width	<img src="/images/file.png" width="300">
Centered image	<p align="center"><img src="/images/file.png"></p>
Image as a link	[](https://example.com)

5.3   Supported image formats

PNG, JPG/JPEG, GIF, SVG, and WebP are all supported. Keep file sizes reasonable — large images slow down page loads. Aim for under 500 KB per image for web use.

---

6   CV Page

File: _pages/cv.md

The CV page is a Markdown file where you write your resume content directly. The Publications, Talks, and Teaching sections are auto-populated from their respective folders, but Education, Work Experience, and Skills are typed manually.

6.1   Editing Education & Work Experience

6.2   Adding a Skills section

6.3   Auto-populated sections

The following sections in cv.md automatically pull from their folders — you do NOT edit them here:

Section in CV	Data comes from
Publications	_publications/*.md
Talks	_talks/*.md
Teaching	_teaching/*.md

---

7   Publications

Folder: _publications/

Each publication is its own .md file. The filename format is YYYY-MM-DD-short-title.md — the date controls sort order.

7.1   Publication file template

7.2   Adding a new publication

1. Copy any existing file in _publications/.
2. Rename it to match the date and title, e.g. 2024-09-01-my-new-paper.md.
3. Edit all the fields in the front matter (between the --- markers).
4. If you have a PDF, copy it to files/ and set paperurl: '/files/mypaper.pdf'.

7.3   Changing publication categories

category: value	Appears under heading
manuscripts	Journal Articles
conferences	Conference Papers
books	Books

The heading labels can be changed in _config.yml under the publication_category: section.

---

8   Talks

Folder: _talks/

Each talk is its own .md file. Same naming convention: YYYY-MM-DD-talk-title.md.

8.1   Talk file template

8.2   Adding a new talk

1. Create a new file in _talks/ with the date-based filename format.
2. Fill in the front matter fields above.
3. Write a description in the body (below the second ---).

---

9   Teaching

Folder: _teaching/

9.1   Teaching file template

9.2   Adding a new course

1. Copy an existing file in _teaching/.
2. Rename it with the semester and course, e.g. 2024-fall-intro-ml.md.
3. Edit the front matter and body text.

---

10   Blog Posts

Folder: _posts/

Blog post filenames must follow the exact format YYYY-MM-DD-title-slug.md — Jekyll requires this.

10.1   Blog post template

10.2   Adding a new blog post

1. Create a new file in _posts/ with the exact filename format, e.g. 2024-06-15-my-research-update.md.
2. Write the front matter with at minimum title, date, and permalink.
3. Write your post content below the closing ---.

---

11   Uploading Files (PDFs, etc.)

Folder: files/

Anything placed in the files/ folder is publicly accessible at https://yourusername.github.io/files/filename.pdf.

11.1   How to add a file

1. Copy your PDF (or any file) into the files/ folder.
2. Commit and push to GitHub (or upload via the GitHub web interface).
3. Link to it from any Markdown page using: [Download PDF](/files/myfile.pdf)

11.2   Linking to a CV PDF

A common use case is a downloadable CV. Copy your CV PDF to files/cv.pdf and then in _pages/cv.md add:

11.3   Current files in this project

File	Access URL
paper1.pdf	/files/paper1.pdf
paper2.pdf	/files/paper2.pdf
slides1.pdf	/files/slides1.pdf

---

12   Markdown Quick Reference

All page content (about, cv, publications, talks, posts) is written in Markdown. Here is everything you need for everyday edits.

What you want	Markdown syntax	Result
Large heading	# Heading	Big bold heading
Sub-heading	## Sub-heading	Smaller heading
Heading (underline style)	Title ======	Same as #
Bold text	**bold**	bold
Italic text	*italic*	italic
Hyperlink	[text](https://url.com)	Clickable link
Image		Displayed image
Bullet list	- Item 1 - Item 2	• Item 1 • Item 2
Numbered list	1. First 2. Second	1. First 2. Second
Inline code	\`code\`	code
Horizontal rule	--- (on its own line)	Divider line
Paragraph break	One blank line between paragraphs	New paragraph
Line break	Two spaces at end of line then Enter	New line, same paragraph

12.1   Linking to a downloadable file

12.2   Linking to an external website

12.3   Embedding a YouTube video

Markdown does not support videos natively, but you can use an HTML iframe:

Replace VIDEO_ID with the ID from the YouTube URL (the part after v=).

---

Quick Reference — Where Is What?

I want to change…	Open this file	Field / Section
My name everywhere on the site	_config.yml	name: and author: name:
My sidebar bio	_config.yml	author: bio:
My profile photo	_config.yml + images/	author: avatar: + photo file
My email / social links	_config.yml	Under author: section
The top navigation links	_data/navigation.yml	title: and url:
The homepage text	_pages/about.md	Body below the ---
My CV / resume content	_pages/cv.md	Education, Work, Skills sections
A publication entry	_publications/YYYY-MM-DD-name.md	Front matter fields
A talk entry	_talks/YYYY-MM-DD-name.md	Front matter fields
A teaching entry	_teaching/YYYY-MM-DD-name.md	Front matter fields
A blog post	_posts/YYYY-MM-DD-title.md	Front matter + body
Add a downloadable PDF	files/ folder	Copy file here, link with /files/name.pdf
Add an image	images/ folder	Copy file here, reference with /images/name.jpg
The site URL	_config.yml	url: field