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, an entire ecosystem of frameworks makes 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:
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 to a custom domain.
Now, go forth and document!
Additional reading
VitePress
Getting Started
Using Vue in Markdown
Extending the Default Theme
Top comments (1)
Good stuff, Charles!