# VuePress Tutorial 5 - Configuration Basics
# Adding a Config File
Currently, the site consists of a homepage with a title saying "Hello VuePress" and a search box provided by the default theme (opens new window) which builds an index from all h2 and h3 markdown (opens new window) headers and from the title and tags included in the frontmatter (opens new window) of pages.
We'll be discussing the default theme (opens new window), markdown (opens new window), and frontmatter (opens new window) in more detail in future tutorials.
To see your site be sure to start the local development server which should be running at http://localhost:8080/ (opens new window).
The site is working, but it doesn't have a lot of functionality or customization. To add more functionality and customization like site navigation with a navbar, a site title, a site description, favicons, etc. we need to add a config file.
Before adding the config file, let's first create a .vuepress directory in the docs directory. The .vuepress directory will be used to store all VuePress (opens new window) specific directories and files.
The directory structure for your site should now look something like this:
.
├── .yarn (Optional)
│ ├── releases
│ │ └── yarn-1.22.17.cjs
├── docs
│ ├── .vuepress
│ └── README.md
├── node_modules
├── .gitattributes (Optional)
├── .gitignore
├── .yarnrc (Optional)
├── LICENSE
├── package.json
├── README.md
└── yarn.lock
Now inside of the .vuepress directory, let's add a config.js file.
After adding the config.js file, the directory structure for your site should now look something like this:
.
├── .yarn (Optional)
│ ├── releases
│ │ └── yarn-1.22.17.cjs
├── docs
│ ├── .vuepress
│ │ └── config.js
│ └── README.md
├── node_modules
├── .gitattributes (Optional)
├── .gitignore
├── .yarnrc (Optional)
├── LICENSE
├── package.json
├── README.md
└── yarn.lock
The config.js file should export a JavaScript object like the following:
If you run into any issues when adding the directory and file above, then be sure to check out the Configuration (opens new window) documentaion.
Alternative Config Formats
In this series we'll be using a JS config file format, i.e., .vuepress/config.js. However, VuePress (opens new window) also supports the following config file formats: YAML - .vuepress/config.yml, TOML - .vuepress/config.toml, and TS - .vuepress/config.ts. If you want to use TS, then you need to have a VuePress (opens new window) version of 1.9.0+ installed. See the TypeScript as Config (opens new window) documentation for more details.
# Config File Properties
Now that we have added a config.js file, we can begin to add more functionality and customization to the site by setting some of the basic config file properties.
The properties we'll be setting will be using the <head>, <meta>, and <title> tags. To learn more about these tags check out the following references: HTML <head> Tag (opens new window), HTML <meta> Tag (opens new window), and HTML <title> Tag (opens new window).
As we develop the site we'll be adding more config file properties as needed. For a full list of the available config file properties check out the Config Reference (opens new window).
# Title
The title property is used to define the title for the site. The provided value is used to prefix all page titles, and it gets shown in the navbar when using the default theme (opens new window) as a link to the homepage.
The expected type is a string, and the default value is undefined.
Now let's set the title of the site:
After adding the title and saving the file, you should see Code Monkeys or whatever value you set as your site's title in the top left of the navbar as a link to the homepage.
You can also inspect the page, go to the Elements tab, open the <head> tag, and you'll see the following:
The value of the <title> tag will be whatever you set as the value for the title of your site.
Removing Hello VuePress
When we update the homepage in the next tutorial, we'll remove the Hello VuePress | from the <title> tag.
# Description
The description property is used to define the description for the site. The provided value is used in a <meta> tag in the <head> tag of the site.
The expected type is a string, and the default value is undefined.
Now let's set the description of the site:
After adding the description and saving the file, you can inspect the page, go to the Elements tab, open the <head> tag, and you'll see the following:
The value of the content attribute will be whatever you set as the value for the description of your site.
# Head
The head property is used to inject extra tags into the <head> tag of the site.
The expected type is an array, and the default value is [].
You can specify a tag to inject into the <head> tag by using the following form: [tagName, { attr1Name: attr1Value, attr2Name: attr2Value, ... }].
Here are some examples of what can be injected into the <head> tag:
- Author of the Site
- Favicons
- Social Media Metadata
- Links to External Style Sheets
- Client-Side Scripts
To start we'll set an author by using a <meta> tag in the <head> tag:
After adding the author and saving the file, you can inspect the page, go to the Elements tab, open the <head> tag, and you'll see the following:
To change the author for your site you can use a different value for the content attribute.
We'll be injecting more tags into the <head> tag as we develop the site.
# Updated Config File
Here's the content of the config.js file after adding the title, description, and author:
Be sure to substitute the values with the preferred values for your site.
# Next Steps
In the next tutorial we'll discuss the homepage layout provided by the default theme (opens new window).