For this article, let’s use the manual installation method.
You have now created a documentation site. You will notice that VuePress offers a clean, minimalist default theme out of the box. However, it’s highly customizable, giving you the creative freedom to craft a unique look and feel for your website.
VuePress follows a straightforward directory structure for organizing documentation. Inside your project folder, you’ll find the docs directory we created, where you can create Markdown (.md
) files for your documentation pages.
To enhance the organization of your documentation, you can create dedicated folders for related documentation pages. For instance, you can create a folder called guide and organize it with specific guides like using-kinsta-stsh.md . When you employ this structure, the content in using-kinsta-stsh.md becomes accessible via a URL like http://localhost:8080/guide/using-kinsta-stsh.
Once you’ve created your documentation site with content, you might find it challenging to navigate, especially if you have many files to manage. However, VuePress allows you to customize the navigation structure of your site to make it more user-friendly and organized.
Styling VuePress allows you to customize the appearance of your site through styles. You can either override the default styles using some defined variables or define your style. To do either, create a styles folder in the .vuepress folder
To apply simple overrides to the styling of the default preset or define some variables to use later, you can create a palette.styl file in .vuepress/styles . These are some predefined variables you can tweak:
// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px
These variables can be used to maintain consistent styling throughout your site. VuePress also provides a convenient way to add extra styles. You can create an index.styl file in .vuepress/styles folder where you can use normal CSS syntax :
.content {
font-size 30px
}
Read more about styling VuePress in the official documentation.
Using Components VuePress supports the use of components to enhance the functionality and appearance of your pages. You can create Vue components and include them in your Markdown files. Create a
components folder in .vuepres, and then any *.vue
files found in .vuepress/components are automatically registered as global components.
For instance, consider creating two components, HomeOptions.vue and HostingBanner.vue :
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vue
Within these vue.js component files, you can add CSS codes. Let’s add code to the HomeOptions.vue and HostingBanner.vue components.
Add the code below to HomeOptions.vue :
Also, add the code below to HostingBanner.vue :
Host Your Static Site With Kinsta for Free!
Read More
Inside any Markdown file, you can then directly use the components (names are inferred from filenames):
Read more about components in VuePress in the documentation.
Customize Homepage In VuePress, the default theme offers a pre-designed homepage layout that you can use to create an engaging and informative starting point for your site. To make use of this homepage layout, you need to specify home: true
and include some additional metadata in the YAML frontmatter of your root README.m d file.
Here’s an example of the YAML frontmatter:
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---
All these configurations make your documentation homepage look like this:
VuePress default homepage. It’s worth noting that you can disable the heroText
and tagline
or any other value by setting their corresponding fields to null
if you prefer a simpler layout or not including it. Any content you include after the YAML frontmatter (i.e., the metadata section) will be treated as regular Markdown and will be rendered following the features section.
If you want a fully custom homepage layout, VuePress also supports Custom Layouts. Additionally, you can create a rich-text footer by using Markdown Slot Syntax, offering more flexibility in displaying footer content. Here’s an example of how to set a rich-text footer:
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
In this case, the content within the ::: slot footer
section allows you to include links and additional information in the footer area of your homepage.
Now that you understand how to perform the above customizations, add the components created earlier to the Homepage and remove some options so the Homepage looks better:
---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
Using components on the VuePress homepage. By following these VuePress customization techniques, you can create a documentation site that not only provides valuable content but also offers an excellent user experience with organized navigation and appealing styling.
You can read more about customizing the default theme in the documentation.
Building a Blog Section With VuePress Adding a blog section to your VuePress site is a breeze since VuePress allows you to write custom Vue components that can be inserted into any Markdown files. Let’s create a component that will render the list of blog posts.
Create a BlogIndex.vue file in the components folder and add the following code:
:to="post.path">{{ post.frontmatter.title }}
{{ post.frontmatter.description }}
:to="post.path">Read more
In the provided code snippet, you define a Vue template that loops through your blog posts using v-for
, displaying the post title, description, and a “Read more” link for each post.
The script section exports a Vue component that computes and retrieves the blog posts. These posts are filtered based on their path (starting with /blog/
) and the absence of a blog_index
frontmatter attribute. They are then sorted by date in descending order to present the latest posts first.
When you create new blog posts, you’ll need to specify the post date as part of the frontmatter information. This will help sort the posts so that the newest posts appear first.
To store the blog posts, create a folder named blog at the project’s root. In this folder, add a README.md file. This is going to be the blog index, and this is where you’ll include the BlogIndex
component to list all blog posts.
---
blog_index: true
---
# Blog
Welcome To Our Blog
Ensure to add the blog_index
frontmatter attribute, as it is instrumental in ensuring that the blog index itself is not listed among the individual blog posts. This attribute is utilized when filtering the posts in the posts computed property of the BlogIndex.vue component.
Next, create a blog folder at the root of your project that will store all blog posts and create each post. For example, create a first-post.md file and add the following markdown content:
---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.
For each blog post, ensure that you define essential frontmatter settings, such as the post title, date, and other relevant metadata. This meticulous organization ensures your blog posts are presented cohesively and provides a compelling reading experience for your audience.
Adding blog to VuePress. Finally, you can add the blog navigation to your navbar in the .vuepress/config.js file:
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
There is a lot more you can do with VuePress, such as adding plugins , using a separate theme , or even creating your own theme .
Deploy VuePress Static Site To Kinsta Kinsta allows you to host up to 100 static websites for free . This can be done by pushing your code to your preferred Git provider (Bitbucket , GitHub , or GitLab ) and then deploying it to Kinsta.
Info Static Site Hosting is a free service to deploy your static site, and it’s currently in BETA. To use it before it becomes generally available, join the Kinsta Research Program and gain access to all beta features released by Kinsta. You can then contribute back to Kinsta by reporting bugs and leaving feedback.
Before pushing your files to any Git provider, create a .gitignore file in the root of your project to specify the files and folders Git should ignore when pushing your code:
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/public
Info You can configure another location for the VuePress SSG to build into by adding a destination in .vuepress/config.js using dest
e.g., dest: 'public',
.
For this guide, we use GitHub. Create a repository on GitHub to push your source code . Once your repo is ready, follow these steps to deploy your static site to Kinsta:
Log in or create an account to view your MyKinsta dashboard. Authorize Kinsta with your Git provider. Click Static Sites on the left sidebar, then click Add site . Select the repository and the branch you wish to deploy from. Assign a unique name to your site. Add the build settings in the following format:Build command: npm run build
Node version: 16.20.0
Publish directory: ./docs/.vuepress/dist
or public
Finally, click Create site . And that’s it! You now have a deployed site within a few seconds. A link is provided to access the deployed version of your site. You can later add your custom domain and SSL certificate if you wish.
As an alternative to Static Site Hosting, you can opt for deploying your static site with Kinsta’s Application Hosting , which provides greater hosting flexibility, a wider range of benefits, and access to more robust features. For example, scalability, customized deployment using a Dockerfile, and comprehensive analytics encompassing real-time and historical data.
Summary VuePress is a versatile and powerful tool for creating fast documentation and blog sites. With its simple setup, customizable themes, and plugins, you can build an informative and visually appealing platform for your audience.
Start creating your VuePress site today and share your knowledge with the world by hosting on our Static Site Hosting for free!
Have you utilized VuePress to build anything? Feel free to share your projects and experiences with us in the comments section below.
Get all your applications , databases , and WordPress sites online and under one roof. Our feature-packed, high-performance cloud platform includes:
Easy setup and management in the MyKinsta dashboard 24/7 expert support The best Google Cloud Platform hardware and network, powered by Kubernetes for maximum scalability An enterprise-level Cloudflare integration for speed and security Global audience reach with up to 35 data centers and 260 PoPs worldwide Get started with a free trial of our Application Hosting or Database Hosting . Explore our plans or talk to sales to find your best fit.
Joel Olawanle Joel is a Frontend developer working at Kinsta as a Technical Editor. He is a passionate teacher with love for open source and has written over 200 technical articles majorly around JavaScript and it’s frameworks.