前言
默认主题的配置通过可以通过 themeConfig选项进行配置,且只对默认主题生效。如果你在使用一个自定义主题,选项可能会有不同。
项目创建
- Step 1: Create and change into a new directory
mkdir project-starter cd project-starter
- Step2:Initialize your project
git init yarn init # OR git init npm init
- Step3:Install VuePress locally
yarn add -D vuepress@next # OR npm install -D vuepress@next
- Step 4: Add some scriptsopen in new window to
package.json
{ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } }
- Step 5: Add the default temp and cache directory to
.gitignore
file
echo 'node_modules' >> .gitignore echo '.temp' >> .gitignore echo '.cache' >> .gitignore
- Step 6: Create your first document
mkdir docs echo '# Hello VuePress' > docs/README.md
- Step 7: Serve the documentation site in the local server
yarn docs:dev ## OR npm run docs:dev
- Step 8: VuePress webpack dev server is listening at http://localhost:8080/
目录结构
├─ docs │ ├─ .vuepress │ │ └─ config.js │ └─ README.md ├─ .gitignore └─ package.json
配置
你可能已经注意到了,在 VuePress 配置中有一项 themeConfig
配置项,在 themeConfig
外部的配置项属于 站点配置 ,而在 themeConfig
内部的配置项则属于 主题配置。
站点配置
- base
- lang
- title
- description
- head
- locales
目录配置
- dest
- temp
- cache
- public
打包工具配置
- bundler
- bundlerConfig
Markdown 配置
- anchor
- assets
- code
开发配置项
- debug
- host
- port
- open
- pagePatterns
- templateDev
- templateSSR
- shouldPreload
- shouldPrefetch
插件配置
- plugins
主题配置
主题配置将会被 VuePress 主题来处理,所以它取决于你使用的主题是什么,也就是说取决于你theme
的配置。
- theme
- themeConfig
默认主题
如果你没有设置 VuePress 配置的 theme
配置项,则代表使用的是默认主题。默认主题配置主要从目录结构、首页、导航栏、侧边栏、搜索框等方面进行讲解。
目录结构
docs ├─.vuepress │ ├─.cache │ │ ├─default-development │ │ └─default-production │ ├─.temp │ │ ├─internal │ │ ├─pages │ │ │ ├─en │ │ │ │ ├─guide │ │ │ │ └─pages │ │ │ │ ├─about │ │ │ │ ├─cli │ │ │ │ ├─components │ │ │ │ ├─course │ │ │ │ ├─outsource │ │ │ │ ├─project │ │ │ │ │ ├─angular │ │ │ │ │ ├─micrcservice │ │ │ │ │ ├─react │ │ │ │ │ ├─vue │ │ │ │ │ └─wechat │ │ │ │ ├─standard │ │ │ │ ├─store │ │ │ │ ├─study │ │ │ │ ├─templates │ │ │ │ ├─tools │ │ │ │ └─videos │ │ │ ├─guide │ │ │ └─pages │ │ │ ├─about │ │ │ ├─cli │ │ │ ├─components │ │ │ ├─course │ │ │ │ ├─backend │ │ │ │ ├─deploy │ │ │ │ ├─design │ │ │ │ ├─frontend │ │ │ │ ├─operate │ │ │ │ ├─project │ │ │ │ ├─prototype │ │ │ │ ├─test │ │ │ │ └─ui │ │ │ ├─outsource │ │ │ ├─project │ │ │ │ ├─angular │ │ │ │ ├─micrcservice │ │ │ │ ├─react │ │ │ │ ├─vue │ │ │ │ └─wechat │ │ │ ├─standard │ │ │ ├─store │ │ │ ├─study │ │ │ ├─templates │ │ │ ├─tools │ │ │ └─videos │ │ └─styles │ ├─components │ ├─config │ │ ├─headConfig │ │ ├─localesConfig │ │ │ ├─en │ │ │ └─zh │ │ ├─markdownConfig │ │ ├─pluginsConfig │ │ └─themeConfig │ │ ├─locale │ │ │ ├─en │ │ │ └─zh │ │ ├─navbar │ │ ├─sidebar │ │ └─themePlugins │ ├─dist │ │ ├─assets │ │ │ ├─css │ │ │ ├─img │ │ │ └─js │ │ ├─en │ │ │ ├─guide │ │ │ └─pages │ │ │ ├─about │ │ │ ├─cli │ │ │ ├─components │ │ │ ├─course │ │ │ ├─outsource │ │ │ ├─project │ │ │ │ ├─angular │ │ │ │ ├─micrcservice │ │ │ │ ├─react │ │ │ │ ├─vue │ │ │ │ └─wechat │ │ │ ├─standard │ │ │ ├─store │ │ │ ├─study │ │ │ ├─templates │ │ │ ├─tools │ │ │ └─videos │ │ ├─ercode │ │ ├─guide │ │ ├─images │ │ │ ├─doc │ │ │ └─home │ │ └─pages │ │ ├─about │ │ ├─cli │ │ ├─components │ │ ├─course │ │ ├─outsource │ │ ├─project │ │ │ ├─angular │ │ │ ├─micrcservice │ │ │ ├─react │ │ │ ├─vue │ │ │ └─wechat │ │ ├─standard │ │ ├─store │ │ ├─study │ │ ├─templates │ │ ├─tools │ │ └─videos │ ├─public │ │ ├─ercode │ │ └─images │ │ ├─doc │ │ └─home │ ├─styles │ └─theme │ ├─components │ ├─global-components │ ├─layouts │ ├─styles │ └─util ├─en │ ├─guide │ └─pages │ ├─about │ ├─cli │ ├─components │ ├─course │ ├─outsource │ ├─project │ │ ├─angular │ │ ├─micrcservice │ │ ├─react │ │ ├─vue │ │ └─wechat │ ├─standard │ ├─store │ ├─study │ ├─templates │ ├─tools │ └─videos ├─guide └─pages ├─about ├─cli ├─components ├─course ├─outsource ├─project │ ├─angular │ ├─micrcservice │ ├─react │ ├─vue │ └─wechat ├─standard ├─store ├─study ├─templates ├─tools └─videos
首页
默认的主题提供了一个首页(Homepage)的布局,需要使用它需要在项目的docs>README.md
的 YAML front matter 指定 home: true
,如果不使用的内容你可以通过设置null
来禁用,YAML front matter
内容将会以普通的 markdown 被渲染,并插入到 YAML front matter
的后面。
--- home: true heroImage: /hero.png heroText: 快智岛 标题 tagline: 快智岛副标题 actionText: 快速上手 → actionLink: /zh/guide/ features: - title: 简洁至上 details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。 - title: Vue驱动 details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。 - title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。 footer: MIT Licensed | Copyright © 2021-present Xunzhaotech ---
导航栏
导航栏可能包含你的页面标题、搜索框、 导航栏链接、多语言切换、仓库链接,它们均取决于你的配置。
- 导航栏 Logo
你可以通过
themeConfig.logo
增加导航栏 Logo ,Logo 可以被放置在公共文件目录
示例代码
// .vuepress/config.js module.exports = { themeConfig: { logo: '/assets/img/logo.png', } }
- 导航栏链接
你可以通过
themeConfig.nav
增加一些导航栏链接,外部链接 标签的特性将默认包含target="_blank" rel="noopener noreferrer"
,你可以提供target
与rel
,它们将被作为特性被增加到 标签上
// .vuepress/config.js module.exports = { themeConfig: { nav: [ { text: '首页', link: '/' }, { text: '示例', link: '/example/',target:'_blank'}, { text: '扩展', link: 'https://google.com', target:'_self', rel:''}, //通过items数组设置下拉列表 { text: 'Languages', ariaLabel: 'Language Menu', items: [ { text: 'Chinese', link: '/language/chinese/' }, { text: 'Japanese', link: '/language/japanese/' } ] }, // 通过嵌套items在下拉列表中设置分组 { text: 'Languages', items: [ { text: 'Group1', items: [/* */] }, { text: 'Group2', items: [/* */] } ] } ] } }
// .vuepress/config.js module.exports = { themeConfig: { navbar: false } }
你也可以通过 YAML front matter
来禁用某个指定页面的导航栏
--- navbar: false ---
侧边栏
侧边栏(Sidebar)生效,需要配置 themeConfig.sidebar
,基本的配置,需要一个包含了多个链接的数组
搜索框
最后更新时间
上 / 下一篇链接
上一篇和下一篇文章的链接将会自动地根据当前页面的侧边栏的顺序来获取,可以通过过themeConfig.nextLinks
和 themeConfig.prevLinks
来全局禁用它们。
module.exports = { themeConfig: { // 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接 nextLinks: false, // 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接 prevLinks: false }
--- prev: ./some-other-page next: false ---
Git 仓库和编辑链接
当你提供了 themeConfig.repo
选项,将会自动在每个页面的导航栏生成生成一个 GitHub 链接,以及在页面的底部生成一个 "Edit this page"
链接.
// .vuepress/config.js module.exports = { themeConfig: { // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL repo: 'vuejs/vuepress', // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为 // "GitHub"/"GitLab"/"Bitbucket" 其中之一,或是 "Source"。 repoLabel: '查看源码', // 以下为可选的编辑链接选项 // 假如你的文档仓库和项目本身不在一个仓库: docsRepo: 'vuejs/vuepress', // 假如文档不是放在仓库的根目录下: docsDir: 'docs', // 假如文档放在一个特定的分支下: docsBranch: 'master', // 默认是 false, 设置为 true 来启用 editLinks: true, // 默认为 "Edit this page" editLinkText: '帮助我们改善此页面!' }
--- editLink: false ---
页面滚动
你可以通过 themeConfig.smoothScroll
选项来启用页面滚动效果。但在1.2.0+后配置才生效。
// .vuepress/config.js module.exports = { themeConfig: { smoothScroll: true } }