---
contentId: b1b99d95-ac6d-4f25-a121-0851988102a2
part: 1
title: "Getting Started with VitePress: Project Setup and Essentials"
description: From setup to styling with Tailwind CSS and automatic Vue imports, build your content-driven site effortlessly.
github:
  branch: 01.project-initialization
date: 2024-10-10
seriesSlug: create-a-blog-with-vitepress-and-vue-js-from-scratch
---

Before embarking on creating our blog, it is essential to understand what [**VitePress**](https://vitepress.dev/) is and its origins. Familiarity with the **tools** we utilize for our blog creation is crucial.

## VitePress

According to the [homepage](https://vitepress.dev/):

> Vite & Vue Powered Static Site Generator, Markdown to Beautiful Docs in Minutes

While the tagline's use of "docs" might suggest VitePress is exclusively for documentation websites, it can create any content-centric website.

The ["What is VitePress?"](https://vitepress.dev/guide/what-is-vitepress) section explains:

> VitePress is a Static Site Generator (SSG) designed for building fast, content-centric websites. In a nutshell, VitePress takes your source content written in Markdown, applies a theme to it, and generates static HTML pages that can be easily deployed anywhere.

In essence, VitePress builds upon a basic **Vite** and **Vue** application, similar to what you could generate with `npx create-vite --template vue`. However, VitePress offers much more.

It introduces three key features to the standard Vite and Vue application:

1. **Markdown Support**: VitePress comes with a pre-configured **Markdown to HTML compiler** based on markdown-it. It inherently supports **frontmatter**, **syntax highlighting**, GitHub-style alerts, **emojis**, **Vue components**, and more. It leverages a comprehensive **configuration with numerous plugins**. You can review the [**source code**](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for more insight.
2. **Data Loading**: VitePress enables [**data loading**](https://vitepress.dev/guide/data-loading) from the **file system**, networks, or any other sources. This potent feature facilitates the creation of **dynamic websites** using a **static site generator**.
3. **Pre-rendering at Build-time**: VitePress operates as a **Single Page Application (SPA)**, enhancing **User Experience (UX)** but challenging **Search Engine Optimization (SEO)**. However, due to its markdown-centric **static content** nature, VitePress **pre-renders pages during build-time**, resulting in **static HTML files**. This approach is excellent for SEO while maintaining SPA benefits for UX. It cleverly employs Server Side Rendering (SSR) capabilities of Vue, which you can observe in the [**source code**](https://github.com/vuejs/vitepress/blob/main/src/client/app/ssr.ts#L10).

These elements constitute VitePress's foundation, making it ideal for creating blogs, documentation, and other content-focused websites. While it supports dynamic data, that aspect will be explored in another series.

Equipped with a default theme, VitePress facilitates attractive documentation websites. The default theme, available for exploration in the [VitePress documentation](https://vitepress.dev/) and its [source code](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default), is simply a built-in Vue library comprising components, composables, and CSS, easy to override for creating custom themes.

Understanding the tagline's real implication clarifies why VitePress is chosen for developing a blog; it's a versatile tool for content-centric websites beyond just documentation.

![VitePress Architecture](/series/create-a-blog-with-vitepress-and-vue-js-from-scratch/getting-started-with-vitepress-project-setup-and-essentials/vitepress-architecture.png)



> [!NOTE]
> Attempting to utilize a custom Vite and Vue application is ill-advised. VitePress's complexity and configuration management save considerable time, both now and during future blog updates.



### History

Developed by [Evan You](https://x.com/youyuxi) alongside Vite, VitePress tested Vite in a real-world setting, ensuring its practicality and user-friendliness. VitePress evolved from its predecessor VuePress, upgrading from Webpack and Vue 2 to Vite and Vue 3, offering significant performance and developer experience enhancements.

VitePress is popular for creating documentation sites or blogs like [The Vue Point](https://blog.vuejs.org/), the official Vue.js blog. Its thin layer over Vite ensures it remains highly extendable and customizable, with assurances of continued support.

## Initializing the project

Armed with a better understanding of VitePress, we can initiate a fresh project called "**Garabit**." You can access the **source code** on [barbapapazes/garabit](<https://github.com/barbapapazes/garabit>).

Despite being initially tailored for documentation sites within existing projects, the installation process could be smoother. I have highlighted this in two pull requests on the VitePress repository: [feat(cli): support custom npm scripts prefix](https://github.com/vuejs/vitepress/pull/4271) and [feat(cli): support custom `srcDir`](https://github.com/vuejs/vitepress/pull/4270).

First, create a folder for our project:

```bash [terminal]
mkdir garabit
```

Then, initialize **npm** inside this folder and install VitePress:

```bash [terminal]
pnpm init
pnpm add -D vitepress
```



> [!NOTE]
> Throughout this series, I will use [`pnpm`](https://pnpm.io/) as the package manager, but you can adapt the commands for your preferred package manager.



Finally, scaffold the VitePress project:

```bash [terminal]
pnpm vitepress init
```

Respond to the prompts (press enter for default values, which we will adjust later):

```bash [terminal]
┌  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 pnpm run docs:dev and start writing.
```

## Exploring the project

We now have a freshly minted VitePress project. Let's examine the **project structure**:

```bash [terminal]
.
├── .vitepress
│   └── config.mts
├── api-examples.md
├── index.md
├── markdown-examples.md
├── package.json
└── pnpm-lock.yaml
```

The root level contains our Markdown files, representing our blog's pages, with filenames (and directories) corresponding to page URLs. `index.md` serves as the homepage. Although this structure is basic, we will refine it in future articles.

Being content-focused, VitePress's configuration and theme-related elements reside within the `.vitepress` directory, where the `config.mts` file configures the theme, plugins, data loading, and more, written in **TypeScript**. We will delve into this in upcoming articles.

## Enhancing the developer experience (DX)

While suitable for documentation websites, our custom blog requires additional dependencies to enhance the developer experience (DX). We will incorporate two dependencies:

- [**Tailwind CSS**](https://tailwindcss.com/): A utility-first **CSS framework** for efficiently crafting custom designs.
- [**unplugin-vue-components**](https://github.com/unplugin/unplugin-vue-components): A Vite plugin for **automatic Vue components import**.

### Tailwind CSS

We will leverage Tailwind CSS for styling our custom theme. This utility-first CSS framework offers powerful, user-friendly design capabilities.

Begin by installing **Tailwind CSS**:

```bash [terminal]
pnpm add -D tailwindcss postcss autoprefixer
```

Create the configuration file for Tailwind CSS:

```bash [terminal]
npx tailwindcss init -p
```

We'll configure Tailwind CSS as we progress.

### Auto-import Vue components

We'll use unplugin-vue-components for automatic Vue component importation, a **Vite plugin** enabling on-demand component importation. This automated process significantly saves time by eliminating manual importation per file. Components are not globally available, mitigating performance impact, as our files are transformed via a rollup plugin, adding an import at the file's top solely if the component is utilized, a testament to the on-demand philosophy.

First, install **unplugin-vue-components**:

```bash [terminal]
pnpm add -D unplugin-vue-components
```

Then, integrate it into the `config.mts` file:

```typescript [config.mts]
import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
  vite: {
    plugins: [Components()],
  },
})
```

We will configure unplugin-vue-components more thoroughly later.

## Ready for the next step

With our VitePress project now featuring **Tailwind CSS** and **unplugin-vue-components**, we are poised to begin developing our blog.

In the subsequent article, we will examine **VitePress fundamentals** and craft a personalized theme for our blog.
