How to build a beautiful docs site with VitePress and Render

Charles Watkins — Thu, 26 Oct 2023 14:26:11 +0000

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 and deploy it to the internet with Render.

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 account
A free Render account
Some familiarity with Git and web development

Scaffold your docs site with VitePress

1. Create a directory for your VitePress project.



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 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, 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.

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. Check the box to add a README.md and .gitignore file with the Node template, as VitePress doesn't include them by default.

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.

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, add content by creating additional Markdown files, build or import custom themes, and put your project on a custom domain.

Now, go forth and document!

Additional reading

VitePress

Getting Started
Using Vue in Markdown
Extending the Default Theme

Render

Static sites
Deploying a commit
Build previews

DEV Community: Charles Watkins