Detailed Version - From Zero - How to Have Your Own Personal Website in 8 Hours
chuanbaozheng.com
20260325 Today I decided to build my own personal website. The reason: yesterday my wife made one. The idea of making my own site first came to me during my master's. Some knowledge gaps plus procrastination kept me from doing it.
So, like a volcano that had built up enough, I decided to feel my way through it today. After all, when I got up this morning I knew nothing. I had no idea what enemies and difficulties I was facing. Anyways, since I could do it, and you've read this far, believe in yourself. You can do it too.
This is the detailed version. Every step is broken out, with error handling included. If you just want a config you can copy straight, see Quick Version.
(Updated 2026-07: this was first written in 2026-03. I went through it again against how the site actually runs and fixed a few places that would get you stuck if you followed them as written — mainly the GitHub default branch name, the Vercel DNS values, and a
.gitignoretrap I hit myself.)
Tools you need
Making a website is basically this pipeline:
Write code locally → push to GitHub → Vercel deploys automatically → a URL is generated worldwide
Before you start, register these accounts:
| Number | Tools | link | comments | In plain words |
|---|---|---|---|---|
| Computer | One that can create folders | |||
| 1 | Gemini / ChatGPT / Claude | https://gemini.google.com/ | Paste errors to it and let it help you fix them | Your on-call tech support |
| 2 | Github | https://github.com/ | Code built locally gets uploaded to GitHub; the next tool (Vercel) can pull from it | |
| 3 | Vercel | https://vercel.com | Used to deploy the site; publishes what's stored on GitHub to the web | |
| 4 | Windows PowerShell | No install needed, comes with Windows | Nothing to install here | You'll need some basic command line |
| 5 | Obsidian | https://obsidian.md/ | Works with PowerShell; uploads what you just updated to GitHub | Optional, but strongly recommended |
| 6 | Git | https://git-scm.com/download/win | The code mover; you can install this later, at step 14 | No rush |
| 7 | Cloudflare | https://dash.cloudflare.com | Register and buy a domain | Custom domain |
OK, let's start:
Part 1: Get the site running locally
1. Install Node.js first, so you can preview your site locally before uploading it for real: go to https://nodejs.org/ and download the LTS version, clicking "Next" all the way through.
2. Once it's installed, press the Win key (the four little squares), search for Windows PowerShell, and open it. You'll see a prompt like this:
PS C:\Users\chuan>3. Type cd Desktop (to enter the Desktop folder).
If you hit an error at this step, paste the error as-is to an AI and let it help you fix it.
4. mkdir my-blog (creates a folder named my-blog)
5. cd my-blog (enters the my-blog folder)
6. Once you're in the folder, we'll install and initialize VitePress in this black window.
7. Initialize the project:
npm init -y8. Install VitePress, Vue, and the sidebar plugin:
npm add -D vitepress vue vitepress-sidebar9. Run the setup wizard (you only need to run this once):
npx vitepress initYou'll be asked these questions:
Where should VitePress initialize the config? → enter ./
Site title: → your site name (e.g. XX's study space)
Site description: → a description (e.g. tracking growth, daily check-ins)
Theme: → choose Default Theme
Use TypeScript for config and theme files? → Yes
Add VitePress npm scripts? → YesAbout the TypeScript question: when I first wrote this, I suggested beginners pick No. I now recommend Yes. The reason is practical: Yes generates
config.mts, which matches all the code later in this post and most VitePress tutorials online; No generatesconfig.mjs, which adds a layer of confusion when you copy code. It doesn't require you to know TypeScript. The config is written exactly the same way.
10. Start the local preview:
npm run devThe terminal will give you an address (usually http://localhost:5173). Copy that address into your browser and open it, and you'll see a clean personal site prototype with a sidebar!
If this step throws
npm : cannot load file ...\npm.ps1 because running scripts is disabled on this system— see the troubleshooting at the end of this post. It takes two minutes to fix.
11. In your my-blog folder, find the .vitepress/config.mts file.
.vitepressis a hidden folder. In File Explorer, click "View" at the top → check "Hidden items" to see it. Or just open the wholemy-blogfolder in VS Code and everything is visible.
12. Open config.mts and replace the contents with the [config I'm using] section at the end of this post (remember to change it to your own name and links).
13. Create the matching files.
Now that the paths are set, you need to create the matching folders and files under the my-blog root directory for the pages to show content:
- In the root directory, create
index.md(home page) andabout-me.md(About Me) - Create a folder
logs, and inside it createindex.mdand your first note
Go back to the browser and refresh, and you'll see the sidebar arranged exactly the way you set it up!
If it doesn't show up, it's most likely a path problem. Paste
config.mtsand your folder structure to an AI and have it check them against each other.
14. If you need images: create a folder under the my-blog root directory named public (VitePress's dedicated place for static assets). Find an image (e.g. test.jpg) and drop it in.
When referencing it in Markdown, just write the path as /test.jpg; you don't need to include public:

Part 2: Push to GitHub
15. Download and install Git for Windows, then click "Next" all the way through the installer. After it finishes, type git --version in the terminal. If you see a version number, it worked.
16. ⚠️ Create .gitignore first, before any git add. Getting this order wrong causes real trouble.
In the root of my-blog, create a new file named exactly .gitignore (note the leading dot, no extension), with this content:
node_modules/
.vitepress/cache/
.vitepress/dist/
.env.localWhy this has to come first:
node_modulesholds tens of thousands of third-party library files that npm installed, hundreds of MB in total. Vercel reinstalls them frompackage.jsonat deploy time, so you never need to upload them.And
.gitignoreonly applies to files that haven't been committed yet. Once a file is in git's history, adding it to.gitignorelater does nothing. It stays with you.I got this order wrong myself: 5341 files from
node_moduleswent up in the first commit, and I didn't notice for months. Cleaning it up meant a separategit rm -r --cached node_modules. Thirty seconds to create this file now saves you that.One more thing: if you also manage this folder with Obsidian, add
.obsidian/and.trash/too. Those are Obsidian's local workspace state and deleted notes, and they don't belong in the repo.
17. Create a repository on GitHub. Its job is to be a relay station for your local code:
- Log in to GitHub
- Click + in the top right → New repository
- Name it
my-blog - Public or Private both work. Choosing Private doesn't affect Vercel deployment at all: Vercel goes through GitHub App authorization, so it can pull and build from private repos, and your site is still publicly accessible. If your notes contain drafts you don't want public, just pick Private.
- Do not check any of "Add a README file" / "Add .gitignore" / "Choose a license" (they'll conflict with your local files)
- Click Create repository
18. Back in PowerShell, run these in order:
git initgit add .git commit -m "first commit"If you get an error saying identity information is needed, run these two first (copy-paste, keep the double quotes):
bashgit config --global user.email "your-email@example.com"bashgit config --global user.name "your-name"Then run
git commitagain.
19. Link the remote repo and push (remember to replace your-username with the real one):
git remote add origin https://github.com/your-username/my-blog.gitgit branch -M maingit push -u origin mainAbout
mainandmaster: Git's default branch used to be calledmaster, and GitHub switched the default tomainin 2020. Thegit branch -M mainabove renames your local branch tomainso it matches GitHub.If you see
git push -u origin masterfail somewhere else with a "branch does not exist" error, this is why.The first push on Windows pops up a window asking you to log in to GitHub. Just authorize it in the browser.
20. Remember these three commands. Every time you change files locally, run these three so Vercel sees the update:
git add .git commit -m "updated today's study notes"git pushThe text in quotes describes the change. Write whatever you like; it's for future you.
Part 3: Deploy to Vercel
21. Connect Vercel (to get free public access):
- Go to the Vercel website and log in directly with your GitHub account
- Click Add New in the top right → Project
- You'll see the
my-blogrepo you just created. Click Import - Vercel usually detects VitePress automatically. Make sure
Framework Presetis set to VitePress (or Other), then click Deploy
22. If the build fails, go to the project's Settings → Build & Development Settings and set these by hand:
- Install Command:
npm install - Build Command:
node node_modules/vitepress/bin/vitepress.js build - Output Directory:
.vitepress/dist
Why the workaround: when you write
vitepress builddirectly, Vercel's Linux environment sometimes throwsPermission Deniedbecause of executable file permissions and can't find the command. Skip that shortcut and call the js file behind it withnode, and permissions no longer matter.
23. How to check whether the deploy worked:
Go back to your Vercel Dashboard:
- Success: your project card shows a green "Ready" label and a preview image (what your site looks like)
- Still running: if you see "Building" or a blue progress bar, it's working. Wait a minute or two
- Failed: you'll see a red "Error" or "Failed". Click in, open Build Logs, copy the red error text and paste it to an AI. That usually solves it
Part 4: Connect your own domain
24. Buy a domain on Cloudflare (Cloudflare sells at cost with no markup, cheaper than most registrars).
25. Add the domain in Vercel: project → Settings → Domains → enter your domain → Add.
26. Vercel shows you a card with the DNS records you need to set.
⚠️ Fill in exactly the values Vercel shows on that page. Don't copy hardcoded numbers from any tutorial, including this one.
Vercel now assigns different addresses depending on the project and plan: older projects mostly get 76.76.21.21 for the A record, while new projects may get 216.198.79.1 or something else. The www CNAME has also changed from the old shared cname.vercel-dns.com to a string unique to each project (something like d1d4fc829fe7bc7c.vercel-dns-017.com). If you enter a value that doesn't belong to your project, verification will never pass, and the error message won't tell you that's the reason.
Go to the Cloudflare dashboard → DNS → add two records:
| Type | Name | Content |
|---|---|---|
| A | @ | The IP shown on the Vercel card |
| CNAME | www | The string shown on the Vercel card |
27. Two Cloudflare-specific traps:
- You must go to the SSL/TLS menu and change the encryption mode to Full (or Full strict). The default Flexible causes an endless redirect loop and the site won't open at all.
- Click the little cloud icon to the right of those two records so it turns grey (DNS only). With the orange proxy on, Vercel sometimes can't verify. Once the domain is verified and the site opens, decide whether to turn the orange cloud back on.
Part 5 (advanced): Connect with Obsidian
Once deployed, managing this folder with Obsidian makes updating much faster. You write in a note-taking app, and one click puts it online.
28. "Take over" your blog in Obsidian:
- Open Obsidian
- Click "Open another vault" in the bottom left
- Click "Open folder as vault"
- Choose your root folder:
C:\Users\chuan\my-blog
Now you'll see all the folders on the left: logs, public, .vitepress, and so on.
29. Configure Obsidian so it works like the web page:
- Files & Links
- Default location for new attachments → change to
Same folder as current file(so images sit next to the note, where the site can find them) - Use [[Wikilinks]] → turn it off (important! the site only understands standard Markdown links
[description](path), not double brackets[[]])
- Default location for new attachments → change to
- Editor
- Default view mode → set to
Live Preview, so you get instant preview when writing formulas and structured notes
- Default view mode → set to
- Install the community plugin GitHobs to push straight from Obsidian without switching back to the terminal
⚠️ After you start using Obsidian, check that
.gitignorecontains.obsidian/and.trash/(see step 16). Obsidian creates workspace layout, plugin config, and backups of deleted notes in your folder. These are local state and shouldn't go into the repo.
Troubleshooting
npm : cannot load file xxx\npm.ps1 because running scripts is disabled on this system
Windows blocks PowerShell scripts by default. Allow them:
- Click the Windows Start menu and search for
PowerShell - Right-click "Windows PowerShell" and choose "Run as administrator" (this step matters)
- Type the command below and press Enter:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser- The terminal asks you to confirm. Type
Yand press Enter - Close this administrator window and go back to your normal PowerShell window (the one at
C:\Users\chuan\my-blog), then run the command that failed
If it works this time, you'll see a block of text about package.json scroll past. That means your foundation is in place.
I changed custom.css but the page looks the same
Check whether .vitepress/theme/index.ts exists and whether it imports your css. A CSS file only takes effect if this entry file imports it. This is the most common beginner trap: "I wrote the styles but nothing happened."
Works locally, but clicking into a folder online gives a 404
Check whether config.mts has cleanUrls: true.
Build error: dead link
By default VitePress treats dead links as fatal errors and stops the build. Add ignoreDeadLinks: true to config.mts.
Common PowerShell commands
| Command | What it does |
|---|---|
ls | Show the contents of the current folder |
cd path | Go into a folder, e.g. cd C:\Users\chuan\my-blog |
cd .. | Go up one folder |
npm run dev | Start the local preview |
npm run build | Build once locally to catch errors early |
git status | See which files have changed |
The config I'm running, for reference
Below are the files actually running on chuanbaozheng.com.
.vitepress/config.mts
The site's command center. What the sidebar looks like, what the site is called, where the top nav goes — it's all configured here.
import { defineConfig } from 'vitepress'
import { generateSidebar } from 'vitepress-sidebar'
export default defineConfig({
// 1. Basic config (default = English root locale)
title: "Chuanbao's Space",
description: 'Protein design & wet-lab notes',
ignoreDeadLinks: true, // ignore dead links, force the build
cleanUrls: true, // 🌟 key: clean URLs, fixes 404s on folder index routes
// 🌟 required for a custom domain: sitemap so Google can find you
sitemap: {
hostname: 'https://chuanbaozheng.com'
},
// 🌟 make sure base is the root, or images/styles break on a custom domain
base: '/',
appearance: false, // dark mode switch, see notes below
lastUpdated: true,
// 🌟 bilingual: English is root (no prefix), Chinese lives under /zh/
locales: {
root: {
label: 'English',
lang: 'en-US',
},
zh: {
label: '简体中文',
lang: 'zh-CN',
link: '/zh/',
title: 'Chuanbao',
description: '蛋白质设计与实验笔记',
themeConfig: {
nav: [
{ text: '首页', link: '/zh/' },
{ text: '研究', link: '/zh/research' },
{ text: '项目', link: '/zh/projects' },
{ text: '日志', link: '/logs/' },
{ text: '关于我', link: '/zh/about-me' },
{ text: '简历', link: '/zh/cv' },
],
outline: { label: '本页目录', level: [2, 3] },
lastUpdatedText: '最后更新时间',
footer: {
message: 'chuanbaozheng77@gmail.com',
copyright: `Copyright © 2026-${new Date().getFullYear()} Chuanbao`,
},
},
},
},
// 🌟 favicon + social share metadata
head: [
['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
['meta', { name: 'theme-color', content: '#4f5fd6' }],
['meta', { property: 'og:type', content: 'website' }],
['meta', { property: 'og:title', content: "Chuanbao's Space" }],
['meta', { property: 'og:url', content: 'https://chuanbaozheng.com/' }],
['meta', { name: 'twitter:card', content: 'summary' }],
],
themeConfig: {
// 1. Top nav (English root)
nav: [
{ text: 'Home', link: '/' },
{ text: 'Research', link: '/research' },
{ text: 'Projects', link: '/projects' },
{ text: 'Notes', link: '/logs/' },
{ text: 'About', link: '/about-me' },
{ text: 'CV', link: '/cv' },
],
// 2. Sidebar
// /logs/ → generated by scanning
// /academy/ → written by hand (order matters, can't sort by filename)
sidebar: {
// 🌟 note the three dots. With resolvePath, generateSidebar returns
// an object keyed by path, like { '/logs/': [...] }, so you spread it
// in to sit alongside the hand-written '/academy/' below.
// If you only have one auto sidebar and no second hand-written one,
// just write sidebar: generateSidebar([...]) without this wrapper.
...generateSidebar([
{
documentRootPath: '/',
scanStartPath: 'logs',
resolvePath: '/logs/',
useTitleFromFileHeading: true,
useFolderTitleFromIndexFile: true, // if a folder has index.md, use its title
collapsed: true,
hyphenToSpace: true,
sortMenusByName: true
}
]),
'/academy/': [
{
text: 'Protein Design Journey',
items: [
{ text: 'Dashboard', link: '/academy/' },
{ text: 'Knowledge Map', link: '/academy/map' },
{ text: 'Changelog', link: '/academy/changelog' },
],
},
{
text: 'Learn',
items: [
{ text: 'Curriculum', link: '/academy/curriculum/' },
{ text: 'Knowledge Base', link: '/academy/knowledge/' },
{ text: 'Paper Library', link: '/academy/papers/' },
],
},
{
text: 'Research',
items: [
{ text: 'Research Lab', link: '/academy/lab/' },
{ text: 'Timeline', link: '/academy/timeline' },
{ text: 'Unknown Unknown', link: '/academy/unknowns' },
],
},
],
},
// 3. Article outline and table of contents
outline: { label: 'On this page', level: [2, 3] },
aside: true,
// 4. Social links
socialLinks: [
{ icon: 'github', link: 'https://github.com/superaseraser' },
{ icon: 'linkedin', link: 'https://www.linkedin.com/in/chuanbao-zheng-05a081202/' }
],
// 5. Footer and last-updated text
lastUpdatedText: 'Last updated',
footer: {
message: 'chuanbaozheng77@gmail.com',
copyright: `Copyright © 2026-${new Date().getFullYear()} Chuanbao`
}
}
})Two lessons, both learned the hard way:
appearance: false— I had dark mode on at first (true). Then the custom CSS kept growing, and every color had to be tuned twice, light and dark. Each new component meant checking both. Maintenance cost doubled, so I turned it off. If you're using the default theme and barely touching the styles, go ahead and settrue— VitePress's built-in dark mode looks good. How much you customize decides this, not whether dark mode is any good.The bilingual trap — VitePress assumes the two languages have perfectly matching paths. My
logs/is Chinese-only, with no English mirror, so clicking the language switcher on a logs page gave a 404. I fixed it by writing a small route interceptor. If you go bilingual, either build both sides of every page, or accept that some sections exist in one language only and decide up front how the switcher should handle them.
.vitepress/theme/custom.css
Handles "looking good." Controls colors, font sizes, layout tweaks. Without it, the site goes out with no makeup on.
/* =========================================
1. Layout fix: nav links left, social/search right
========================================= */
.VPNavBar .content-body {
display: flex !important;
justify-content: flex-start !important;
}
/* key: push the menu left, leave the rest of the space on the right */
.VPNavBarMenu {
flex-grow: 0 !important;
margin-right: auto !important; /* 🌟 the trick: shoves everything on the right away */
margin-left: 32px !important;
}
.VPNavBarSearch,
.VPNavBarAppearance,
.VPNavBarSocialLinks {
flex-grow: 0 !important;
margin-left: 12px !important;
}
/* mobile: keep the hamburger menu on the right */
@media (max-width: 959px) {
.VPNavBar .content-body {
justify-content: space-between !important;
}
}
/* =========================================
2. Home hero: default font sizes are too loud, shrink them
========================================= */
.VPHero .name {
font-size: 38px !important;
line-height: 44px !important;
}
.VPHero .text {
font-size: 26px !important;
line-height: 32px !important;
}
.VPHero .tagline {
font-size: 16px !important;
color: var(--vp-c-text-2) !important;
}.vitepress/theme/index.ts
The theme's entry file. It pulls in custom.css above and applies the renovation to the house. Miss this file and not one line of your CSS takes effect.
import DefaultTheme from 'vitepress/theme'
import './custom.css'
export default {
extends: DefaultTheme,
}index.md
Your homepage content. The text and buttons you see first when you open chuanbaozheng.com are all written here.
⚠️ Note the
---line at the top and another at the bottom. You need both. The part in between is called frontmatter, config for VitePress. Leave off the opening line and the whole page renders as one block of plain text.
---
layout: home
hero:
name: "Chuanbao's Space"
text: "Bio-Design & Digital Life"
tagline: 记录每一个成功搭建环境的小瞬间
image:
src: /test-cat.png
alt: 我的测试猫
actions:
- theme: brand
text: About me
link: /about-me
- theme: alt
text: 开始阅读
link: /logs/
features:
- icon: 🧬
title: 蛋白质设计
details: 记录 RFdiffusion, AlphaFold 和结构生物学的点点滴滴。
link: /logs/learning/protein-design/AlphaFold2
- icon: 🔬
title: 实验技能
details: 湿实验操作规范与避坑指南。
link: /logs/learning/Basic-biology/lab-skills/lab-skill-list
- icon: 📚
title: 读书笔记
details: 把看过的书沉淀为成长的养料。
link: /logs/learning/books-and-other/Books/books
---The
linkin eachfeaturesentry must point to a file that actually exists, or you get a 404. Click through them all yourself when you're done.
package.json
Records which "parts" (plugins) the site needs, plus the commands to start and build it.
{
"name": "my-blog",
"version": "1.0.0",
"type": "module",
"scripts": {
"dev": "vitepress dev",
"build": "node node_modules/vitepress/bin/vitepress.js build",
"preview": "vitepress preview"
},
"dependencies": {
"vitepress": "latest",
"vitepress-sidebar": "^1.33.1",
"vue": "latest"
}
}.gitignore
Don't forget this file (see step 16).
node_modules/
.vitepress/cache/
.vitepress/dist/
.env.local
.obsidian/
.trash/Another version for reference: Quick Version — How to Get Your Own Personal Website in 8 Hours
💡 A note to the reader
"You've got this!"