Create a Static Website Using VitePress
This post will cover how to create a static website using VitePress.
Before using VitePress you must install Node.js v18 or higher.
Initialize the VitePress Project
Add vitepress dependency
# create a directory |
VitePress is used in the development process as a build tool. It converts your Markdown files to HTML files. You don’t need VitePress in runtime.
Scaffold a basic project
$ npx vitepress init |
npx can run your installed package directly, you don’t need to add any npm script to your
package.json
. You also can donpx package_command
by usingnpm run your_script
.
You need to set some basic configuration for your website.
- Setting the VitePress directory.
./
means using the current directory as the project root directory. - Setting your site title.
- Setting your site description.
- Other configurations just use the default settings.
┌ Welcome to VitePress! |
Running the project
Start a local server
npm run docs:dev |
Visiting http://localhost:5173
to access the website
Git Configurations
Initialize the git repository
$ cd my-site |
Config gitignore
You need to ignore the .vitepress/cache
directory. Others are common ignore folders.
Edit .gitignore
vim .gitignore |
Add the following content to the .gitignore
file.
.idea |
VitePress Configurations
Site Config
1. Edit site config
The site configuration file is .vitepress/config.mts
vim .vitepress/config.mts |
Use the following config
import {type DefaultTheme, defineConfig} from 'vitepress' |
2. Move index.md
(home page) to src
folder
$ mkdir src/ && mv index.md src/ |
3. Add your favicon image logo.jepg
(the same as the filename in site config) to the src/public/
directory.
srcDir
Move the home page index.md
to src/index.md
$ mkdir src/ |
export default defineConfig({ |
srcExclude
Optional config. If you need to add excluded directories and files.
export default defineConfig({ |
For example:
docs/**
,index-en.md
lastUpdated
export default defineConfig({ |
Head
Shortcut icon
export default defineConfig({ |
src/public/logo.jepg
Theme Config
1. Edit the theme config
The theme configuration file is also .vietpress/config.mts
Add theme config content to .vietpress/config.mts
import {type DefaultTheme, defineConfig} from 'vitepress' |
2. Add your home page logo my-logo.png
(the same as filename in config) to the src/public
directory
The logo is in the upper left corner of the homepage.
You can also use the favicon image you added before as the home page logo.
3. Add the Example page markdown file src/example/index.md
# Example |
Logo
export default defineConfig({ |
src/public/your-logo.png
Local Search
export default defineConfig({ |
Outline
export default defineConfig({ |
Home Page Config
Config home page in src/index.md
Image
hero: |
src/public/your-home-image.png
Feature Icons
features: |
Other Config
Favicon
Put your website icon to src/public/favicon.ico
Deployment
Create a repository on GitHub
Create button on the right top bar of GitHub -> New repository
Enter your repository name. For example, my-site
Click the “Create Repository” button.
Commit your local repository to GitHub
git add . |
Deploy your project on Vercel
Go to Vercel website.
Click the “Add New” button -> Project -> Import Git Repository
Add permission to access the new GitHub repository to Vercel
After finishing the permission configuration, you can find the new GitHub repository on Vercel.
Select the repository. And click “Import”
Override “Build and Output Settings”
- Build Command:
npm run docs:build
oryarn docs:build
- Output Directory:
.vitepress/dist
Click “Deploy”
After the deployment process is finished, you can visit your website by Vercel provided URL.