用我这套模板，几分钟做出文档网站！

大家好，我是保姆皮，最近我上线了自己的《编程宝典》网站，可以在线阅读我分享过的各种编程学习路线和知识干货。

指路：https://codefather.cn/

不少小伙伴催我出教程，说也想做个类似的文档网站。

所以我用最快的速度出了 “保姆级文档网站制作教程”，并且开源了一套网站模板。大家只需要几分钟的时间，就能快速做出同款的、精简的文档网站。

推荐观看视频教程：https://www.bilibili.com/video/BV1LQ4y1V79r/

以下为文字版教程：

引言

首先，很多同学肯定会觉得这个网站的风格比较眼熟。没错，这是基于 VuePress 静态网站生成器开发的。

有同学问了，你咋不用 vitepress 嘞？

啊，也用过，但是在生态和成熟度上不及 VuePress，折腾一番后还是选择返璞归真。

别看这么一个网站非常精简，但是想做好它，这里面的门道可多着呢。你要阅读 VuePress 的官方文档，还要在琳琅满目的插件中做选择，很费时间。

我出这期教程的目的，就是帮大家做做减法，不用阅读那老长的官方文档，我帮大家选好了插件。甚至，我给大家提供了一套我们自己增强的、开箱即用的文档网站模板。

以后你要做自己的文档网站，直接用这个模板，不用写代码，有手就行。

VuePress 文档网站制作教程

一、项目启动

先花 30 秒的时间启动项目。

首先打开我的开源项目 codefather，切换分支为 template 模板。

指路：https://github.com/liyupi/codefather

然后下载代码压缩包：

解压后，用 WebStorm 或 VS Code 等开发工具打开项目。

项目基于 VuePress 实现，需要 Node 和 Npm 环境，尽量和我的版本号保持一致防止后面出现莫名其妙的报错，没有的同学请到官网安装一下。

首次运行前，需要运行 npm install 命令安装依赖：

安装依赖成功后，在 package.json 文件中点击 docs:dev 运行即可：

运行成功，默认在本地的 8080 端口，就能访问到网站啦！

接下来，我会详细讲解这套 VuePress 模板，包括目录结构、基本配置、主题配置、插件配置等，让大家在学会 VuePress 的基础上、能灵活运用这套模板轻松定制网站。

二、模板目录结构

先来看下 VuePress 模板的目录结构，如下图：

所有的文档（目录）直接放到项目根目录下即可。

三、基本配置

我们打开 VuePress 的核心配置文件 config.ts，所有的配置基本都集中在这个文件，可以在这里全局改变网站的内容、主题样式、使用插件增强能力等。

先来看一些基本配置：

1、网站基本信息

包括网站标题、描述，还有我们自定义的作者、域名、全局标签：

const?author?=?"程序员鱼皮";
const?domain?=?"https://codefather.cn";
const?tags?=?["程序员",?"编程",?"计算机"];

export?default?defineConfig({
??title:?"鱼皮的编程宝典",
??description:?"贴心的编程学习路线，全面的编程知识百科",
??...
});

2、网站 head 标签

head 标签作为 HTML 网页文件的大脑，通常包含了网页的重要基本信息，比如上面提到的网页标题、描述等。

使用 VuePress 工具，我们可以在 head 配置中添加网站 head 标签信息，比如设置站点图标、设置有利于 SEO（搜索引擎优化）的元信息、添加第三方统计分析代码等：

head:?[
??//?站点图标
??["link",?{?rel:?"icon",?href:?"/favicon.ico"?}],
??//?SEO
??[
????"meta",
????{
??????name:?"keywords",
??????content:
????????"程序员鱼皮,?编程学习路线,?编程知识百科,?Java,?编程导航,?前端,?开发,?编程分享,?项目,?IT,?求职,?面经",
????},
??],
??//?百度统计
??[
????"script",
????{},
????`
??????var?_hmt?=?_hmt?||?[];
??????(function()?{
????????var?hm?=?document.createElement("script");
????????hm.src?=?"https://hm.baidu.com/hm.js?2675818a983a3131404cee835018f016";
????????var?s?=?document.getElementsByTagName("script")[0];?
????????s.parentNode.insertBefore(hm,?s);
??????})();
????`,
??],
],

3、永久链接

默认情况下，VuePress 是根据文档层级生成的访问链接，如下图：

但如果文档存放的目录改变了，那么原有的链接就会失效，会影响 SEO 和用户访问。

