Vuepress 三分钟搭建一个精美的文档或博客

作者：凌览

2023-10-25
浙江
本文字数：2420 字
阅读完需：约 8 分钟

大家好，我是凌览。

作为一个程序员，相信每个人都想折腾一个属于自己的博客。技术文章的输出是我们程序员能力的一种体现，也是一种非常好的个人总结。

网上有很多文档编写网站及工具，比如语雀、石墨等等。但多数需要付费，不能自己 DIY。

为了少写点 curd，我推荐使用VuePress，它可以帮助我们快速地搭建出技术文档或个人博客。

Vuepress 搭建地址：https://jshai.gitee.io/vuepress-blog/

什么是 Vuepress

VuePress 是由 Vue.js 开发团队创建的一个静态网站生成器。它的设计目标是用于编写技术文档或者博客，并且提供了一系列的默认主题和插件，使得构建和维护现代化的静态网站变得更加简单。

它有以下优点：

基于 Vue.js，可以使用 Vue.js 编写功能
支持 Markdown
简单易用
开箱即用的主题
丰富的插件

本地搭建文档

快速上手同官方文档

mkdir vuepress-starter && cd vuepress-starte

复制代码

初始化项目，自行选择喜欢的包管理器

npm init #yarn init

复制代码

安装 VuePress 为本地依赖

npm install -D vuepress # yarn add -D vuepress

复制代码

创建一篇文档

mkdir docs && echo '这是知识库的介绍' > docs/README.md

复制代码

在 package.json 中添加一些 ++scripts++

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

复制代码

启动本地服务器

npm run docs:dev #yarn docs:dev

复制代码

VuePress 会在 http://localhost:8080启动一个热重载的开发服务器。

基础配置

在docs创建一个.vuepress文件夹，.vuepress下再创建config.js文件，Vuepress 的配置由config.js文件内容决定。这里我们的项目结构可能是这样的：

├─ docs│  ├─ README.md│  └─ .vuepress│     └─ config.js└─ package.json

复制代码

配置网站的标题和描述，config.js写入内容：

module.exports = {    title: '凌览的知识库',    description: '凌览，微信搜索「凌览社」关注我，长期交流学习。不知名前端，Node.js爱好者'}

复制代码

页面长这样：

添加导航栏

给首页的上方添加导航栏，config.js修改：

module.exports = {    title: '凌览的知识库',    description: '凌览，微信搜索「程序员凌览」关注我，长期交流学习。不知名前端，Node.js爱好者'    themeConfig: {        logo: 'https://www.linglan01.cn/favicon.JPG',        //顶部导航栏        nav: [            { text: '博客', link: 'https://linglan01.cn/' },            { text: '掘金', link: 'https://juejin.cn/user/3350967174565198' },            { text: 'Github', link: 'https://github.com/CatsAndMice' }        ]    } }

复制代码

页面变成了这样：

更多导航栏配置参考VuePress导航栏配置。

添加侧边栏

我们在docs文件夹下，创建introduce文件夹，此时结构如下：

├─ docs│  ├─ README.md│  └─ .vuepress│     └─ config.js|   └─ introduce|            └─ haha.md|            └─ README.md└─ package.json

复制代码

配置config.js如下：

module.exports = {       themeConfig: {        nav:[...]        sidebar: [            {                title: '侧边栏分组1',                 collapsable: false,                 sidebarDepth: 1,                    children: [                    '/introduce/',//自动获取README.md                    '/introduce/haha'                ]            },        ],    },  }

复制代码

页面效果如下：

还可以设置多组侧边栏：

module.exports = {       themeConfig: {        nav:[...]        sidebar: [            {                title: '侧边栏分组1',                 collapsable: false,                 sidebarDepth: 1,                    children: [                    '/introduce/',//自动获取README.md                    '/introduce/haha',                   '...'                ]            },             {                title: '侧边栏分组2',                 collapsable: true,                 sidebarDepth: 1,                    children: [                     '...'                ]            },        ],    },  }

复制代码

更多侧边栏配置参与Vuepress侧边栏。

更换主题

社区有vuepress-theme-hope、vuepress-theme-reco等主题，可以根据喜好选择。

这里我们以vuepress-theme-reco为例，现在安装 vuepress-theme-reco：

npm install vuepress-theme-reco --save-dev# oryarn add vuepress-theme-reco

复制代码

config.js 配置：

module.exports = {    // ...    theme: 'reco'    // ...}

复制代码

刷新页面即可看见改变。这里就不贴具体图样了

添加文章信息

我们的文章必需要标题，可能需要展示文章作者信息、创建日期等信息，我们可以给文章的 md 文件添加一些信息修改：

--- title: 凌览的知识库 #文章标题author: 凌览 #作者date: '2023-10-24' #日期tags: #标题  - 配置  - 主题  - 索引---公众号【程序员凌览】

复制代码

此时页面效果如下：

设置语言

Vuepress 默认使用en-US，所以日期我们明明设置的是 2023-10-24，但它页面展示的是 10/24/2023 。

这里修改config.js：

module.exports = {    // ...    locales: {        '/': {            lang: 'zh-CN'        }     },    // ...}

复制代码

页面效果：

网站部署

到这里，我们的博客或文档算是正式做好了。接下来我们部署到免费的 Gitee Pages 上，这里有两种方式：

直接在 Gitee 创建一个名为vuepress-blog的仓库，手动触发 Gitee Pages

Github 创建一个名为vuepress-blog的仓库，Gitee 也相同创建一个名为vuepress-blog仓库，通过 Github Action 每次一次仓库更新时将 Github 仓库自动同步到 Gitee 并自动触发 Gitee Pages，详情操作请阅读Github Actions实现仓库自动同步Gitee并更新文档

（完）

关注公粽号【程序员凌览】回复"666"，拉您进【人类高质量前端交流群~】
往期推荐：linglan01.cn/about

发布于: 刚刚阅读数: 3

原文链接:【http://xie.infoq.cn/article/98473fd9c6025af8215e1985a】。文章转载请联系作者。

凌览

关注

还未添加个人签名 2023-09-06 加入

还未添加个人简介

发布

暂无评论

创作场景

Vuepress 三分钟搭建一个精美的文档或博客

什么是 Vuepress

本地搭建文档

基础配置

添加导航栏

添加侧边栏

更换主题

添加文章信息

设置语言

网站部署

凌览

评论