Create a Static Website Using VitePress

Posted on Edited on In ,

This post will cover how to create a static website using VitePress.

Before using VitePress you must install Node.js v18 or higher.

Initialize VitePress Project

Add vitepress dependency

$ 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 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

Add the .vitepress/cache directory to .gitignore

.vitepress/cache

Result .gitignore

.idea

# macOS
.DS_Store

# vitepress
.vitepress/cache

# Dependency directories
node_modules/

# build output
dist

VitePress Configurations

Site Config

The site configuration file is .vitepress/config.mts

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,
	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: {
		//...
	}
})
$ mkdir src/ && mv index.md src/

Files

  • src/public/logo.jepg

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,
  
})

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

The theme configuration file is also .vietpress/config.mts

import {type DefaultTheme, defineConfig} from 'vitepress'

export default defineConfig({
  themeConfig: {
    nav: nav(),
    sidebar: {
	    '/example/': sidebarExample()
    },
    
    logo: {src: '/your-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: '/examples.md'},
	]
}

Files

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

src/public/your-logo.png

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.