基于VuePress构建高基于markdown语法的网站全教程

Posted 2021-02-21 zoomlacms

• 特性
• 环境搭建
  • 全局安装
  • 创建项目目录
  • 始化项目，建立并编辑 package.json
  • 建立基本目录
  • 修改配置文件 - config.js
  • 修改README.md
  • 运行项目
• 深度开发
  • 配置导航
  • 配置侧边栏
  • 总结
• 模板主题设置
• 其它插件
• 一份完整的源码

介绍

VuePress是一个用来构建博客以及简易网站的项目，基于vuejs，由尤雨溪亲自主持的一个静态项目，静态打包。

基于这样的系统，可以方便用于小型文章发布，如帮助中心、官方博客，支持解析md文件。

VuePress由两部分组成：一部分是支持用 Vue 开发主题的极简静态网站生成器，另一个部分是为书写技术文档而优化的默认主题。它的诞生初衷是为了支持 Vue 及其子项目的文档需求。
它以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作；享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题；它会为每个页面预渲染生成静态的 html，同时，每个页面被加载的时候，将作为 SPA 运行。

VuePress官网：[https://vuepress.vuejs.org/zh/]

特性

• 为技术文档而优化的内置 Markdown 拓展
• 在 Markdown 文件中使用 Vue 组件的能力
• Vue 驱动的自定义主题系统
• 自动生成 Service Worker
• Google Analytics 集成
• 基于 Git 的 “最后更新时间”
• 多语言支持
• 自由主题与插件设置

其中默认主题包含

• 响应式布局
• 可选的主页
• 简洁的开箱即用的标题搜索
• Algolia 搜索
• 可自定义的导航栏 和 侧边栏
• 自动生成的 GitHub 链接和页面的编辑链接

上述都是官网所提供的内容；下面让我们来真正实践下如何快速建立一个技术文档，当然，你熟悉它的操作* 后，优化成为自己的博客也是不错的选择！本着尤大出品必是精品的原则，相信VuePress未来发展会很不错!

*本教程目的在于快速搭建技术文档的基本模型，更具体的配置和说明请参考官网配置
*https://vuepress.vuejs.org/zh/config/

https://vuepress.vuejs.org/zh/default-theme-config/

环境搭建

查看nodejs版本
注意：Node.js 版本 >= 8

node -v

全局安装

npm install -g vuepress

创建项目目录

	mkdir vuepress-demo
	cd vuepress-demo

始化项目，建立并编辑 package.json

npm init -y

进入package.json，修改脚本内容

	{
	"scripts": {
	"docs:dev": "vuepress dev docs",
	"docs:build": "vuepress build docs"
	}
	}

建立基本目录

	vuepress-demo
	├─package.json
	├─docs
	| ├─README.md
	| ├─.vuepress
	| | ├─config.js
	| | ├─public
	| | | └favicon.ico

修改配置文件 - config.js

	module.exports = {
	title: ‘Hello VuePress‘,
	description: ‘Hello, my friend!‘,
	head: [
	[‘link‘, {
	rel: ‘icon‘,
	href: `/favicon.ico`
	}]
	],
	dest: ‘./docs/.vuepress/dist‘,
	ga: ‘‘,
	evergreen: true,
	}

修改README.md

VuePress 提供了对 YAML front matter 开箱即用的支持，我们可以模仿vuepress首页进行如下优化：

	---
	home: true
	heroImage: /favicon.ico
	actionText: 快速上手 →
	actionLink: /guide/
	features:
	- title: 简洁至上
	details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
	- title: Vue驱动
	details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
	- title: 高性能
	details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
	footer: MIT Licensed | Copyright © 2018-present xxxxxx
	---

运行项目

vuepress dev docs

运行上述代码，最后会提示预览的网址http://localhost:8080/（端口号可根据配置进行修改https://vuepress.vuejs.org/zh/config/#port）
打开网址，我们就可以看到如下画面：

README.md中的内容已完美呈现！

深度开发

配置导航

首先在docs目录下建立文件

每个文件夹下的README.md就是当前目录的内容；
让我们通过config.js文件配置相应导航

	themeConfig: {
	nav: [
	{ text: ‘Home‘, link: ‘/‘ },
	{ text: ‘Guide‘, link: ‘/guide/‘ },
	{
	text: ‘Languages‘,
	items: [
	{ text: ‘Chinese‘, link: ‘/language/chinese‘ },
	{ text: ‘English‘, link: ‘/language/english‘ }
	]
	},
	{ text: ‘External‘, link: ‘https://www.baidu.com‘ },
	]
	}

为guide文件下的README.md添加内容：

	## This is guide
	content...
	### title3
	content...
	### title3-01
	## small title
	content...

这时，我们使用完整的命令来运行项目：

	# 开发调试状态
	npm run docs:dev
	# 项目发布
	npm run docs:build

运行项目点击导航Guide，或是通过Home页点击“快速上手”会看到如下画面：

此时我们能够看到guide内容已成功显示，点击Lanuages能看到下拉，点击External会跳转到百度.

配置侧边栏

依旧在config.js文件下的themeConfig属性下添加：

	sidebarDepth: 2,
	sidebar: [
	{
	title: ‘Guide‘,
	collapsable: false,
	children: [‘/guide/‘]
	}
	]

注：通过 themeConfig.sidebarDepth 来修改它的行为。默认的深度是 1，它将提取到 h2 的标题，设置成 0 将会禁用标题（headers）链接，同时，最大的深度为 2，它将同时提取 h2 和 h3 标题。

配置好后，运行项目

总结

通过上述操作，本项目已成功完成了技术文档的基本模型，如更个性化的配置可通过官网按需求优化。

模板主题设置

VuePress支持自由主题定义，在官方网站提供了一系列的主题插件，相关网址：
https://github.com/vuepressjs/awesome-vuepress

其它插件

	# 自动边栏插件
	vuepress-plugin-auto-sidebar

评论插件：
https://valine.js.org/quickstart.html

优秀案例：
www.z01.com/cli
http://wp.z01.com
https://vuepress-theme-reco.recoluan.com/

一份完整的源码

https://github.com/zoomla/waipo
【全文完】