URL
type
status
date
slug
summary
tags
category
icon
password
在下面的文章中,将带你从0到1用
vitepress
搭建一个个人博客,从初始化到项目部署。一起来看看~🕵️一、📡项目启航
1.1 将会收获
学完这篇文章,你将会收获以下内容:
- 自定义首页样式
- 拥有一个可自定义的侧导
- 高度自定义化一个专属个人的博客
1.2 快速搭建
首先创建并进入一个新目录:
接着,使用你喜欢的包管理器进行初始化。这里我用
pnpm
,如下代码所示:项目初始化完成以后,使用
pnpm
将vitepress
安装为本地依赖。如下代码所示:在vitepress官方文档中提到,vitepress附带了一个命令行向导,来帮助我们构建一个基本的项目。通过以下命令来执行该操作:
构建完成如下图所示:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F026a1385-731b-4e41-a2f3-60a05d435a11%2Fimage.webp?table=block&id=42da640c-a71b-44eb-8e72-a699c5037f49&t=42da640c-a71b-44eb-8e72-a699c5037f49&width=674&cache=v2)
此时文件的目录结构是这样的,日下树状代码所示:
到这里,我们就基本完成了
vitepress
项目的初始化。最后,我们运行 pnpm run docs:dev
来打开项目。效果如下:![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F10576353-cc1c-4e97-a7d3-734b388befbe%2Fimage.webp?table=block&id=8bfd6500-372f-4ed2-81ac-f1be37228ab3&t=8bfd6500-372f-4ed2-81ac-f1be37228ab3&width=708&cache=v2)
二、📹美化个人博客
基础框架我们已经搭建完成,但看着博客的整体内容还比较少。接下来我们需要对博客进行进一步美化。
2.1 整体布局
首先,我们需要了解下博客的整体布局,才能更好的做美化。
1、首页
对于
vitepress
来说,刚进去的那一刻,映入眼帘的就是首页,也就是docs/index.md
这个文件。首页主要由以下五个部分组成:![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F0f5626e4-1b52-4064-a7ad-25bd211e6382%2Fimage.webp?table=block&id=f91da1a2-b1f6-4b9c-8dcc-0b9dd3f055d4&t=f91da1a2-b1f6-4b9c-8dcc-0b9dd3f055d4&width=708&cache=v2)
对于首页来说,我们一般会比较少去放侧边栏,更多地是放一些个人博客的概述。下面我们先来继续了解下普通文章页面的布局,配置修改放后面。
2、普通文章
对于普通文章页面来说,我们一般会在左侧放专栏的文章,中间放当前文章的内容,右边放文章的锚点导航。具体如下:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F64abdb6e-b623-4bbf-9bbe-574ce3fd3460%2Fimage.webp?table=block&id=31adc5d7-3b6e-4e0a-9dbf-56bc60666986&t=31adc5d7-3b6e-4e0a-9dbf-56bc60666986&width=708&cache=v2)
2.2 内容完善
上面,我们了解了整体布局。接下来,依据这个布局,我们来说之后一步步的修改。
1、导航条美化navbar
在上面的两张图当中,会发现到,它们共同的部分都是序号①,也就是
navbar
。因此,我们先来对这部分进行美化。(1)左上角-logo和名称自定义
修改
docs/.vitepress/config.ts
文件下的配置,具体代码为:具体展示效果为:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2Fab05e0b1-509f-4263-a249-151144737e2c%2Fimage.webp?table=block&id=fe45a93f-3521-4c04-a2d6-5aeb84c6fa32&t=fe45a93f-3521-4c04-a2d6-5aeb84c6fa32&width=708&cache=v2)
(2)右上角-导航内容自定义
接下来美化右上角部分,首先先确定nav在
docs/.vitepress/config.ts
文件的位置,具体如下👇🏻:位置有了,接下来我们来定义
navbar
的内容。具体代码如下:到这里,我们就完成了
navbar
的美化。具体来看下效果:![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F3f12ef06-ebe0-4dd9-8e07-4eeadee8f466%2Fimage.webp?table=block&id=d8647a69-19e6-4ae3-bb9f-00d31c4e9760&t=d8647a69-19e6-4ae3-bb9f-00d31c4e9760&width=708&cache=v2)
2、首页美化home
对于首页部分来说,就是上面首页图中的序号②。我们来对这部分进行美化。
(1)layout选择
首页部分的配置在
docs/index.md
文件,具体来看下面这些配置项:来看下效果:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F819fe67b-b672-49e8-93ed-55be1915ab37%2Fimage.webp?table=block&id=2793e0d3-7540-4615-8836-9bda05d9608e&t=2793e0d3-7540-4615-8836-9bda05d9608e&width=708&cache=v2)
到此,一个像模像样的首页就有了。但有些同学会觉得,自定义力度还不够,比如说想在页面的下方再加点图片或者图标之类的,那下面我们就来说说,在vitepress中如何自定义组件。
(2)自定义组件
首先,我们在
docs/.vitepress/components
文件夹下定义一个文件,名为home.vue
。然后在里面写些想要展示的内容所对应的代码,比如:接着,在
docs/index.md
中引入,具体如下:下面来看实现后的效果:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2Fba21a595-0257-46e0-866e-c8bb185e4618%2Fimage.webp?table=block&id=37a5f64c-31d2-4975-95bd-d6590c6951b9&t=37a5f64c-31d2-4975-95bd-d6590c6951b9&width=708&cache=v2)
这样,我们就实现了相应的自定义内容。按照这个思路,我们也可以在组件里面写各种自己想要添加的东西,达到页面自定义的效果。
到这里,navbar和主页都完成了,下面就要去写文章了。那这里有的小伙伴就会开始疑问:①文章的目录怎么存放?②不同的专栏怎么独立分类?③侧边栏怎么展示?④h1~h6的标题怎么对齐锚点?
不着急,下面我们一个个来逐一突破。
3、侧边栏美化Sidebar
看2.1中的第2点我们可以知道,文章页面包括序号②③④三个部分。那我们先来看看,怎么定义侧边栏。
(1)定义入口
假设说我们现在有一个专栏,叫数据结构与算法。那么我们会先去
navbar
定义入口。入口代码在docs/relaConf/navbar.ts
,定义内容如下:定义完成之后,来看下现在的效果:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2Fa32e62a7-b669-4dd5-8b4b-fd6cf2bafaf1%2Fimage.webp?table=block&id=7dc9d1a0-d4c7-4f29-9471-98195a278c08&t=7dc9d1a0-d4c7-4f29-9471-98195a278c08&width=708&cache=v2)
此时大家会发现,左边的侧边栏莫名其妙的。其实这是因为,在我们刚开始初始化项目的时候,脚手架给我们预置的侧边栏内容,对应
docs/.vitepress/config.ts
中的themeConfig.sidebar
。下面,我们来改造这个位置的内容。(2)侧边栏规范化
我们当前只是定义了“数据结构与算法”专栏的入口文件,那在这个页面中的侧边栏,我们要展示的是「数据结构与算法」这个专栏所要填充的文章。比如:栈、队列、字典和集合等等。
那接下来,我们先去专栏下面建立相关文章的md文件。在
docs/column/Algorithm
文件下定义以下几个文件:想要生成侧边栏的内容有了,下面我们去给侧边栏做相应的配置。同样,考虑到以后会生成很多侧边栏,我们同样把
sidebar
单独抽离成文件。具体代码如下:最终,我们来看下实现的效果。具体如下图所示:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2Fba55ed71-7e36-483e-8eef-882148c1a6bd%2Fimage.webp?table=block&id=755fa0ce-aca8-4896-9f25-57285926db29&t=755fa0ce-aca8-4896-9f25-57285926db29&width=708&cache=v2)
这样,就成功替换了当前专栏的侧边栏。这里我们只对一个专栏做侧边导航栏配置,如果有多个专栏的情况下,按照上面的方法,继续叠加配置即可。
写到这里的时候,周一突然发现个问题,侧边栏的配置每回更新都要去手动修改,有时候又很容易出现错误订正的情况。然后我就在想,有没有什么办法,可以通过npm包等方式,来自动生成sidebar的配置?
于是找到了这篇文章:基于目录为VitePress生成侧边栏 - 掘金[1]。实践了一番下来,周一觉得跟自己平常的归类整理方式相比,自定义化的程度比较低。因此这里不再做详细介绍,大家各取所需~
4、正文排版Markdown
侧边导航栏介绍完毕,下面我们来了解下正文的排版。有一小部分小伙伴可能不知道
markdown
语法,所以在对文章排版的时候,会自上而下地用黑体字来处理。这里,我们来讲讲平常经常会排版的方式,就是
markdown
语法。vitepress
官网也对markdown
做了很好的支持,具体可以戳此链接[2]。(1)md基础语法
(2)vitepress对md的支持
上面我们介绍了最简单的
markdown
语法,还有另一个要提到的问题是,vitepress官方对markdown的扩展支持。包括但不限于emoji:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F91d06254-cea5-44fc-8b01-c7b67b489eb1%2Fimage.webp?table=block&id=eaf4fc7a-cf56-4dc5-a103-754558cfddd6&t=eaf4fc7a-cf56-4dc5-a103-754558cfddd6&width=708&cache=v2)
或者高亮信息:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F8628c749-a489-4f3e-ad2d-1b3ed7e9d9c2%2Fimage.webp?table=block&id=c5d6e2e3-bd5a-4da1-aef4-c00786b183d2&t=c5d6e2e3-bd5a-4da1-aef4-c00786b183d2&width=708&cache=v2)
还有其他很多种类型的扩展支持,这里不再赘述。**具体可戳此链接查看:**
https://vitepress.dev/guide/markdown#header-anchors
(3)最后更新时间
到这里,我们已经了解了
md
的大部分内容。配置到一半的时候,细心的小伙伴可能已经发现,在正文的最后,有个最后更新时间LastUpdated的样式。这其实是因为我们在docs/index.md
文件里配置了这个文件,所以展示了这个样式。代码如下:5、锚点导航Anchor
现在,我们来到锚点导航。锚点导航对应的是,
2.1
第 2
点中的④区域。也就是说,点击其对应的导航,就能够跳转到文章对应地页面位置上。类似于掘金右边导航的这种效果~回到正题,怎么配置呢?回答
.vitepress/config.ts
文件,在themeConfig
中配置outline
。具体如下代码所示:具体展示效果如下:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F8bdc173b-ad70-4b08-b966-1b31610b6cdd%2Fimage.webp?table=block&id=cb002603-427f-4271-afca-bb5d3ee1269b&t=cb002603-427f-4271-afca-bb5d3ee1269b&width=708&cache=v2)
值得注意的是📢,目前锚点导航只能配置h2-h6级的标题,h1标题暂时不能配置。看了下
github
,发现有小伙伴提了issue
,但似乎目前还没解决。静等官方解决……2.3 配色相关
1、修改主题色
上面描述了内容主体的整体布局,接下来谈谈整体配色。也就是,整体的绿色如何更换成其他颜色呢?
首先,我们需要确定想要更换的颜色色调,需要稍微统一一下。这里推荐个网站:https://coolors.co/palettes。
可以先在上面这个网站找一套自己喜欢的颜色,比如紫色:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F8383856d-b203-454f-99d0-a68f4c5a66d3%2Fimage.webp?table=block&id=a8e13094-6e8f-43e8-b545-73e3283d4302&t=a8e13094-6e8f-43e8-b545-73e3283d4302&width=708&cache=v2)
之后呢,要做的就是,把
vitepress
项目中对应的全局变量的颜色给替换掉。具体操作如下:这样,我们就完成整体主题色的替换:
![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F9d00d589-808f-4f02-bf08-1a644327a3ff%2Fimage.webp?table=block&id=70852589-ae42-43fc-be83-f45697d82b7f&t=70852589-ae42-43fc-be83-f45697d82b7f&width=708&cache=v2)
大家可以看到,整体变成了以紫色调为主,右图像的渐变也有了。如果还想要修改其他跟主题色相关的颜色,可以看下官方
github
上的变量说明,进行相应的修改。这里附上官方网站的详细说明:https://vitepress.dev/guide/extending-default-theme#customizing-css ;
以及
github
的变量地址:https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css2、更换主题
当我搭建到这一步的时候,就开始想着
vitepress
有没有像vuepress-theme-reco
类似的主题。很遗憾的是,暂时还没看到。不过在掘金社区里搜到一些博主自己搭建了一些主题,这里不做详细介绍,感兴趣的同学可以前往查看。戳链接:
- @sugarat/theme - https://theme.sugarat.top/
- 一个简约风的VitePress博客主题[3]
三、🎥其他周边
3.1 搜索功能
谈到搜索,
vitepress
支持两种搜索模式:本地搜索和algolia。对于algolia
来说,相当于把网站的数据丢给algolia
,然后当你在网站上进行搜索时,会向algolia
发送一个请求,然后呢,algolia
在你上传的数据中进行搜索,之后把结果返回给你,就可以在网站上进行展示。这种方式相对比较繁琐些,这里不详细介绍,有需要可以查看这篇文章:vitepress 如何开启 algolia 全文搜索[4]。另一种方式是:本地搜索。本地搜索只需要这样处理即可:
3.2 国际化i18n
对于个人博客来说,一般只用到中文。不过有的小伙伴可能会想要兼容下中英文,那么可以使用国际化i18n来解决。
vitepress
提供了这个解决方案:具体路由配置见这里:https://vitepress.dev/reference/default-theme-config#i18nrouting
四、📽Github Page部署
到这里,我们基本完成了一个博客的搭建。那搭建完成以后,就是发布上线啦~
这里采用的是
Github Page
来进行部署,值得注意的是,如果要用Github Page
来部署,那么需要在git
上的仓库需要是public
状态哦~首先,我们在Github上新建一个仓库,假设命名为
vitepress-demo-mondaylab
。之后,我们需要再去 config.ts
文件里,做相应的配置。具体如下:其次,在根目录下创建一个文件夹,名为
vitepress-starter
。之后,建立一个文件,名为deploy.sh
。具体代码如下:之后,先把我们调试完成的代码,推到
github
上的master
分支上,然后跑脚本,发布到生产环境。本地终端运行如下代码:最后,可以在仓库的
Setting → Pages
中看到最后的地址:![notion image](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F4647b009-2509-4b75-9f61-d232042f9e5b%2F2a3a422e-25e2-4db2-b54e-c67e326c3189%2Fimage.webp?table=block&id=d8367454-ff51-4137-b982-6fa633970ed9&t=d8367454-ff51-4137-b982-6fa633970ed9&width=708&cache=v2)
访问上面圈中的地址,就可以正常进行访问啦~
最后,放上此次搭建的
demo
地址,可以直接在github上fork
下来,然后将相关的文字等内容进行修改即可。具体地址戳:https://github.com/Jacqueline712/vitepress-demo-mondaylab
五、🎙结束语
在搭建博客的过程中,我突然意识到,文档在日常开发中的使用还蛮广泛的。小到一个组件库的文档说明,大到一个产品的使用说明等等,都需要文档。
这篇文章也从0到1讲解了用
vitepress
搭建一个博客的全过程,希望对大家有帮助~如果有一些好玩的周边插件,记得评论区分享呀~
Ending,我们下次见!🍻🍻🍻
💡参考资料
如果想要从vuepress直接升级为vitepress,可以参考:
- vuepress升级成vitepress - 掘金[5]
- 如何理解vitepress以及怎么将vuepress升为vitepress - 编程语言 - 亿速云[6]
- Migration from VuePress | VitePress[7]
官方文档:
- 中文版 - vitepress 中文文档 🎉 - 掘金[8]
- 英文版 - https://vitepress.dev/
其他:
- vuepress博客搭建系列 - 保姆级教程[9]
- 使用 VitePress 打造个人前端导航网站 - 掘金[10]
参考资料
[1]
基于目录为VitePress生成侧边栏 - 掘金: https://juejin.cn/post/7169108165198348302#comment
[2]
具体可以戳此链接: https://vitepress.dev/guide/markdown
[3]
一个简约风的VitePress博客主题: https://juejin.cn/post/7196517835380293693#heading-1
[4]
vitepress 如何开启 algolia 全文搜索: https://fyzhu.github.io/2022/11/01/vitepress-如何添加-algolia-搜索/
[5]
vuepress升级成vitepress - 掘金: https://juejin.cn/post/7021062842790969381#heading-5
[6]
如何理解vitepress以及怎么将vuepress升为vitepress - 编程语言 - 亿速云: https://www.yisu.com/zixun/618840.html
[7]
Migration from VuePress | VitePress: https://vitepress.dev/guide/migration-from-vuepress#migration-from-vuepress
[8]
vitepress 中文文档 🎉 - 掘金: https://juejin.cn/post/7147274707060916232
[9]
vuepress博客搭建系列 - 保姆级教程: https://juejin.cn/column/7041871760995647502
[10]
使用 VitePress 打造个人前端导航网站 - 掘金: https://juejin.cn/post/7204860462239498296#heading-0
- 作者:NickYam
- 链接:https://i.nickyam.com/article/vitepress-blog-setup
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议,转载请注明出处。
相关文章