How to build a beautiful docs site with VitePress and Render
Tags: tutorial, documentation, webdev, writing
Published: 2023-10-26 14:26:11

Good documentation is one of the best ways to give your project instant credibility. Sure, you could stick it all in a README for a smaller project. That's fine. For larger projects, you'll want features like navigation, interactivity, search, and maybe even embedded videos. You'll also want something that looks good because presentation matters. 

Thankfully, there's an entire ecosystem of frameworks that make docs sites easy to build and services that make static sites easy to deploy. In this post, you'll learn how to build a docs site with [VitePress](https://vitepress.dev/) and deploy it to the internet with [Render](https://render.com).

VitePress is a highly customizable Vue-based static site generator for building docs sites. Think Docusaurus but with Vue instead of React. Render is a Platform-as-a-Service that makes deploying a web service or static site as easy as a few clicks (literally) via Git-based deployments with GitLab and GitHub. Think Heroku, but still free and easier to use. Using Vitepress and Render, you can build a fully functional (and surprisingly good-looking) docs site in moments. 

Before you get started, you’ll need:


- A free [GitHub](https://github.com/) account
- A free [Render](https://dashboard.render.com/register) account
- Some familiarity with Git and web development

### Scaffold your docs site with VitePress
#### 1. Create a directory for your VitePress project.

```bash
mkdir my-awesome-site 
cd my-awesome-site
```

#### 2. Scaffold your VitePress project using their installation wizard. 

I recommend using the Default Theme because it looks great and is highly configurable. 

```
npx vitepress init
```

The scaffolded VitePress project will contain two types of files: a single configuration file and three [Markdown](https://www.markdownguide.org/getting-started/) files: `index.md`, `markdown-examples.md`, and `api-examples.md`. 

The `index.md` file serves as your homepage, while the other two demonstrate using common VitePress features. You can customize the content of the Markdown files to begin writing your docs and add additional ones. 

You can use the configuration file to set a custom theme, update the title and description on the home page, and update the sidebar that appears on all doc pages. VitePress employs [file-based routing](https://vitepress.dev/guide/routing#file-based-routing), meaning the `index.md` file serves as the main entry point at your-docs-domain and `markdown-examples.md` is accessible at your-domain/markdown-examples.html.

#### 3. Install the `vitepress` package and run the app locally
Add the `vitepress` dependency to project and run it locally. VitePress will serve a development version of your docs site on `localhost:5173` by default. 

```
yarn add -D vitepress
yarn docs:dev
```

Navigate to http://localhost:5173. You should have a surprisingly beautiful docs site with three pages.  

![Starter VitePress docs site running on localhost:5173](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3bj6ia45vahtvolnxgla.png)

If you're having issues running `yarn docs:dev` make sure that you've added VitePress using `yarn add -D vitepress`. VitePress' installation wizard may not have installed VitePress as a package. 

### Push your project to GitHub
Now that we’re happy with our site, let’s put it on GitHub. 

#### 1. Create a GitHub repo for your docs site
Create a repo in GitHub–if you're new to using GitHub or need a quick refresher, check out their docs on [creating a repo in GitHub](https://docs.github.com/en/get-started/quickstart/create-a-repo). Check the box to add a `README.md` and `.gitignore` file with the Node template, as VitePress doesn't include them by default. 


![Creating a GitHub repository with name of my-awesome-docs, description of My awesome docs. The Add README file box is checked. The add .gitignore has node selected.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wcyy14lpvnw5wnrat7o3.png)

#### 2. Push your project to GitHub
Now that you have a remote repository, it's time to push your code to GitHub. 

First, add `.vitepress/cache` to your .gitignore file to ignore the cache created when you ran the project locally.

Next initialize git, save a commit, and push it to GitHub. 

```
git init
git add .
git commit -m "first commit"
git remote add origin <YOUR REPOSITORY>
git push -u origin main
```

Make sure to replace `<YOUR REPOSITORY>` with your newly created GitHub repository.

### Deploy your docs site with Render
#### 1. Create a Static Site on Render
Go to the Render dashboard and click **Create a new Static Site** page. To the right, you’ll see an option to connect your GitHub (or GitLab) account. Click **+ Connect account**  to grant Render access to the GitHub repo you made a few moments ago. You'll see your repository appear in a list with a **Connect** button. Click **Connect**. 

#### 2. Configure your deployment
Once you’ve connected your repository, you’ll be asked to configure how it should be deployed. Give your docs site a name and specify your build command and publish directory. 

Set the build command to ` yarn install; yarn docs:build`.

Set the publish directory to `.vitepress/dist`. 

![Configuration screen for a new static site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7erhrmr2juogkv5vwp54.png)

By default, Render sets the Node version to 14.17.0. VitePress requires Node version 18+. Click the **Advanced** dropdown button and click the **Add Environmental Variable** button. Set the key to NODE_VERSION and the value to 18.14.1–the latest LTS version of Node. 

#### 3. Deploy the docs site to Render
Click the **Create Static Site** button. Render will build and deploy your docs site to a custom onrender.com domain. Once the deployment process is finished, you can check out the live site. Here's mine: https://vitepress-demo-vt0r.onrender.com.

Going forward, Render will automatically build and deploy your docs site whenever you merge code into your main.
### Now what?

In this tutorial, you learned how to build a docs site with VitePress and deploy it with Render, but there’s still more to do. You can [update the home page](https://vitepress.dev/reference/default-theme-home-page), add content by creating additional Markdown files, [build or import](https://vitepress.dev/guide/custom-theme) custom themes, and put your project to a [custom domain](https://render.com/docs/custom-domains).

Now, go forth and document!

### Additional reading
#### VitePress
[Getting Started](https://vitepress.dev/guide/getting-started)
[Using Vue in Markdown](https://vitepress.dev/guide/using-vue)
[Extending the Default Theme](https://vitepress.dev/guide/extending-default-theme)
#### Render
[Static sites](https://render.com/docs/static-sites)
[Deploying a commit](https://render.com/docs/deploy-a-commit)
[Build previews](https://render.com/docs/pull-request-previews)