VitePress
快速上手
本节将帮助你从头开始搭建一个简单的 VitePress 文档站点。如果你已经有了一个存在的项目并且向在项目中维护文档，你可以从步骤 3 开始
如果你还没有配置yarn，请先阅读yarn的使用方法并安装yarn
npm install yarn
- 创建并进入一个目录
$ mkdir vitepress-starter && cd vitepress-starter
$ yarn init
$ yarn add --dev vitepress
- 创建你第一篇文档
$ mkdir docs && echo '# Hello VitePress' > docs/index.md
- 在 package.json.添加一些script
{
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs"
}
}
- 在本地服务器上启动文档站点
$ yarn docs:dev
VitePress 会在 http://localhost:xxxx启动一个热重载的开发服务器
现在，你应该有了一个基本的单功能强大的 VitePress 文档站点了
配置
如果没有任何配置，这个站点将会是非常局限的，用户也无法在你的网站上自由导航。
为了更好地自定义你的网站，首先，你需要在你的文档目录下创建一个 .vuepress 目录。所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ └─ index.md
└─ package.json
一个 VuePress 站点必要的配置文件是 .vuepress/config.js，它应当导出一个 JavaScript 对象：
module.exports = {
title: 'Hello VitePress',
description: 'Just playing around.'
}
应用级别配置： 基础
base
- Type: string
- Default: /
站点将部署在这个base URL。如果你计划将站点部署到子路径（例如GitHub页面），则需要设置这个选项。
比如，你计划将站点部署到https://foo.github.io/bar/,那么你需要设置base为’/bar/’。
注意，base需要以/开始并以/结尾。
因为base会自动的被插入到到其他配置中所有以/开始的链接之前，所以你只需要指定一次。
module.exports = {
base: '/base/'
}
lang
- Type : string
- Default:en-US
站点的lang属性。这个属性将作为<html lang="en-US">标记渲染到页面HTML中。
注意，lang属性只会通过vitepress build构建站点时添加， 通过 vitepress dev渲染时不会出现。
module.exports = {
lang: 'en-US'
}
title
- Type: string
- Default: VitePress
站点的标题。 这是所有页面标题的前缀，并显示在导航栏中。
module.exports = {
title: 'VitePress'
}
description
- Type: string
- Default: A VitePress site
站点的描述。 这将作为<meta>标记渲染在页面HTML中。
module.exports = {
description: 'A VitePress site'
}
主题配置: 主页
VitePress 提供主页布局。想要使用，你需要在你的根目录index.md的YAML frontmatter中定义home: true并加上其他元数据。
---
home: true
heroImage: /logo.png
heroAlt: Logo image
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VitePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2019-present Evan You
---
Frontmatter
任何包含YAML frontmatter块的Markdown文件都将由gray-matter处理。
Frontmatter块必须位于在Markdown文件的顶部，必须是有效的YAML格式，放置在三点划线之间。
例如：
---
title: Docs with VitePress
editLink: true
---
在三点划线之间，你可以设置预定义变量，甚至可以创建自定义变量。
这些变量可以通过$frontmatter调用。
这是一个如何在Markdown文件使用预定义变量的例子：
---
title: Docs with VitePress
editLink: true
---
# {{ $frontmatter.title }}
Guide content
其他格式的 frontmatter
VitePress也支持JSON格式的frontmatter，需要以花括号开始和结尾。
---
{
"title": "Blogging Like a Hacker",
"editLink": true
}
---
预定义变量
title
- Type:
string - Default:
h1_title || siteData.title
当前页面的标题
head
- Type:
array - Default:
undefined
定义额外的需要注入的head标签。
---
head:
- - meta
- name: description
content: hello
- - meta
- name: keywords
content: super duper SEO
---
navbar
- Type: boolean
- Default: undefined
你可以通过在特定的页面上设置navbar:false来禁用导航。
sidebar
- Type:
boolean|'auto' - Default:
undefined
你可以通过在特定页面上设置 sidebar: auto来显示侧边栏，或通过sidebar: false来禁用侧边栏。
editLink
- Type:
boolean - Default:
undefined
决定当前页面是否包含编辑链接。
原文地址：http://www.cnblogs.com/yangshu-cnu/p/16810019.html