所以建议使用永久链接，只要在 config.ts 中加上这行配置即可：

permalink:?"/:slug",

开启永久链接后，系统自动根据文章标题生成链接地址，会更简短、精确，不会被文档目录结构影响。

效果如下：

永久链接的生成规则可以自己配置，或者给某个页面定制永久链接，详见官方文档。

官方文档：https://vuepress.vuejs.org/zh/guide/permalinks.html#%E8%83%8C%E6%99%AF

4、开启文件热更新

VuePress 默认提供了热更新，改动文档或配置时会自动更新网站，但是范围有限，如果是自定义的 js、ts 等前端文件，修改后不会触发热更新。

可以添加 extraWatchFiles 配置解决，为特定范围的文件开启热更新。

比如模板中所有的 ts 文件和侧边栏配置文件：

//?监听文件变化，热更新
extraWatchFiles:?[".vuepress/*.ts",?".vuepress/sidebars/*.ts"],

5、Markdown 配置

VuePress 的基本功能就是把我们写的 Markdown 文件渲染成网站，我们可以在 markdown 配置中自定义网站的渲染规则，比如显示代码块的行号、支持更细层级的标题渲染等：

markdown:?{
??//?开启代码块的行号
??lineNumbers:?true,
??//?支持?4?级以上的标题渲染
??extractHeaders:?["h2",?"h3",?"h4",?"h5",?"h6"],
},

四、主题配置

这里我使用的是 VuePress 默认主题，因为更精简、更稳定。

官网默认主题配置：https://vuepress.vuejs.org/zh/theme/default-theme-config.html

也有同学推荐 Hope 主题，其实我以前有的文档网站就是用的它，但后面觉得界面有点复杂了，个人还是喜欢最精简的哈哈。

想修改主题配置，只需要更改 config.ts 配置文件中的 themeConfig 配置即可。

export?default?defineConfig({
?...
????
??//?主题配置
??themeConfig:?{
????logo:?"/logo.png",
????nav:?navbar,
????sidebar,
????lastUpdated:?"最近更新",

????//?GitHub?仓库位置
????repo:?"liyupi/codefather",
????docsBranch:?"master",

????//?编辑链接
????editLinks:?true,
????editLinkText:?"完善页面",

????//?@ts-ignore
????//?底部版权信息
????footer,
????//?额外右侧边栏
????extraSideBar,
??},
});

1、主题基本配置

包括整个网站的 Logo、GitHub 仓库的基本信息、页面底部展示最近更新时间、页面底部展示编辑文章链接等。

配置如下：

export?default?defineConfig({
?...
????
??//?主题配置
??themeConfig:?{
????//?替换?logo
????logo:?"/logo.png",
??????
????//?页面底部展示最近更新时间
????lastUpdated:?"最近更新",
??????
????//?GitHub?仓库和分支信息
????repo:?"liyupi/codefather",
????docsBranch:?"master",
??????
????//?页面底部展示编辑文章
????editLinks:?true,
????editLinkText:?"完善页面",
??},
});

2、导航栏配置

由于导航栏配置可能比较复杂，为了让配置更清晰，我们可以集中把导航配置写在 navbar.ts 文件中。

如下图：

然后在 config.ts 的主题配置中引用 navbar 即可：

import?navbar?from?"./navbar";

export?default?defineConfig({
??//?主题配置
??themeConfig:?{
????nav:?navbar,
??},
});

可以参考官方文档的语法，添加导航栏配置，支持子导航栏。

导航栏配置文档：https://vuepress.vuejs.org/zh/theme/default-theme-config.html#%E5%AF%BC%E8%88%AA%E6%A0%8F

示例代码：

//?.vuepress/config.js
module.exports?=?{
??themeConfig:?{
????nav:?[
??????{
????????text:?'Languages',
????????ariaLabel:?'Language?Menu',
????????items:?[
??????????{?text:?'Chinese',?link:?'/language/chinese/'?},
??????????{?text:?'Japanese',?link:?'/language/japanese/'?}
????????]
??????}
????]
??}
}

效果如下：

3、侧边栏配置

和导航栏一样，所有的侧边栏配置都放在 sidebar.ts 文件中，然后在 config.ts 中引用。

但是由于侧边栏的配置比较复杂，文章多的时候需要分组、还要能自动识别文章中的小标题，所以这里我摸索出来的 最佳实践 是：

1）将同类的文章放到同一个目录里，比如学习路线：

2）将该目录的所有文章（侧边栏配置）集中写在单独的配置文件中，比如 roadmapSideBar.ts，放到 sidebars 目录下：

