If you wish to apply simple overrides to the styling of the default theme, you can create an `.vuepress/override.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
You can add links to the navbar via `themeConfig.nav`:
There are a few color variables you can tweak:
``` js
// .vuepress/config.js
module.exports={
themeConfig:{
nav:[
{text:'Home',link:'/'},
{text:'Guide',link:'/guide/'},
{text:'External',link:'https://google.com'},
]
}
}
```
``` stylus
// showing default values
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
## Sidebar
To enable the sidebar, use `themeConfig.sidebar`. The basic configuration expects an Array of links:
``` js
// .vuepress/config.js
module.exports={
themeConfig:{
sidebar:[
'/',
'/page-a',
['/page-b','Explicit link text']
]
}
}
```
You can omit the `.md` extension, and paths ending with `/` are inferred as `*/README.md`. The text for the link is automatically inferred (either from the first header in the page or explicit title in YAML frontmatter). If you wish to explicitly specify the link text, use an Array in form of `[link, text]`.
### Nested Header Links
The sidebar automatically displays links for headers in the current active page, nested under the link for the page itself. You can customize this behavior using `themeConfig.sidebarDepth`. The default depth is `1`, which extracts the `h2` headers. Setting it to `0` disables the header links, and the max value is `2` which extracts both `h2` and `h3` headers.
A page can also override this value in using YAML frontmatter:
``` md
---
sidebarDepth: 2
---
```
### Sidebar Groups
You can divide sidebar links into multiple groups by using objects:
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
{
title: 'Group 1',
collapsable: false,
children: [
'/'
]
},
{
title: 'Group 2',
children: [ /* ... */ ]
}
]
}
}
```
## Options Reference
Sidebar groups are collapsable by default. You can force a group to be always open with `collapsable: false`.
### Multi Category Sidebars
### logo
If you wish to display different sidebars for different group of pages, you will first need to organize your pages into directories:
### nav
```
.
├─ README.md
├─ foo
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ README.md
├─ three.md
└─ four.md
```
### search
Then, with the following sidebar config:
### sidebar
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: {
// sidebar for pages under /foo/
'/foo/': [
'',
'one',
'two'
],
// sidebar for pages under /bar/
'/bar/': [
'',
'three',
'four'
]
}
}
}
```
### sidebarDepth
## Homepage
### editLinks
## GitHub Repo and Edit Links
### docsDir
Providing `themeConfig.repo` auto generates a GitHub link in the navbar and "Edit this page" links at the bottom of each page.
### docsBranch
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
// Assumes GitHub. Can also be a full GitLab url.
repo: 'vuejs/vuepress',
// if your docs are not at the root of the repo
docsDir: 'docs',
// optional, defaults to master
docsBranch: 'master',
// defaults to true, set to false to disable
editLinks: true
}
}
```
## Simple CSS Override
If you wish to apply simple overrides to the styling of the default theme, you can create an `.vuepress/override.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system, and a default theme optimized for writing technical documentation. In fact, it was created to support the documentation needs of Vue's own sub projects.
VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system, and a default theme optimized for writing technical documentation. It was created to support the documentation needs of Vue's own sub projects.
A VuePress site is in fact a Single-Page Application (SPA) powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). If you've used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).
When deployed, each page has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, Vue takes over the static content and turns it into a full SPA. Additional pages are fetched on demand as the user navigates around the site.
Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, however, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site.
## How It Works
A VuePress site is in fact a powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). If you've used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).
During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/).
Each markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your markdown files and is great when you need to embed dynamic content.
...
...
@@ -39,6 +39,8 @@ VuePress is still a work in progress. There are a few things that it currently d
- PWA Support
- Blogging support
Contributions are welcome!
## Why Not ...?
### Nuxt
...
...
@@ -47,8 +49,8 @@ Nuxt is capable of doing what VuePress does, but it is designed for building app
### Docsify / Docute
Both are great projects and also Vue-powered. Except they are both completely runtime-driven and thus not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices.
Both are great projects and also Vue-powered. Except they are both completely runtime-driven and therefore not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices.
### Hexo
Hexo is great - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure.
Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure.
Since your markdown files are compiled into Vue components via webpack, you can safely reference any asset using relative paths on your file system:
All markdown files are compiled into Vue components and processed by webpack, therefore you can and **should prefer** referencing any asset using relative URLs:
``` md
![logo][./logo.png]
![An image][./image.png]
```
This would work the same way as if you are referencing it inside a `*.vue` file template. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build.
This would work the same way as in `*.vue` file templates. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build.
In addition, you can use the `~` prefix to explicitly indicate this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies:
``` md
![Iamge from alias][~@assets/image.png]
![Iamge from dependency][~some-dependency/image.png]
```
## Public Files
Sometimes you may need to provide some static assets that are not directly referenced in any of your markdown or theme components - for example, favicons and PWA icons. In such cases you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
Sometimes you may need to provide static assets that are not directly referenced in any of your markdown or theme components - for example, favicons and PWA icons. In such cases you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
## Base URL
...
...
@@ -25,8 +32,10 @@ If your site is deployed to a non-root URL, you will need to set the `base` opti
With a base URL, if you want to reference an image in `.vuepress/public`, you'd have to use URLs like `/bar/image.png`. However, this is brittle if you ever decide to change the `base` later. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue's prototype) that generates the correct path:
```md
```vue
<img:src="$withBase('/foo.png')"alt="foo">
```
In addition, if a `base` is set, all asset URLs in `.vuepress/config.js` will get the base automatically prepended as well.
Note you can use the above syntax not only in theme components, but in your markdown files as well.
In addition, if a `base` is set, it is automatically prepended to all asset URLs in `.vuepress/config.js` options.
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.
The essential file for configuring a VuePress site is `.vuepress/config.js`, which should export a JavaScript object:
``` js
module.exports={
title:'Hello VuePress',
description:'Just playing around'
}
```
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.
Consult the [Config Reference](../config/) for a full list of options.
## Theme Configuration
::: tip NOTE
Configurations below are applicable to the default theme only. If you are using a custom theme, the theme config options may be different.
:::
### Navbar Links
You can add links to the navbar via `themeConfig.nav`:
``` js
// .vuepress/config.js
module.exports={
themeConfig:{
nav:[
{text:'Home',link:'/'},
{text:'Guide',link:'/guide/'},
{text:'External',link:'https://google.com'},
]
}
}
```
### Sidebar
To enable the sidebar, use `themeConfig.sidebar`. The basic configuration expects an Array of links:
``` js
// .vuepress/config.js
module.exports={
themeConfig:{
sidebar:[
'/',
'/page-a',
['/page-b','Explicit link text']
]
}
}
```
You can omit the `.md` extension, and paths ending with `/` are inferred as `*/README.md`. The text for the link is automatically inferred (either from the first header in the page or explicit title in YAML frontmatter). If you wish to explicitly specify the link text, use an Array in form of `[link, text]`.
### Nested Header Links
The sidebar automatically displays links for headers in the current active page, nested under the link for the page itself. You can customize this behavior using `themeConfig.sidebarDepth`. The default depth is `1`, which extracts the `h2` headers. Setting it to `0` disables the header links, and the max value is `2` which extracts both `h2` and `h3` headers.
A page can also override this value in using YAML frontmatter:
``` md
---
sidebarDepth: 2
---
```
### Sidebar Groups
You can divide sidebar links into multiple groups by using objects:
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
{
title: 'Group 1',
collapsable: false,
children: [
'/'
]
},
{
title: 'Group 2',
children: [ /* ... */ ]
}
]
}
}
```
Sidebar groups are collapsable by default. You can force a group to be always open with `collapsable: false`.
### Multi Category Sidebars
If you wish to display different sidebars for different group of pages, you will first need to organize your pages into directories:
```
.
├─ README.md
├─ foo
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ README.md
├─ three.md
└─ four.md
```
Then, with the following sidebar config:
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: {
// sidebar for pages under /foo/
'/foo/': [
'',
'one',
'two'
],
// sidebar for pages under /bar/
'/bar/': [
'',
'three',
'four'
]
}
}
}
```
### Homepage
### GitHub Repo and Edit Links
``` js
// .vuepress/config.js
module.exports = {
themeConfig: {
// Assumes GitHub. Can also be a full GitLab url.
repo: 'vuejs/vuepress',
// if your docs are not at the root of the repo
docsDir: 'docs',
// optional, defaults to master
docsBranch: 'master'
}
}
```
### Simple CSS Override
If you wish to apply simple overrides to the styling of the default theme, you can create an `.vuepress/override.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
By default the built files will be in `.vuepress/dist`, which can be configured via the `dest` field in `.vuepress/config.js`. The built files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services.
## Basic Configurations
Right now our 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.
The essential file for configuring a VuePress site is `.vuepress/config.js`, which simply exports a JavaScript object:
Because VuePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the [universal code requirements](https://ssr.vuejs.org/en/universal.html). In short, make sure to only access Browser / DOM APIs in `beforeMounted` or `mounted` hooks.
