Full Documentation
Step-by-step visual guides for every content file — expand any section to learn more.
Contents
Contents
Install dependencies
Open a terminal in your project folder and install all required packages.
Run the setup wizard
The wizard asks your name, email, and social links, then generates your config file.
Start the dev server
Opens your portfolio in the browser. Changes you make are reflected instantly.
Before you start, make sure Node.js (v18+) and Git are installed. You can check by running node -v and git -v in your terminal.
Tip
The setup wizard only creates site.json with your basic info. All other content files are ready to edit at your own pace.
Everything you need to edit is in the content/ folder. You never need to touch any code in src/.
content/
All your content goes here
site.json
Your name, email, social links, feature switches
about.md
Your bio and career timeline
experience.json
Work history and education
publications/
One file per paper
projects/
One file per project
articles/
One file per blog post
news.json
Announcements and updates
awards.json
Awards and honors
research.json
Research lab affiliations
logos.json
Maps institution names to logo images
images/
Avatar, logos, project screenshots
Tip
After setup, your workflow is: edit a file in content/ → save → browser auto-refreshes. That's it!
site.json is the central config file generated by the setup wizard. Here are all the fields you can customize:
name.full
requiredYour full display name
Example:
Alex Chen
name.first / last
requiredUsed for terminal greeting and author matching
Example:
Alex / Chen
name.nickname
Short name for casual display
Example:
Alex
contact.email
requiredPrimary contact email
Example:
alex@example.com
contact.location
City and country for display
Example:
Portland, OR, USA
social.github
Full GitHub profile URL
Example:
https://github.com/username
social.linkedin
Full LinkedIn profile URL
social.twitter
Full Twitter/X profile URL
social.googleScholar
Google Scholar profile URL
terminal.username
Username shown in the terminal prompt
Example:
alex
terminal.skills
List of skill tags shown in the terminal
Example:
Python, React, Docker
terminal.timezone
Your timezone for the clock display
Example:
America/Los_Angeles
avatar
requiredFilename of your photo in content/images/
Example:
avatar.jpg
Tip
You can re-run npm run setup anytime to regenerate this file from scratch.
Each feature can be turned on or off in the features section of site.json. When a feature is off, its page and navigation link are completely hidden.
publications
Academic papers and research publications page
projects
Portfolio projects showcase page
articles
Blog posts and articles page
experience
Work history and education timeline page
news
News announcements on the home page
pets
Pet companion section on the home page
guide
This guide page (disable for your live portfolio)
Common presets to get started quickly:
Preset
What to enable
Software developer
projects, experience, articles
Researcher / Academic
publications, experience, news, articles
Student / Job seeker
projects, experience, awards
Designer / Creative
projects, articles
Minimal
projects only
Create a .md file in content/publications/ for each paper. The top section (between --- marks) contains structured data, the body is an optional description.
title
requiredFull paper title
authors
requiredComma-separated author list (your name will be highlighted automatically)
venue
requiredConference or journal name
Example:
NeurIPS 2025
year
requiredPublication year
Example:
2025
type
Paper type: conference, journal, workshop, preprint, or thesis
status
Publication status: published, accepted, under-review, or preprint
award
Award if any
Example:
Best Paper Award
links
List of links — each needs text, url, and icon name
abstract
Paper abstract (shown on click)
featuredImage
Path to a figure image
Example:
/images/paper-fig.png
tldr
One-line plain-English summary
Tip
Your name is auto-highlighted in the author list based on the name variants in site.json. Add name variations to name.authorVariants if needed.
Create a .md file in content/projects/ for each project. The structure is similar to publications.
title
requiredProject name
description
requiredShort one-line description
tags
Technology tags
Example:
React, Python, Docker
year
Year of the project
Example:
2025
links
List of links (demo, GitHub, docs, etc.)
featured
Set to true to highlight this project
featuredImage
Path to a screenshot
Example:
/images/projects/demo.png
Create a .md file in content/articles/ for each blog post. Write the body in Markdown below the front matter.
title
requiredArticle headline
date
requiredPublication date
Example:
2025-03-01
tags
Topic tags
Example:
AI, Tutorial, Python
description
Short summary shown in article list
links
External links (e.g. published on Medium)
Edit content/experience.json to add your work positions, internships, and education history. Each entry is displayed on a visual timeline.
title
requiredJob title or degree name
Example:
Software Engineer
company
requiredCompany or university name
Example:
type
requiredEntry type: work, education, internship, or research
startDate
requiredStart date
Example:
2023-09
endDate
End date (leave empty for current position)
Example:
2025-06
isCurrent
Set to true for ongoing positions (shows "Present")
location
City and state/country
Example:
San Francisco, CA
description
Short description of your role
tags
Skills and technologies used
Tip
Entries are sorted by start date. Use isCurrent: true for ongoing positions — they appear at the top. If a company name matches an entry in logos.json, its logo will be displayed.
Edit content/research.json to list your research lab affiliations. Each lab is displayed on the About page with an icon and optional advisor.
lab
requiredLab or research group name
Example:
AI Research Lab
emoji
requiredFallback icon (shown if no logo image)
Example:
🤖
advisor
Advisor name (displayed as "w/ Prof. Name")
focus
requiredResearch focus area
Example:
large language models
link
requiredLab website URL
Tip
If the lab name matches an entry in logos.json, the logo image is shown instead of the emoji.
Edit content/news.json for announcements and content/awards.json for awards. News items appear on the home page.
type
requiredCategory: publication, talk, release, award
Example:
publication
badge
requiredShort label shown as a colored badge
Example:
Publication
icon
requiredReact icon name for the badge
Example:
FaFileAlt
iconColor
Chakra UI color for the icon
Example:
blue.400
title
requiredHeadline of the news item
description
Short description text
date
requiredDisplay date
Example:
Dec 2025
sortDate
requiredSorting date (YYYY-MM-DD format)
Example:
2025-12-01
links
Optional action links (Paper, Code, etc.)
Common icon names for news:
Icon name
Looks like
Good for
FaFileAlt
Document
Publications, papers
FaMicrophone
Microphone
Talks, presentations
FaRocket
Rocket
Releases, launches
FaTrophy
Trophy
Awards, competitions
FaGraduationCap
Grad cap
Education milestones
FaCode
Code
Open source releases
Awards in content/awards.json use a simpler format:
title
requiredAward name
Example:
Best Paper Award
org
requiredAwarding organization
Example:
NeurIPS 2024
date
requiredDate received
Example:
Dec 2024
kind
requiredType: grant, hackathon, travel, scholarship, honor, competition, innovation
link
Optional link to the award page
Edit content/about.md — it has two parts: structured data (between --- marks) and your free-form bio below.
journeyPhases
Career timeline entries displayed as vertical cards
→ period
requiredTime range
Example:
2019 - 2023
→ title
requiredPosition or degree
Example:
B.S. in Computer Science
→ org
requiredOrganization name
Example:
UC Berkeley
→ description
Short description of what you did
→ tags
Skill tags for this phase
mentorship
Collaborators section with name, URL, and note
Bio text (below ---)
Your main bio in Markdown — shown at the top of the About page
Tip
Journey phases are displayed as a vertical timeline. Put them in chronological order. The bio text below --- becomes your main paragraph at the top.
All images live in content/images/ and are automatically served on your site. Here's how they're organized:
content/images/
All your images
avatar.jpg
Your profile photo (set in site.json)
logos/
Institution and company logos
stanford.png
Square PNG ~200x200px
projects/
Project screenshots (optional)
How to reference images in different files:
File
How to reference
Example
site.json (avatar)
Just the filename
"avatar.jpg"
site.json (pets)
/images/ path
"/images/lulu.jpg"
logos.json
/images/logos/ path
"/images/logos/mit.png"
Markdown files
/images/ path
"/images/paper-fig.png"
Map institution names to logos in content/logos.json. The key must exactly match the institution name in experience.json or research.json.
Tip
Supported formats: .jpg, .png, .svg, .webp, .gif. For logos, square PNG or SVG at ~200x200px works best. For avatar, any aspect ratio works — it's displayed as a circle.
npm run dev
Start the local dev server with hot reload — the main command you'll use.
npm run build
Build your site for production. Output goes to the dist/ folder.
npm run setup
Re-run the setup wizard to regenerate site.json from scratch.
npm run validate
Check for common config mistakes like missing files or typos.
npm run lint
Run the code linter to check for style issues.
If something breaks, try these troubleshooting steps in order:
Run validate
npm run validate — checks for config errors and missing files.
Clear cache and reinstall
Delete node_modules and dist folders, then run npm install again.
Check TypeScript errors
Run npx tsc --noEmit to see detailed error messages.
Tip
The dev server auto-refreshes when you save any file in content/. If it stops, just restart with npm run dev.
After building your site, deploy it to the web. Here are three popular, free options:
GitHub Pages (recommended)
Free and automatic. Push your code to GitHub, go to Settings → Pages → Source, select "GitHub Actions". Every push to main deploys automatically via the included workflow.
Vercel
Easiest setup. Sign in at vercel.com with GitHub, click "Import Project", select your repo, and click "Deploy". Auto-detects Vite and deploys on every push.
Netlify
Similar to Vercel. Sign in at netlify.com with GitHub, click "Add new site" → "Import from Git", select your repo, and deploy.
Before deploying, always build locally first to catch errors:
Tip
All three platforms support custom domains. Add your domain in the platform's settings and update your DNS records as instructed.
TermHub includes a built-in MCP (Model Context Protocol) server that lets AI assistants like Claude directly read, write, and manage your portfolio content. Instead of editing files manually, you can give your resume to Claude and have it generate everything automatically.
Install the MCP server
Navigate to the mcp-server/ directory inside TermHub and install its dependencies.
Configure your AI client
Add the MCP server to Claude Desktop or Claude Code so the AI can use TermHub tools.
Talk to the AI
Tell Claude to read your resume and generate your portfolio. It calls the tools automatically.
Configure the MCP server in your AI client:
After configuring, restart your AI client. Then you can say things like:
The MCP server exposes 19 tools. Here are the most commonly used ones:
Tool
What it does
get_schema
Returns all data types — AI calls this first to understand the structure
get_site_status
Overview of current content (counts, profile info)
parse_pdf
Extract text from a PDF resume
generate_from_resume
All-in-one: creates a blueprint from resume text for AI to follow
update_site_config
Set name, email, social links, terminal config
add_publication
Add a paper (with full metadata validation)
add_project
Add a project with tags, highlights, category
add_experience
Add a work/research timeline entry
add_education
Add an education entry
add_news
Add a news item
add_award
Add an award or honor
write_markdown_content
Write any Markdown content file
write_json_content
Write any JSON content file
manage_assets
Copy images (avatar, logos) to the right directories
preview_site
Start dev server or build for production
reset_content
Clear all content for a fresh start
Tip
The typical AI workflow is: parse_pdf → generate_from_resume → reset_content → call individual add_* tools for each item → preview_site. The whole process takes under a minute.
Site didn't update after saving?
Check that the dev server is still running in your terminal. If it crashed, restart with npm run dev.
Red error in the terminal?
Usually a typo in JSON — missing comma, extra comma, unclosed quotes. Run npm run validate to find the issue.
Avatar or logo not showing?
Make sure the file is in content/images/ and the filename matches exactly (case-sensitive). Check avatar field in site.json or key in logos.json.
How to change colors/theme?
Edit src/config/theme.ts — this requires some code knowledge. The file has comments explaining each color.
How to add a new page?
Requires code changes: create a component in src/components/, add a route in src/App.tsx, and add to navItems in src/site.config.ts.
Not a researcher?
No problem! Disable publications and research in site.json, focus on projects and articles. TermHub works great for developers, designers, students, and anyone who wants a clean portfolio.