VuePress的默认主题配置

答神
2,985 阅读5分钟

前言

默认主题的配置通过可以通过 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

{
  "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

目录结构

├─ 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 增加一些导航栏链接,外部链接 <a> 标签的特性将默认包含target="_blank" rel="noopener noreferrer"，你可以提供 target 与 rel，它们将被作为特性被增加到 <a> 标签上 示例代码

// .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: [/*  */] }
        ]
      }
    ]
  }
}
  • 禁用导航栏

你可以使用 themeConfig.navbar 来禁用所有页面的导航栏 示例代码

// .vuepress/config.js
module.exports = {
  themeConfig: {
    navbar: false
  }
}

你也可以通过 YAML front matter 来禁用某个指定页面的导航栏

---
navbar: false
---

侧边栏

侧边栏（Sidebar）生效，需要配置 themeConfig.sidebar，基本的配置，需要一个包含了多个链接的数组

搜索框

最后更新时间

上 / 下一篇链接

上一篇和下一篇文章的链接将会自动地根据当前页面的侧边栏的顺序来获取,可以通过过themeConfig.nextLinks 和 themeConfig.prevLinks 来全局禁用它们。

  • js代码配置
module.exports = {
  themeConfig: {
    // 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接
    nextLinks: false,
    // 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接
    prevLinks: false
  }
  • YAML front matter配置
---
prev: ./some-other-page
next: false
---

Git 仓库和编辑链接

当你提供了 themeConfig.repo 选项，将会自动在每个页面的导航栏生成生成一个 GitHub 链接，以及在页面的底部生成一个 "Edit this page" 链接.

  • js代码配置
// .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: '帮助我们改善此页面！'
  }
  • YAML front matter配置
---
editLink: false
---

页面滚动

你可以通过 themeConfig.smoothScroll 选项来启用页面滚动效果。但在1.2.0+后配置才生效。

  • js代码配置
// .vuepress/config.js
module.exports = {
  themeConfig: {
    smoothScroll: true
  }
}
avatar
文章
阅读
粉丝