3）在侧边栏 sidebar.ts 配置中，引用各分类的侧边栏配置文件，实现不同分类下的文章，展示的侧边栏不同。

import?{SidebarConfig4Multiple}?from?"vuepress/config";

import?roadmapSideBar?from?"./sidebars/roadmapSideBar";
//?@ts-ignore
export?default?{
????"/学习路线/":?roadmapSideBar,
????//?降级，默认根据文章标题渲染侧边栏
????"/":?"auto",
}?as?SidebarConfig4Multiple;

效果如下：

4、底部配置

这是我们自己使用 VuePress 自定义主题能力二次开发的功能，和导航栏、侧边栏配置一样，只用在 footer.ts 中填写配置，就能自动在网页底部生成友情链接、备案信息等，非常方便！ 示例代码如下：

/**
?*?底部版权信息
?*/
export?default?{
??friendLinks:?[
????{
??????label:?"鱼鸢网络",
??????href:?"https://yuyuanweb.com/",
????},
????{
??????label:?"老鱼简历",
??????href:?"https://www.laoyujianli.com/",
????},
????{
??????label:?"编程学习圈",
??????href:?"https://yupi.icu",
????},
??],
??copyright:?{
????href:?"https://beian.miit.gov.cn/",
????name:?"沪ICP备19026706号-6",
??},
};

效果如下：

5、右侧附加边栏配置

这也是我们自己使用 VuePress 自定义主题能力二次开发的功能，和前面讲的配置一样，只用在 extraSideBar.ts 中填写配置，就能自动在网页右侧生成一个固定的侧边栏了，从而提供一些附加能力，比如对站长很重要的引流支持等。

示例代码如下，支持自定义 HTML 代码：

/**
?*?额外右侧边栏
?*/
export?default?[
??{
????title:?"手机看",
????icon:?"/icon/mobile.png",
????popoverTitle:?"微信扫一扫",
????popoverUrl:
??????"/qrcode-codefather.png",
????popoverDesc:?"可以手机看或分享至朋友圈",
??},
??{
????title:?"星球",
????icon:?"/icon/xingqiu.png",
????popoverTitle:
??????'<span style="font-size:0.8rem;font-weight:bold;"><span style="color:red;">保姆级实战项目教程</span>、编程学习指南、学习资源、求职指南、技术分享、编程交流</span>',
????popoverUrl:
??????"/qrcode-codenav.png",
????popoverDesc:?"知识星球：编程导航",
??},
}

效果如下：

五、插件配置

除了上述基本能力外，我选择 VuePress 的主要原因就是它的插件生态特别好，随便下个插件，就能增强网站的能力。

可以在 awesome-vuepress 项目中看到大量的插件，点进去就能看到插件的介绍、安装方式等。

指路：https://github.com/vuepressjs/awesome-vuepress#plugins

但是大家也发现了，插件太多，反而不知道该用哪些了。。。一个个试也太费时间了！

所以这里我帮大家做了减法，在模板中只保留了我认为有用的核心插件。

分别介绍一下：

1、返回顶部

安装（其实模板中已经帮大家装好了）：

yarn?add?-D?@vuepress/plugin-back-to-top
#?OR?npm?install?-D?@vuepress/plugin-back-to-top

开启插件配置，一行代码就能搞定：

module.exports?=?{
??plugins:?['@vuepress/back-to-top']
}

2、图片点击放大

可以让网站中的所有图片支持点击放大功能。

开启插件配置，一行代码就能搞定：

module.exports?=?{
??plugins:?["@vuepress/medium-zoom"]
}

3、SEO 相关插件

安装插件后，只需要修改几行配置，就能让你的网站更容易被搜索引擎收录，从而提高访问量。

SEO 相关插件有很多，列举几个我觉得不错的：

1）谷歌分析

是一款有利于谷歌搜索引擎优化的插件：

module.exports?=?{
??plugins:?[
????[
??????'@vuepress/google-analytics',
??????{
????????'ga':?''?//?补充自己的谷歌分析?ID，比如?UA-00000000-0
??????}
????]
??]
}

2）vuepress-plugin-seo

作用是可以自定义生成的网站 meta 标签内容，比如把文章描述、标签信息放到标签中，从而增加收录率。

插件官方：https://github.com/lorisleiva/vuepress-plugin-seo

示例代码：

//?定义常量
const?author?=?"程序员鱼皮";
const?domain?=?"https://codefather.cn";
const?tags?=?["程序员",?"编程",?"计算机"];

