提交 d213dbb6 编写于 作者: E Evan You

sidebar: auto

上级 01e258f0
---
sidebar: self
sidebar: auto
---
# Config Reference
......
---
sidebar: self
sidebar: auto
---
# Default Theme Config
::: tip
All options listed on this page apply to the default theme only. If you are using a custom theme, the options may be different.
:::
## Navbar Links
You can add links to the navbar via `themeConfig.nav`:
......@@ -79,9 +83,9 @@ module.exports = {
Sidebar groups are collapsable by default. You can force a group to be always open with `collapsable: false`.
### Multi Category Sidebars
### Multiple Sidebars
If you wish to display different sidebars for different group of pages, you will first need to organize your pages into directories:
If you wish to display different sidebars for different group of pages, first organize your pages into directories:
```
.
......@@ -120,6 +124,16 @@ module.exports = {
}
```
### Auto Sidebar for Single Pages
If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use YAML frontmatter on that page:
``` md
---
sidebar: auto
---
```
## Homepage
## GitHub Repo and Edit Links
......
......@@ -4,7 +4,7 @@ next: ./assets
sidebarDepth: 2
---
# Site Configurations
# Configuration
## Config File
......@@ -25,154 +25,6 @@ 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.
:::
A VuePress theme is responsible for all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now) which is designed for technical documentation. It exposes a number of options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the [Default Theme Config](../default-theme-config/) page.
### 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.
There are a few color variables you can tweak:
``` stylus
// showing default values
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
```
If you wish to develop a custom theme, see [Custom Themes](./custom-themes.md).
......@@ -48,9 +48,11 @@ export default {
const { themeConfig } = this.$site
const { frontmatter } = this.$page
return (
themeConfig.sidebar &&
!frontmatter.home &&
frontmatter.sidebar !== false
frontmatter.sidebar === 'auto' || (
themeConfig.sidebar &&
!frontmatter.home &&
frontmatter.sidebar !== false
)
)
}
},
......
......@@ -76,7 +76,7 @@ function resolveOpenGroupIndex (route, items) {
function resolveSidebarItems (page, route, site) {
const pageSidebarConfig = page.frontmatter.sidebar
if (pageSidebarConfig === 'self') {
if (pageSidebarConfig === 'auto') {
return resolveHeaders(page)
}
const { pages, themeConfig } = site
......@@ -98,7 +98,7 @@ function resolveHeaders (page) {
collapsable: false,
title: page.title,
children: headers.map(h => ({
type: 'self',
type: 'auto',
title: h.title,
basePath: page.path,
path: page.path + '#' + h.slug,
......
......@@ -8,15 +8,15 @@ export default {
// use custom active class matching logic
// due to edge case of paths ending with / + hash
const selfActive = isActive($route, item.path)
// for sidebar: self pages, a hash link should be active if one of its child
// for sidebar: auto pages, a hash link should be active if one of its child
// matches
const active = item.type === 'self'
const active = item.type === 'auto'
? selfActive || item.children.some(c => isActive($route, item.basePath + '#' + c.slug))
: selfActive
const link = renderLink(h, item.path, item.title || item.path, active)
const configDepth = $page.frontmatter.sidebarDepth || $site.themeConfig.sidebarDepth
const maxDepth = configDepth == null ? 1 : configDepth
if (item.type === 'self') {
if (item.type === 'auto') {
return [link, renderChildren(h, item.children, item.basePath, $route, maxDepth)]
} else if (active && item.headers && !hashRE.test(item.path)) {
const children = groupHeaders(item.headers)
......
......@@ -94,7 +94,7 @@ h1, h2, h3, h4, h5, h6
&:first-child
margin-top -1.5rem
margin-bottom 1rem
+ p, + pre
+ p, + pre, + .custom-block
margin-top 2rem
&:hover .header-anchor
opacity: 1
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册