The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"`. It should always start and end with a slash.
The `base` is automatically prepended to all the URLs that start with `/` in other options, so you only need to specify it once.
Title for the site. This will be the prefix for all page titles, and displayed in the navbar in the default theme.
### description
- Type: `string`
- Default: `undefined`
Description for the site. This will be rendered as a `<meta>` tag in the page HTML.
### head
- Type: `Array`
- Default: `[]`
Extra tags to be injected to the page HTML `<head>`. Each tag can be specified in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon:
``` js
module.exports={
head:[
['link',{rel:'icon',href:`/logo.png`}]
]
}
```
### port
- Type: `number`
- Default: `8080`
Specify the port to use for the dev server.
### dest
- Type: `string`
- Default: `.vuepress/dist`
Specify the output directory for `vuepress build`.
### ga
- Type: `string`
- Default: `undefined`
Provide the Google Analytics ID to enable integration.
### pwa
- Type: `boolean`
- Default: `false`
Set to `true` to enable PWA support. VuePress will automatically generate and register a service worker that caches the content for offline use in production.
::: warning
Only enable this if you are able to deploy your site with SSL, since service worker can only be registered under HTTPs URLs.
:::
## Theming
### theme
- Type: `string`
- Default: `undefined`
Specify this to use a custom theme. With the value of `"foo"`, VuePress will attempt to load the theme component at `node_modules/vuepress-theme-foo/Layout.vue`.
### themeConfig
Also see [config options for the default theme](../default-theme-config/).
- Type: `Object`
- Default: `{}`
Provide config options to the used theme. The options will vary depending on the theme you are using.
Options for [postcss-loader](https://github.com/postcss/postcss-loader). Note specifying this value will overwrite autoprefixer and you will need to include it yourself.
### configureWebpack
- Type: `Object | Function`
- Default: `undefined`
Modify the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to be merged:
``` js
module.exports={
configureWebpack:(config,isServer)=>{
if(!isServer){
// mutate the config for client
}
}
}
```
### chainWebpack
- Type: `Function`
- Default: `undefined`
Modify the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
``` js
module.exports={
chainWebpack:(config,isServer)=>{
// config is an instance of ChainableConfig
}
}
```
## Browser Compatibility
### evergreen
- Type: `boolean`
- Default: `false`
Set to `true` if you are only targeting evergreen browsers. This will disable ES5 transpilation and polyfills for IE, and result in faster builds and smaller files.
All options listed on this page apply to the default theme only. If you are using a custom theme, the options may be different.
:::
## Homepage
The default theme provides a homepage layout (which is used on [the homepage of this very website](/)). To use it, specify `home: true` plus some other metadata in your root `README.md`'s YAML front matter. This is the actual data used on this site:
``` yaml
---
home: true
heroImage: /hero.png
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.
You can add links to the navbar via `themeConfig.nav`:
...
...
@@ -134,7 +155,18 @@ sidebar: auto
---
```
## Homepage
Any additional content after the front matter will be parsed as normal markdown and rendered after the features section.
## Prev / Next Links
Prev and next links are automatically inferred based on the sidebar order of the active page. You can also explicitly overwrite or disable them using YAML front matter:
@@ -11,45 +11,17 @@ VuePress uses Vue single file components for custom themes. To use a custom layo
From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme.
## Using Theme from a Dependency
Themes can be published on npm as `vuepress-theme-xxx`.
To use a theme from an npm dependency, provide a `theme` option in `.vuepress/config.js`:
``` js
module.exports={
theme:'awesome'
}
```
VuePress will attempt to locate and use `node_modules/vuepress-theme-awesome/Layout.vue`.
## Content Outlet
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content:
``` html
<template>
<divclass="theme-container">
<Content/>
</div>
</template>
```
In addition to rendering the markdown content, the `<Content/>` component is also responsible for setting the title and other metadata of a specific page.
## Site and Page Metadata
The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively in `$site` and `$page` properties which are injected into every component in the app.
The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively as `this.$site` and `this.$page` properties which are injected into every component in the app.
This is the value of `$site` of this very website:
``` json
{
"title":"VuePress",
"description":"Minimalistic docs generator with Vue component based layout system",
"base":"/vuepress/",
"description":"Vue-powered Static Site Generator",
"base":"/",
"pages":[
{
"path":"/",
...
...
@@ -67,10 +39,39 @@ This is the `$page` object for this page you are looking at:
``` json
{
"path":"/theming.html",
"title":"Custom Theme",
"path":"/custom-themes.html",
"title":"Custom Themes",
"headers":[/*...*/],
"frontmatter":{}
}
```
If the user provided `themeConfig` in `.vuepress/config.js`, it will also be available as `$site.themeConfig`. You can use this to allow users to customize behavior of your theme - for example, specifying categories and page order. You can then use these data together with `$site.pages` to dynamically construct navigation links.
Finally, don't forget that `this.$route` and `this.$router` are also available as part of Vue Router's API.
## Content Outlet
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content:
``` html
<template>
<divclass="theme-container">
<Content/>
</div>
</template>
```
## Using Theme from a Dependency
Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`.
To use a theme from an npm dependency, provide a `theme` option in `.vuepress/config.js`:
``` js
module.exports={
theme:'awesome'
}
```
VuePress will attempt to locate and use `node_modules/vuepress-theme-awesome/Layout.vue`.
The following guides assumes you are placing your docs inside the `docs` directory of your project and using the default build output location.
## GitHub Pages
1. Set `base` in `.vuepress/config.js` to your repository's name. For example, if your repository is `https://github.com/foo/bar`, the deployed pages will be available at `https://foo.github.io/bar`. In this case, you should set `base` to `"/bar/"`.
