Quick Version — How to Get Your Own Personal Website in 8 Hours (VitePress + Vercel + Cloudflare)
Before you start: if you also want a personal site like
chuanbaozheng.comthat loads fast, builds its own table of contents, and works in both Chinese and English, follow this guide. You don't need to know programming. You just need to copy and paste.The whole chain is: write Markdown locally → push to GitHub → Vercel deploys automatically → live worldwide. Finish a note, push it, and a minute later the whole world can see it.
If you want the longer version with error handling at every step, go to Detailed Version.
Stage 1: Getting ready (installing tools)
Before you start, your computer needs two foundations:
Node.js: the environment your site runs in.
- Go to nodejs.org and download the LTS (Long Term Support) version, clicking "Next" all the way through.
- After installing, type
node -vin PowerShell. If you see a version number, you're set.
Git: the mover that carries your code to GitHub.
- Go to git-scm.com, download, and click "Next" all the way through.
- After installing, type
git --versionto check.
VS Code (optional): an editor.
- PowerShell + Notepad, which come with Windows, can also do the job, but VS Code is much nicer. code.visualstudio.com
Stage 2: Set up your site repository
Make a new folder: for example
my-blog.Open a terminal: inside this folder, hold
Shift+ right-click → "Open PowerShell window here". (Or in VS Code:Terminal→New Terminal.)Run the setup commands:
npm init -ynpm add -D vitepress vue vitepress-sidebarnpx vitepress initIt will ask you a few questions:
| Question | How to answer |
|---|---|
| Where should VitePress initialize the config? | Enter ./ |
| Site title | Your site name, e.g. XX's Study Space |
| Site description | A one-line description |
| Theme | Choose Default Theme |
| Use TypeScript for config and theme files? | Yes (only if you pick Yes will it generate config.mts, which matches the code later in this guide) |
| Add VitePress npm scripts? | Yes |
- Preview locally:
npm run devThe terminal will give you http://localhost:5173. Open it in a browser and you'll see the bare bones of your site.
Stuck here? If you get the error
npm : cannot load file ... because running scripts is disabled on this system, see the troubleshooting at the end.
Stage 3: The core config file
This is the "brain" of the site. Open .vitepress/config.mts and replace everything with the block below (remember to change the name, links, and domain to your own).
This is a starter config: one language, one automatic sidebar. Enough to get your site running. The full version I actually run on my own site (bilingual + hand-written sidebar + OG sharing info) is at the end of the Detailed Version. Copy it when you want to add features.
import { defineConfig } from 'vitepress'
import { generateSidebar } from 'vitepress-sidebar'
export default defineConfig({
title: "Your Name",
description: "A one-line description of your site",
base: '/',
// 🌟 Three switches every beginner should turn on. Skip one and you'll hit a snag:
cleanUrls: true, // URLs without .html; also fixes local 404s on folder index pages
ignoreDeadLinks: true, // your notes will have broken links sooner or later; without this the build just fails
lastUpdated: true, // shows "last updated" at the bottom of each page
appearance: false, // dark mode switch. true = show the toggle; false = light only
// Turn this on after you have a custom domain; helps Google index you (delete this block if you haven't bought a domain yet)
sitemap: {
hostname: 'https://your-domain.com'
},
head: [
['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
],
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'About Me', link: '/about-me' },
{ text: 'Notes', link: '/logs/' },
],
// Scans the logs/ folder automatically to build the left sidebar; no need to write it by hand
sidebar: generateSidebar([{
documentRootPath: '/',
scanStartPath: 'logs',
resolvePath: '/logs/',
useTitleFromFileHeading: true, // use the file's H1 as the sidebar title
useFolderTitleFromIndexFile: true, // if the folder has an index.md, use its title
collapsed: true,
hyphenToSpace: true,
sortMenusByName: true,
}]),
outline: { label: 'On this page', level: [2, 3] },
aside: true,
socialLinks: [
{ icon: 'github', link: 'your GitHub link' }
],
lastUpdatedText: 'Last updated',
footer: {
message: 'your email',
copyright: `Copyright © ${new Date().getFullYear()} Your Name`
}
}
})About
appearance: I ended up setting my own site tofalse. The reason is that once you have a lot of custom styles, you have to tune both the light and dark versions, and maintenance doubles. If you're just using the default theme, go ahead and turn ontrue. VitePress's built-in dark mode looks good.About
sidebar: thesidebar: generateSidebar([...])form above only works when your whole site has a single automatic sidebar. The day you want to hand-write another one (say, a fixed-order table of contents for one column), you have to switch to the object form and spread the automatic one in with..., otherwise the two overwrite each other. The Detailed Version has a full example.
Create the matching files
The config lists paths, so those files need to exist, or clicking through gives you a blank page:
- In the root, create
index.md(home) andabout-me.md(About Me). - Make a new folder
logs, and inside it create anindex.mdplus a few notes.
Refresh the browser and the sidebar will be laid out automatically by your folder structure.
Adding images
Create a folder called public in the root (VitePress's dedicated place for static assets) and drop your images in.
When you reference them in Markdown, don't include public in the path:
Stage 4: Making it look good (CSS)
Create .vitepress/theme/custom.css:
:root {
--vp-c-brand-1: #4f5fd6; /* your brand colour */
}
/* Nav menu on the left, search/social icons stay on the right */
.VPNavBarMenu {
margin-right: auto !important;
margin-left: 24px !important;
}
/* Smaller home hero title; the default is a bit loud */
.VPHero .name { font-size: 38px !important; line-height: 44px !important; }
.VPHero .text { font-size: 26px !important; line-height: 32px !important; }Then create .vitepress/theme/index.ts to hook it in, or the CSS won't take effect at all (the most common beginner "I wrote the styles but nothing happens" is missing this step):
import DefaultTheme from 'vitepress/theme'
import './custom.css'
export default {
extends: DefaultTheme,
}Stage 5: Create .gitignore first, then push to GitHub
The order matters here. Do this before git add. I skipped it once, and over five thousand files in node_modules got committed. Cleaning that up later was a pain.
In the root, create a file named exactly .gitignore (with the dot at the front), with this content:
node_modules/
.vitepress/cache/
.vitepress/dist/
.env.localWhy:
node_modulesis tens of thousands of third-party library files, hundreds of MB, and Vercel reinstalls everything frompackage.jsonon its own. You don't need to upload it at all.⚠️ Note that
.gitignoreonly affects files you haven't committed yet. For files already committed, adding them to.gitignorewon't make them disappear. You have to remove them from the record by hand withgit rm -r --cached folder-name. So create it first, always.
Once it's created, push:
On GitHub, click + in the top right → New repository, name it
my-blog, Private or Public both work (Private doesn't affect Vercel deployment; the site is still publicly accessible). Do not tick any of the "Add README / Add .gitignore" initialisation options.Back in PowerShell:
git initgit add .git commit -m "first commit"git remote add origin https://github.com/your-username/my-blog.gitgit push -u origin main
mainormaster? GitHub's default branch is calledmainnow. If the push fails saying the branch doesn't exist, rungit branch -M mainto rename your local branch, then push again.The first push will pop up a window asking you to log in to GitHub. Just authorise it in the browser. If it asks you to set your identity:
bashgit config --global user.email "your-email@example.com"bashgit config --global user.name "Your Name"
From now on, every update is just these three:
git add .git commit -m "updated today's notes"git pushPhase 6: Go live (Vercel)
Log in to Vercel with your GitHub account.
Click Add New → Project, find your repo, and click Import.
Vercel usually detects VitePress on its own. Just hit Deploy.
The big gotcha (when the build fails): if you get
Permission Deniedor the build dies, set these by hand in the project settings:- 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 can't find the command because of executable permissions. Skip the shortcut and call that js file withnode, and permissions stop mattering.- Install Command:
How to check it worked: go back to the Vercel Dashboard and look at the project card
- Green Ready = success, and the card shows a preview of your site
- Blue Building = still running, wait a bit
- Red Error / Failed = failure. Click in, open Build Logs, and paste the error straight to an AI to ask about
Phase 7: Get your own domain (.com)
Buy one: get
yourname.comfrom Cloudflare or Namecheap. Cloudflare sells at cost with no markup.Add the domain in Vercel: project → Settings → Domains → enter your domain → Add.
Set up DNS with the values Vercel gives you:
⚠️ Always use the values shown on the Vercel page, never copy them from any tutorial online (including this one).
Vercel now assigns different addresses to different projects: older projects mostly get the A record
76.76.21.21, newer ones may get216.198.79.1or something else; thewwwCNAME has also changed from a singlecname.vercel-dns.comto a per-project string (liked1d4fc829fe7bc7c.vercel-dns-017.com). Get it wrong and verification simply won't pass.Follow the card Vercel shows you and add two records in your registrar's dashboard:
- A record: name
@, content = the IP Vercel shows - CNAME record: name
www, content = the string Vercel shows
- A record: name
Cloudflare-specific gotchas:
- Go to the SSL/TLS menu and set the encryption mode to Full (or Full strict). Otherwise you get an endless redirect loop and the site won't open.
- Set the little cloud icon on those two records to grey (DNS only) for now, and decide whether to turn on the orange proxy after Vercel verification passes.
Advanced: connect with Obsidian
Once deployed, manage this folder directly in Obsidian. Writing notes gets a lot faster.
Open Obsidian → bottom left "Open another vault" → "Open folder as vault" → pick your
my-blogroot folder.A few settings you have to change:
- Files & Links → Default location for new attachments →
Same folder as current file(images sit next to the note so the site can find them) - Files & Links → Use [[Wikilinks]] → turn it off (important! the site only understands standard Markdown
[description](path), not double brackets) - Editor → Default view mode →
Live Preview
- Files & Links → Default location for new attachments →
Install the GitHobs plugin so you can push to GitHub from inside Obsidian without going back to the terminal.
Advanced: Chinese and English
If you want a bilingual site (English at the root, Chinese under /zh/), add locales in config.mts:
export default defineConfig({
title: "Your Name", // English (default language, no URL prefix)
locales: {
root: { label: 'English', lang: 'en-US' },
zh: {
label: '简体中文',
lang: 'zh-CN',
link: '/zh/',
title: '你的名字',
themeConfig: {
nav: [
{ text: '首页', link: '/zh/' },
{ text: '关于我', link: '/zh/about-me' },
],
},
},
},
// ... the rest of the config
})Then put the Chinese pages in a zh/ folder (zh/index.md, zh/about-me.md, ...) and the matching English pages at the root. The nav bar will show a language switcher automatically.
Gotcha: VitePress assumes the two languages have symmetric paths. If some folder only has a Chinese version and no English one (like my
logs/), clicking the language switch on that page 404s, and you'd need extra code to catch it. So either build both sides, or accept that part being in one language only.
Troubleshooting
npm : cannot load file xxx\npm.ps1 because running scripts is disabled on this system
Windows blocks script execution by default. Turn it on:
- Search
PowerShellin the Start menu → right-click → Run as administrator (this step matters) - Enter:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser- Type
Yand press Enter when it asks for confirmation - Close the admin window, go back to your normal window, and run the command again
Changed custom.css but nothing on the page changed
You almost certainly missed .vitepress/theme/index.ts (see Phase 4). The CSS file only takes effect if that entry file imports it.
Works locally, but clicking into some folder on Vercel 404s
Check whether config.mts has cleanUrls: true.
Build error: dead link
VitePress treats dead links as fatal errors by default. Add ignoreDeadLinks: true.
Command cheat sheet
| Command | What it does |
|---|---|
ls | List what's in the current folder |
cd path | Enter a folder, e.g. cd C:\Users\chuan\my-blog |
cd .. | Go up one level |
npm run dev | Local preview (auto-refreshes when you edit files) |
npm run build | Build once locally to check for errors |
git status | See which files changed |
git add . + git commit -m "..." + git push | The three-step push |
💡 A note to the reader
"Believe in yourself."
Before I built this site, I stared at the terminal with a blank mind, no idea what I was looking at. A day later it was fine. You can do it too.