Configuration

Config File

Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let’s first create a .vuepress directory inside your docs directory. This is where all VuePress-specific files will be placed in. Your project structure is probably like this:

  1. .
  2. ├─ docs
  3. │  ├─ README.md
  4. │  └─ .vuepress
  5. │     └─ config.js
  6. └─ package.json

The essential file for configuring a VuePress site is .vuepress/config.js, which should export a JavaScript object:

  1. module.exports = {
  2.   title: 'Hello VuePress',
  3.   description: 'Just playing around'
  4. }

If you’ve got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, h2 and h3 headers from all the pages.

Check out the Config Reference for a full list of options.

Alternative Config Formats

You can also use YAML (.vuepress/config.yml) or TOML (.vuepress/config.toml) formats for the configuration file.

Theme Configuration

A VuePress theme owns all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now), designed for technical documentation. It exposes many options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the Default Theme Config page.

To develop a custom theme, see Writing a theme.

App Level Enhancements

Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file .vuepress/enhanceApp.js, which will be imported into the app if it’s present. The file should export default a hook function which will receive an object containing some app-level values. You can use this hook to install extra Vue plugins, register global components, or add extra router hooks:

  1. export default ({
  2.   Vue, // the version of Vue being used in the VuePress app
  3.   options, // the options for the root Vue instance
  4.   router, // the router instance for the app
  5.   siteData, // site metadata
  6.   isServer // is this enhancement applied in server-rendering or client
  7. }) => {
  8.   // ...apply enhancements to the app
  9. }

Related: