From d213dbb6f6b3e4f0ab2ff443f68118c1cfc308c8 Mon Sep 17 00:00:00 2001 From: Evan You Date: Fri, 13 Apr 2018 13:05:31 -0400 Subject: [PATCH] sidebar: auto --- docs/config/README.md | 2 +- docs/default-theme-config/README.md | 20 +++- docs/guide/basic-config.md | 154 +--------------------------- lib/default-theme/Layout.vue | 8 +- lib/default-theme/Sidebar.vue | 4 +- lib/default-theme/SidebarLink.vue | 6 +- lib/default-theme/styles/theme.styl | 2 +- 7 files changed, 32 insertions(+), 164 deletions(-) diff --git a/docs/config/README.md b/docs/config/README.md index 8a29ea26..0067ef89 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -1,5 +1,5 @@ --- -sidebar: self +sidebar: auto --- # Config Reference diff --git a/docs/default-theme-config/README.md b/docs/default-theme-config/README.md index 205f3ea7..f1777548 100644 --- a/docs/default-theme-config/README.md +++ b/docs/default-theme-config/README.md @@ -1,9 +1,13 @@ --- -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 diff --git a/docs/guide/basic-config.md b/docs/guide/basic-config.md index 63c0354d..dce7a357 100644 --- a/docs/guide/basic-config.md +++ b/docs/guide/basic-config.md @@ -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). diff --git a/lib/default-theme/Layout.vue b/lib/default-theme/Layout.vue index 2160d9f2..06de9e3d 100644 --- a/lib/default-theme/Layout.vue +++ b/lib/default-theme/Layout.vue @@ -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 + ) ) } }, diff --git a/lib/default-theme/Sidebar.vue b/lib/default-theme/Sidebar.vue index d3ebb8ac..2e2f7064 100644 --- a/lib/default-theme/Sidebar.vue +++ b/lib/default-theme/Sidebar.vue @@ -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, diff --git a/lib/default-theme/SidebarLink.vue b/lib/default-theme/SidebarLink.vue index a6e93c06..97788764 100644 --- a/lib/default-theme/SidebarLink.vue +++ b/lib/default-theme/SidebarLink.vue @@ -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) diff --git a/lib/default-theme/styles/theme.styl b/lib/default-theme/styles/theme.styl index 5d79c701..882a5e40 100644 --- a/lib/default-theme/styles/theme.styl +++ b/lib/default-theme/styles/theme.styl @@ -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 -- GitLab