# VuePress Tutorial 6 - Homepage Layout

By: J the Code Monkey

•Posted: Feb 3, 2022 •Updated: Jul 10, 2024

# What is a VuePress Theme?

In this tutorial we'll be discussing how to configure the homepage layout by using the options exposed by the default theme (opens new window) which comes with the installation of VuePress (opens new window) and is designed for technical documentation. Along with the homepage the default theme (opens new window) also allows customization for the navbar, sidebar, search box, etc. We'll discuss those customizations in more detail in future tutorials.

Before moving on to the homepage layout, we're going to first describe what a theme is. If you remember from the VuePress Tutorial 2 - Why Use VuePress? post, a VuePress (opens new window) theme allows you to control how your project is structured. Within a theme you are able to create directories that handle global components, components, layouts, styles, and templates. You can also create files for theme configuration and app level enhancements. So, a theme handles all of the layout and interactivity details for your site.

Now that we have a good understanding of what a theme is, let's move on to configuring the homepage layout.

# Homepage Layout

To see the homepage layout in action you can take a look at the homepages of the VuePress (opens new window) site and the Code Monkeys Blog.

Using a Custom Theme

Since the options being used for the homepage are provided by the default theme (opens new window), they may be different if you're using a custom theme (opens new window).

Make sure you start the local development server which should be running at http://localhost:8080/ (opens new window) to see the changes to your site. If the changes aren't appearing after you save them, then try restarting your local development server.

# Using the Homepage Layout

To use the homepage layout open the README.md file in the docs directory of your project then you need to add home: true to a YAML (opens new window) frontmatter block at the top of the page.

We're also going to remove the # Hello VuePress line from the file since we're going to start customizing the homepage.

The README.md file now looks like this:

Before discussing the changes to the site, let's first describe what YAML (opens new window) and frontmatter are.

# YAML Frontmatter Blocks

YAML (opens new window) is a recursive acroynym for "YAML Ain't Markup Language", and it's a human-readable data serialization language that can be used with a wide variety of programming languages. Frontmatter is structured metadata that allows you to add variables to your pages.

The YAML (opens new window) frontmatter block support comes with the installation of VuePress (opens new window) and is processed using the frontmatter parser gray-matter (opens new window).

When you add a YAML (opens new window) frontmatter block to a page you need to declare it at the top of a Markdown file, and the content must adhere to proper YAML (opens new window) formatting between a set of triple-dashed lines, i.e., --- like the example above.

Within the triple-dashed lines you are able to set predefined variables (opens new window), predefined variables powered by the default theme (opens new window), and you can define your own custom variables. These variables can then be accessed within the current page by using the $frontmatter (opens new window) variable. We'll be discussing and adding predefined and custom variables and using the $frontmatter (opens new window) variable as we continue to develop the site.

If you have any questions, then check out the Frontmatter (opens new window) documentation.

# Alternative Frontmatter Formats

VuePress (opens new window) also supports JSON (opens new window) and TOML (opens new window) frontmatter syntax.

We'll be using the YAML (opens new window) syntax throughout the tutorials, but if you're interested here's how to set the homepage layout using the other supported syntaxes.

For JSON (opens new window) the frontmatter needs to start and end with curly brackets:

For TOML (opens new window) the frontmatter needs to be explicitly marked as toml:

Now that we have a better understanding of YAML (opens new window) frontmatter blocks, let's discuss the changes to the site after specifying the homepage layout.

# Homepage Layout Changes

Before specifying the homepage layout, the HTML for the homepage consists of the following:

The highlighted lines refer to what gets changed after specifying the homepage layout.

After specifying the homepage layout, the HTML for the homepage consists of the following:

Here are the changes in the HTML after specifying the homepage layout:

Line 3: The initial title tag that was set to Hello VuePress | Code Monkeys is now set to Code Monkeys.
Line 15: The initial main tag had a class of "page", and it now has a class of "home" and an attribute of aria-labelledby="main-title".
Line 16: The initial child elements of the div tag are removed since the # Hello VuePress line was removed from the README.md file, and the div tag is moved to line 25 with an added class of "custom". Line 16 now consists of a header tag with a class of "hero", and the child tags of <h1 id="main-title">Code Monkeys</h1> and <p class="description">" Learn to Code like a Monkey... "</p>.
Line 22: The initial footer tag is removed from the page.

# Adding an Image

Before adding a homepage image, we're going to first create a public directory inside of the .vuepress directory.

The directory structure for your site should now look something like this:

.
├── .yarn (Optional)
│   ├── releases
│   │   └── yarn-1.22.17.cjs
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   └── config.js
│   └── README.md
├── node_modules
├── .gitattributes (Optional)
├── .gitignore
├── .yarnrc (Optional)
├── LICENSE
├── package.json
├── README.md
└── yarn.lock

The public directory is a static resource directory which is useful in the following cases:

You need to provide static assests that aren't directly referenced in any of your Markdown or component files, e.g., favicons and PWA icons which we'll discuss in more detail in future tutorials.
You need to serve shared static assets that are referenced outside of your site, e.g., logo images.
You want to reference images using absolute URLs in your Markdown and component files.

In a future tutorial we'll discuss what absolute URLs are in more detail as well as relative URLs, the base URL, and how to use aliases. If you're interested in learning more now, then check out the Assest Handling (opens new window) documentation.