//?https://github.com/lorisleiva/vuepress-plugin-seo
[
??"seo",
??{
????siteTitle:?(_,?$site)?=>?$site.title,
????title:?($page)?=>?$page.title,
????description:?($page)?=>
??????$page.frontmatter.description?||?$page.description,
????author:?(_,?$site)?=>?$site.themeConfig.author?||?author,
????tags:?($page)?=>?$page.frontmatter.tags?||?tags,
????type:?($page)?=>?"article",
????url:?(_,?$site,?path)?=>
??????($site.themeConfig.domain?||?domain?||?"")?+?path,
????image:?($page,?$site)?=>
??????$page.frontmatter.image?&&
??????(($site.themeConfig.domain?&&
????????!$page.frontmatter.image.startsWith("http"))?||
????????"")?+?$page.frontmatter.image,
????publishedAt:?($page)?=>
??????$page.frontmatter.date?&&?new?Date($page.frontmatter.date),
????modifiedAt:?($page)?=>?$page.lastUpdated?&&?new?Date($page.lastUpdated),
??},
],

3）sitemap 插件

可以自动给网站生成 sitemap.xml 站点地图，让搜索引擎更了解你的网站。

插件官方：https://github.com/ekoeryanto/vuepress-plugin-sitemap

配置代码如下：

//?https://github.com/ekoeryanto/vuepress-plugin-sitemap
[
??"sitemap",
??{
????hostname:?domain,
??},
],

4）自动推送到百度插件

除了被动等待搜索引擎收录文章外，我们也可以主动给搜索引擎推送文章，提高收录率。

使用这个插件，文章就会定期、自动地推送给百度，非常方便。

插件官方：https://github.com/IOriens/vuepress-plugin-baidu-autopush

配置代码如下：

//?https://github.com/IOriens/vuepress-plugin-baidu-autopush
[
??'vuepress-plugin-baidu-autopush'
]

4、支持代码复制

这个插件对程序员来说可太实用了，只需一行配置，用户就能一键复制网站上的代码块：

配置代码如下：

//?https://github.com/znicholasbrown/vuepress-plugin-code-copy
[
??"vuepress-plugin-code-copy",
??{
????successText:?"代码已复制",
??},
],

5、配置 RSS 订阅

RSS 是一种统一的内容更新标准，使用这个插件，可以让更多用户通过 RSS 订阅的方式查看到你网站的内容，从而增加访问量。

插件官方：https://github.com/webmasterish/vuepress-plugin-feed

配置代码如下：

//?https://github.com/webmasterish/vuepress-plugin-feed
[
??"feed",
??{
????canonical_base:?domain,
????count:?10000,
????//?需要自动推送的文档目录
????posts_directories:?[],
??},
],

6、显示文章标签插件

插件官方：https://github.com/zq99299/vuepress-plugin/tree/master/vuepress-plugin-tags

这个插件其实可有可无，允许你用 Markdown 的 FrontMatter 语法定义标签，然后在网站上展示。

比如在某篇文章开头定义了如下代码：

一行代码就能开启配置了：

//?https://github.com/zq99299/vuepress-plugin/tree/master/vuepress-plugin-tags
["vuepress-plugin-tags"],

然后就能看到如下效果：

7、图片懒加载

插件官方：https://github.com/tolking/vuepress-plugin--lazy

最后这个插件我觉得最有用，只需要一行代码配置：

['-lazy']

就能给网站所有的图片添加懒加载功能，当页面滚动到图片位置时才会请求加载图片，对于图片较多的网站来说，大幅提高加载速度、节约带宽。

六、项目部署

最后，我们要进行项目部署，也就是发到服务器上供别人访问。

VuePress 的部署非常简单，首先在 package.json 文件中执行 docs:build 打包命令：

打包成功，可以看到 .vuepress 目录下多了个 dist 目录，所有生成的网页资源都在该目录下：

接下来，我们只需要把 dist 目录下所有的文件，扔到服务器上就可以了。我之前已经给大家分享了好几种不同的项目上线方式，感兴趣的同学可以翻翻我之前的视频，这里就不重复演示了。

最后

通过这个教程，我相信大家不仅学到了文档网站的制作方法，还收获了很多其他的前端小知识，比如 SEO、懒加载之类的，希望对大家有帮助，都能做出自己的文档网站来沉淀分享知识。

学会的话点赞收藏支持下啦，谢谢大家~