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
$ mkdir my-site
$ cd my-site

# add vitepress to devDependencies
$ npm add -D vitepress
# or
$ yarn add -D vitepress

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 do npx package_command by using npm 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!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

Running the project

Start a local server

npm run docs:dev
# or
yarn docs:dev
# or
npx vitepress dev

Visiting http://localhost:5173 to access the website

Git Configurations

Initialize the git repository

$ cd my-site
$ git init .

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

# macOS
.DS_Store

# vitepress
.vitepress/cache

# Dependency directories
node_modules/

# build output
dist

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'

export default defineConfig({
	title: '{my_title}',
	description: '{my_description}',
	srcDir: 'src',
	srcExclude: [
		'someDir/**',
		'someFile',
	],
	// Whether to get the last updated timestamp for each page using Git.
	lastUpdated: true,
	// favicon of the website
	head: [
		['link', {rel: 'shortcut icon', type: "image/jpeg", href: '/logo.jpeg'}],
		// These two are what you want to use by default
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "72x72", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "114x114", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "144x144", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon-precomposed', type: "image/jpeg", href: '/logo.jpeg'}],
		// This one works for anything below iOS 4.2
		['link', {rel: 'apple-touch-icon-precomposed apple-touch-icon', type: "image/jpeg", href: '/logo.jpeg'}],
	],
	themeConfig: {
		//TODO
	}
})

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/
$ mv index.md src/

export default defineConfig({
  
  srcDir: 'src',
  
})

srcExclude

Optional config. If you need to add excluded directories and files.

export default defineConfig({
  
  srcExclude: [
    'someDir/**',
    'someFile',
  ],
  
})

For example:

• docs/**,
• index-en.md

lastUpdated

export default defineConfig({
  
  // Whether to get the last updated timestamp for each page using Git.
  lastUpdated: true,
  
})

Head

Shortcut icon

export default defineConfig({

	head: [
		['link', {rel: 'shortcut icon', type: "image/jpeg", href: '/logo.jpeg'}],
		// These two are what you want to use by default
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "72x72", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "114x114", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon', type: "image/jpeg", sizes: "144x144", href: '/logo.jpeg'}],
		['link', {rel: 'apple-touch-icon-precomposed', type: "image/jpeg", href: '/logo.jpeg'}],
		// This one works for anything below iOS 4.2
		['link', {rel: 'apple-touch-icon-precomposed apple-touch-icon', type: "image/jpeg", href: '/logo.jpeg'}],
		],

})

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'

export default defineConfig({
  // site config added before
  // ...
  themeConfig: {
    nav: nav(),
    sidebar: {
	    '/example/': sidebarExample()
    },
    // Logo in the upper left corner of the homepage
    logo: {src: '/my-logo.png', width: 24, height: 24},
    search: {
      provider: 'local'
    },
    outline: {
      level: "deep"
    },
  }
})

function nav(): DefaultTheme.NavItem[] {  
    return [  
        {text: 'Home', link: '/'},  
        {text: 'Example', link: '/example/'},  
    ];  
}  
  
function sidebarExample(): DefaultTheme.SidebarItem[] {  
    return [  
       {text: 'Examples', link: '/example/index.md'},  
    ]  
}

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  
  
This is an example page.

Logo

export default defineConfig({
  themeConfig: {
    
    logo: {src: '/your-logo.png', width: 24, height: 24},
    
  }
})

src/public/your-logo.png

Local Search

export default defineConfig({
  themeConfig: {
    
    search: {
      provider: 'local'
    },
    
  }
})

Outline

export default defineConfig({
  themeConfig: {
    
    outline: {
      level: "deep"
    },
    
  }
})

Home Page Config

Config home page in src/index.md

Image

hero:
  image:
    src: your-home-image.png
    alt: your-home-image

src/public/your-home-image.png

Feature Icons

features:
  - icon: 🚀
    title: 
    details: 

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 .
git commit -m '🎉feat: First commit'
git remote add origin git@github.com:{your_username}/{repo_name}.git
git branch -M main
git push -u origin main

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 or yarn docs:build
• Output Directory: .vitepress/dist

Click “Deploy”

After the deployment process is finished, you can visit your website by Vercel provided URL.