The image we're going to be adding to the homepage is the Code Monkeys full logo. We're going to create an images directory in the public directory. Then we're going to create a code-monkeys-logos directory inside of the images directory. These directories are optional, but will be helpful for organizational purposes when we add more images in the future. Now inside of the code-monkeys-logos directory, we're going to add the full Code Monkeys logo which is named code-monkeys-full-logo.png.

After adding those directories and the image, the directory structure for your site should now look something like this:

.
├── .yarn (Optional)
│   ├── releases
│   │   └── yarn-1.22.17.cjs
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   │   ├── images
│   │   │   │   ├── code-monkeys-logos
│   │   │   │   │   └── code-monkeys-full-logo.png
│   │   └── config.js
│   └── README.md
├── node_modules
├── .gitattributes (Optional)
├── .gitignore
├── .yarnrc (Optional)
├── LICENSE
├── package.json
├── README.md
└── yarn.lock

Here's the full Code Monkeys logo:

You can download the logo right here from your browser, and it will also be in the tutorial-6 branch of the code-monkeys-blog-tutorials (opens new window) repository.

The logo was created using Canva (opens new window). The site offers a lot of features for free, but some features and images require payment after your free trial is expired. A good alternative to use is GIMP (opens new window).

Here are some other useful online image tools:

Here are some useful resources for coming up with color schemes and palettes for your site:

It's also important to reduce the file sizes of your images by using compression. This will help to optimize your site's bundle size, save bandwidth, and decrease the loading time for your images. Canva (opens new window) and GIMP (opens new window), and some of the other image tools mentioned above offer the ability to compress your images.

Here are some other useful online tools for image compression:

After adding the logo to the site, we can reference the logo in our homepage by adding heroImage: /images/code-monkeys-logos/code-monkeys-full-logo.png to the frontmatter.

Notice you don't need to include .vuepress/public in the path to the logo because whenever you reference assets stored in the public directory it's added automatically.

The README.md file now looks like this:

The homepage image is added as a child element of the <header> tag that has a class of "hero".

Here's what the HTML looks like after adding the homepage image:

# Adding a Title

Since we already added a site title property in the config.js file, we already have a title on the homepage which has the same value as the site title property.

If you prefer to have the site title property and the title on the homepage to be different, then you can add heroText: Homepage Title to the frontmatter.

The README.md file would look like this:

For the Code Monkeys Blog we'll be using the value of the site title property for the homepage title, so the README.md file will look the same as before:

Here's the HTML with the homepage title highlighted:

# Adding a Tagline

Since we already added a site description property in the config.js file, we already have a tagline on the homepage which has the same value as the site description property.

If you prefer to have the site description property and the tagline on the homepage to be different, then you can add tagline: Your tagline to the frontmatter.

We're going to update the tagline on the homepage from the value of the site description to be tagline: Let's get down to Monkey Business.

The README.md file now looks like this:

Here's the HTML with the homepage tagline highlighted:

# Adding an Action Button

An action button provides a link to a preferred page on your site, and it's placed directly below the tagline.

To add an action button you need to add actionText: Text on Action Button and actionLink: /preferred-page/ to the frontmatter.

We're going to add the actionText: Learn to Code like a Monkey → and the actionLink: /topics/ to the homepage of the site.

The README.md file now looks like this:

Here's the HTML with the action button highlighted:

404 When Clicking the Action Button

If you click the action button, it will show the 404 layout because we haven't set up the route to /topics/. In a future tutorial we'll create the Topics page which will fix this issue.

# Adding Features

Features are text that get displayed under the action button that are used to provide a summary of what your site is about.

You can add as many features as you like, but the recommended number is three. Using three features looks the best with the default styling, and it gives a user a quick introduction to your site.

Here's the format for adding features with titles and details to the frontmatter of your page:

We're going to be adding only the feature titles to the homepage of the site.

The README.md file now looks like this:

Here's the HTML with the features highlighted:

A footer typically contains:

Authorship Information
Copyright Information
Contact Information
Sitemap (Important Links Regardless of Current Page - Similar to Global Navbar)

Here's how to add a footer to the frontmatter of your page:

We're not going to be adding a footer using the frontmatter in the homepage for the site. Instead we're going to be creating a Footer component in a future tutorial that sticks to the bottom of the page.

If you do decide to add a footer using the frontmatter in the homepage, then the HTML will look like this:

# Final Homepage Layout

Here's the contents of the README.md file for the homepage after adding all of the desired frontmatter:

The contents of your README.md file may be different depending on what metadata you decide to use in the frontmatter of your homepage.

# Homepage Layout Notes

Here are some general notes about the homepage layout:

You can disable any frontmatter by setting any of the options to null.
Any content after the frontmatter block gets parsed as normal Markdown and will be rendered after the features section.
You can also use a fully custom homepage layout. We'll discuss how to use a Custom Layout for Specific Pages (opens new window) in a future tutorial.

# Next Steps

In the next tutorial we'll discuss how to configure the navbar that comes with the default theme (opens new window).

# VuePress Tutorial 6 - Homepage Layout

# What is a VuePress Theme?

# Homepage Layout

# Using the Homepage Layout

# YAML Frontmatter Blocks

# Alternative Frontmatter Formats

# Homepage Layout Changes

# Adding an Image

# Adding a Title

# Adding a Tagline

# Adding an Action Button

# Adding Features

# Adding a Footer

# Final Homepage Layout

# Homepage Layout Notes

# Next Steps