VuePress 是一个以 Markdown 为中心的静态网站生成器。好处是可以使用 Markdown 来书写内容文档或者博客。
VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求。
在明确你的目标之后,先不着急立马搭建项目。
🚀 你喜欢哪个主题
因为VuePress除了默认的主题外,提供了扩展主题、扩展插件的能力,不同的主题又组织了不同的插件集合来完成开箱即用的功能,
所以,你首先应该使用哪款主题作为你的个人完整风格。
比较热门你的主题有:
- vuepress默认主题 21.7k⭐
- vuepress-theme-hope 1.4k⭐
- vuepress-theme-reco,(2.0还在测试阶段) 1.6k⭐
- vuepress-theme-vdoing 3.5k⭐
不同主题的之间的最明显的差异就是默认的样式不同,其次就是默认提供的功能不同。
首先,我们看看各个主题默认的样式
默认主题案例
vue系列早先版本的官网大多数都是默认主题
vuepress-theme-hope案例
蝉沐风的码场: https://www.chanmufeng.com/
vuepress-theme-reco 案例:
萌萌哒草头将军(我的旧博客): https://mmdctjj.github.io/blogs/
vuepress-theme-reco 2.0案例:
异想之旅のBlog:https://www.yixiangzhilv.com/
vuepress-theme-vdoing 案例:
Dra-M: https://dra-m.com/
相信看到这里,应该有自己心仪的主题了吧
我用的主题是:vuepress-theme-reco,主题和默认主题相似
主要功能是新增了一些图标、新增了Tag、新增了时间轴等常用功能,
缺点是:功能还不够丰富,图标比较少,无法有效添加摘要、阅读时间、字数统计等功能。
相反,vuepress-theme-hope 这些做的都不错,成为我新的选择。
🚀 搭建项目
💎 初始化项目
如果你选择了一个主题,请务必使用该主题提供的脚手架工具创建项目。这样可以减少很多配置上的麻烦。
npm init vuepress-theme-hope blogs
Need to install the following packages: create-vuepress-theme-hope@2.0.0-beta.233 Ok to proceed? (y)
Need to install the following packages: create-vuepress-theme-hope@2.0.0-beta.233 Ok to proceed? (y) y ? Select a language to display / 选择显示语言 english (US) ❯ 简体中文 D:\work>npm init vuepress-theme-hope blogs2 Need to install the following packages: create-vuepress-theme-hope@2.0.0-beta.233 Ok to proceed? (y) y ? Select a language to display / 选择显示语言 简体中文 ? 选择包管理器 yarn 生成 package.json... ? 设置应用名称 blogs2 ? 设置应用版本号 2.0.0 ? 设置应用描述 A project of vuepress-theme-hope ? 设置协议 MIT ? 项目需要用到多语言么? No ? 是否需要一个自动部署文档到 GitHub Pages 的工作流? Yes ? 你想要创建什么类型的项目? blog 生成模板... ? 是否初始化 Git 仓库? Yes ? 选择你想使用的源 当前源
初始化目录结构如下
🚀 首页配置
其中,src 目录下的 README.md
即为博客或者文档的首页。
等待下载完毕,执行 npm run docs:dev
打开页面,可以看到博客的首页如下:
可以通过设置heroFullScreen: false
,关闭hero背景全屏。
下滑之后文章的列表如下:
文章的列表来自于项目中所有的markdown文件,你可以在每个md文件的frontmatter中设置文章的标题、封面、分类、标签、日期、是否在文章列表中显示。
--- title: 🚀🚀vue3自定义指令实践 isTimeLine: true date: 2023-07-03 category: - 前端 tag: - JavaScript - Vue ---
通过设置article
为 false
将文章在列表中排除。
站点的基本信息、顶部的hero信息、项目链接、底部的footer信息都可以在README.md
中配置。
我的配置如下:具体可以参考:https://theme-hope.vuejs.press/zh/config/frontmatter/blog-home.html
home: false layout: BlogHome icon: home title: 首页 heroImage: /logo.svg heroText: 萌萌哒草头将军 heroFullScreen: false tagline: 千里之行,始于足下 projects: - icon: react name: RaETable desc: 一款开箱即用的antd表格组件库 link: https://mmdctjj.github.io/raetable - icon: setting name: console-loader desc: 自动清除其他开发者console的loader link: https://github.com/mmdctjj/remove-others-console-loader footer: 萌萌哒草头将军
🚀 导航栏
在开始之前你需要明确,你的导航栏需求是啥样的(大白话就是哪些栏目需要在侧边栏展示,哪些在侧边栏展示)
我的思路是,根据文章的分类,将相同的分类文章放在同一目录下,每个目录对应一个导航栏目。
导航栏的相关设置在 navbar.ts
文件中。
默认为字符串,对应 src 目录下的文件路径,你可以省略 .md
扩展名,以 /
结尾的路径会被推断为 /README.md
。
例如:
import { navbar } from "vuepress-theme-hope"; export default navbar([ "/", // 对应首页,即src/README.md '/react/', // 对应src/react/README.md ]);
也可以是对象,基本格式如下:
import { navbar } from "vuepress-theme-hope"; export default navbar([ { text: "博文", icon: "pen-to-square", prefix: "/posts/", // 对应 src/posts 目录 children: [ { text: "苹果", icon: "pen-to-square", prefix: "apple/", // 对应 src/posts/apple 目录 children: [ { text: "苹果1", icon: "pen-to-square", link: "1" }, { text: "苹果2", icon: "pen-to-square", link: "2" }, "3", "4", ], }, "tomato", "strawberry", ], }, { text: "V2 文档", icon: "book", link: "https://theme-hope.vuejs.press/zh/", // link代码外链地址 }, ]);
我的设置为:
import { navbar } from "vuepress-theme-hope"; export default navbar([ "/", { text: 'React系列', icon: 'react', link: '/react/' }, { text: 'Vue系列', icon: 'vue', link: '/vue/' }, { text: 'Vite系列', icon: 'tool', link: '/vite/' }, { text: '新框架尝鲜系列', icon: 'geometry', link: '/framework/' }, { text: '杂谈', icon: 'article', link: '/posts/' }, { text: '标签', icon: 'tag', link: '/tag/javascript/' }, { text: '分类', icon: 'categoryselected', link: '/category/前端/' }, { text: '时间轴', icon: 'time', link: '/timeline/' }, ]);
我将一些默认的路由也加进了导航栏配置中,比如时间轴、标签、分类等。