解决方案:[边写边学系列] — 超级好用的文档站建站框架 Docusaurus

　　解决方案:[边写边学系列] — 超级好用的文档站建站框架 Docusaurus

　　以上搜索过程引出了这篇文章文章。既然是给小伙伴们推荐的框架，我就忍不住来看看这款Docusaurus到底怎么样了。. 说实话，我在 React 社区里还是用了很多相关的技术栈。对于静态站点文档内容站点，如果不帮朋友找一个一键即用的框架，我想我可能会使用 Next.js 或 Gatsby。手工建造一个。主要是搭建的过程是一个知识积累的过程，但现在其实感觉专业的东西交给专业的框架工具，开发者只需要专注自己应该做的事情，效率更高。在使用 Docusaurus 之前，我们先来看看有哪些知名的文档网站使用它来建站。

　　嗯，果然是官公子。Facebook 上的许多知名框架和 React 社区中的许多知名框架文档网站都是使用 Docusaurus 构建的。由于这意味着框架本身已经过验证，我们将自己尝试一下。一点点。

　　你好 Docusaurus - 第一次认识

　　个人而言，现在学习任何新框架的习惯都是直接上手，启动一个Hello World应用程序上手。所以这篇文章文章顺着我的思路，看看这个框架对于搭建文档站有多么的方便。

　　初始化项目

　　npx @docusaurus/init@latest init [名称] [模板]

npx @docusaurus/init@latest init docusaurus-luffyzh-website classic

　　初始化后，启动项目，我们看看效果：

　　简单看了一下，基本的内容站点结构就自动搭建好了，包括主页和两个内置的文档页面：Tutorial 和Blog。至于为什么会有两个功能选项卡，后面会介绍，而且它还自动支持深色模式的转换，真是良心。

　　对于文档站来说，无非就是写MD文件，然后在页面上渲染。没什么好说的，所以其实文档站框架的核心就是config配置文件。尝试修改核心配置文件docusaurus.config.js，修改网站的一些基本信息。

　　module.exports = {

title: '前端周同学\'s Blog',

tagline: ' 公众号: 前端周同学',

url: 'https://github.com',

baseUrl: '/',

onBrokenLinks: 'throw',

onBrokenMarkdownLinks: 'warn',

favicon: 'img/favicon.ico',

organizationName: 'luffyZh', // Usually your GitHub org/user name.

projectName: 'docusaurus-luffyzh-website', // Usually your repo name.

themeConfig: {

navbar: {

title: '前端周同学',

logo: {

alt: 'My Site Logo',

src: 'img/logo.svg',

},

items: [

{

type: 'doc',

docId: 'intro',

position: 'left',

label: '文档',

},

{

position: 'left',

to: '/blog',

label: '博客',

},

{

href: 'https://github.com/luffyZh/docusaurus-luffyzh-website',

label: 'GitHub',

position: 'right',

},

],

},

footer: {

style: 'dark',

links: [

{

title: 'Docs',

items: [

{

label: '文档',

to: '/docs/intro',

},

],

},

<p>

{

title: &#39;Blog&#39;,

items: [

{

label: &#39;博客&#39;,

to: &#39;/blog&#39;,

},

],

},

{

title: &#39;更多&#39;,

items: [

{

label: &#39;掘金&#39;,

href: &#39;https://juejin.cn/user/96412752681079&#39;

},

{

label: &#39;GitHub&#39;,

href: &#39;https://github.com/luffzh/docusaurus-luffyzh-website&#39;,

},

],

},

],

copyright: `Copyright © ${new Date().getFullYear()} 前端周同学～`,

},

prism: {

theme: lightCodeTheme,

darkTheme: darkCodeTheme,

},

},

};

</p>

　　如您所见，我只是更改了一些简单的配置文本。内容站已经很时尚了。这真的很简单。忍不住继续往下探索~目录结构

　　我们看一下整个项目的目录结构，边看边了解每个目录下每个文件对应的功能。

　　docusaurus-luffyzh-website

├── blog // 包含博客的 Markdown 文件。 若您不需要博客，您可删除此目录

│ ├── 2019-05-28-hola.md

│ ├── 2019-05-29-hello-world.md

│ └── 2020-05-30-welcome.md

├── docs // 包含文档的 Markdown 文件。 您可在 sidebars.js 中自定义文档的侧边栏顺序。

│ ├── doc1.md

│ ├── doc2.md

│ ├── doc3.md

│ └── mdx.md

├── src // 如页面或自定义 React 组件一类的非文档文件

│ ├── css

│ │ └── custom.css

│ └── pages // 放在此处的所有文件都将被转换成网站页面，类似 Next.js。

│ ├── styles.module.css

│ └── index.js

├── static // 静态资源

│ └── img

├── docusaurus.config.js // 站点配置文件

├── package.json

├── README.md

├── sidebars.js // 用于指定侧边栏中的文档顺序

└── yarn.lock

　　看了一圈，发现 Docusaurus 的配置和功能真的很简洁，目的也很明确。感觉是专门为内容站打造的。框架本身只为开发者开放了两个口子，一个是文档（主要用途之一：文档站，上面也提到有这么多文档站用它来生成。），另一个是博客。如上所述，这两个功能是不同的，那么有什么区别呢？

　　该文件夹专门用于生成文档站的核心。它在识别.md文件的同时，还会解析以下子目录，生成目录树结构的侧边栏，如下图所示：

　　

　　【文档规则】：文档的.md可以直接写内容，和普通的Markdown文档写的完全一样。唯一需要注意的是，侧边栏中的文件顺序可以通过标题显示：

　　---

sidebar_position: 3 // 此篇文档显示在第三个顺序

---

　　这个文件夹是用来生成blog文章的，也可以识别.md文件，但是不同的是不能识别目录，生成的侧边栏的顺序是按照文件名排序的~如下图：

　　【文档规则】：博客的md文件头需要按照一定的规则匹配识别，如下：

　　---

slug: first-post // 转化成路由 -> /blog/first-post

title: First Post // 转化成文档标题

author: luffyZh // 转化成文章作者昵称

author_title: 周公子 @掘金 // 转化成作者标题

author_url: https://github.com/luffyZh // 转化成作者链接

author_image_url: https://avatars.githubusercontent.com/u/17840558?s=60&v=4 // 转化成头像

tags: [test] // 转化成分类标签

---

这里直接写标题以外的内容。

　　比较的

　　上手非常简单，说实话，感觉还不错，而且其实大部分开发者如果不关心建站，看到后就能想出一个非常规整的文档和博客站点。那么既然是生成静态内容站的工具，那么它有哪些优势呢？例如，对于大多数内容网站来说，我们看到的大部分文档需求应该是 Gitbook、VuePress，甚至是语雀和飞书。相信大家还是想知道，为什么选择 Docusaurus 而不是其他框架呢？总是有原因的。对于答案，我们仍然可以从官网开始，让它告诉我们，它本身并不是一个 KPI 框架，而是真正可以帮助开发者解决文档构建的痛点。

　　如果你用过 Gatsby，相信大家应该都知道 Gatsby 是由 Graphql 驱动的。如果你只做一个文档内容站，那么使用 Gatsby 就有点矫枉过正了。当然，盖茨比很棒。

　　用屠宰刀杀鸡是描述使用 Next.js 构建文档站点的完美方式。Next.js 作为 React 社区最好的混合框架，可以做这么多事情，SSR、PWA、SSG 等等，所以还是那句老话，艺术界有专攻。如果单纯使用 Next.js 开发自己的，可以，但是有一定的成本，如果只想专注于写文档和搭建文档站点，没必要使用 Next.js。这把大刀。

　　前面说过，朋友说没用过 VuePress，因为他是 React 技术栈，所以可以说 Docusaurus 是 React 社区对 VuePress 进行基准测试的文档构建框架。

　　Gitbook 应该是很多开源工具官方文档的最佳选择，但是因为自己团队的理念逐渐改变，重点逐渐转向商业产品，所以流失了很多用户。最熟悉的就是Redux文档从Gitbook改成了Docusaurus，Docusaurus的理念是对所有用户免费（当然不知道以后会不会改，不过挺好的背靠一棵大树，坐拥脸书的金子

　　这里我想说的是，Docusaurus官网的每个框架都值得学习。它在比较其他框架时不会贬低任何框架，而是在内容站点上讲述每个框架的优缺点。，并诚恳地表示自己借鉴了对方框架的一些优点。和很多框架相比，确实比很多框架为了抬高自己、贬低对方的行为要好很多。更详细的对比和介绍可以参考官方文档。我在这里只是一个简短的总结。与其他工具比较

　　Advance Docusaurus - Advance

　　写进阶的时候，其实觉得这次给朋友的推荐是对的。如果你只是想做一个内容文档站，基本上十分钟就可以搭建一个很像样的内容。网站，包括文档和博客，只需要按照官方文档的规则编写即可。

　　但是，在学习一个新框架的过程中，我希望尽可能地使用它的所有功能。可能没有那么深入。尝一尝就够了。如果以后有类似的需求，可以直接使用，因为它已经在你的知识库中了~

　　部署

　　一个基本的功能文档博客内容站点已经完成，但仍仅限于本地。接下来看看如何部署到公网，不管是自己看还是分享，都很方便。这里我简单介绍两个：Github Pages 和 Vercel。

　　部署 Github Pages 本来很简单，但是由于某种原因，权限验证有点棘手，这里将详细介绍。

　　官方声明：将你的文档站点部署到github只需要一个过程，即运行命令GIT_USER=your_username &amp;&amp; yarn deploy。但是经过我的实践，因为有些仓库有一定的权限设置，所以无法部署成功，如下图所示：

　　因此，需要其他方法才能成功部署。

　　周的动手实践：

　　// build.sh

GIT_USER=your_github_username GIT_PASS=your_personal_token yarn deploy

　　关于个人token的生成方式以及可能遇到的问题，这里有两个网站，方便大家排查问题。

　　生成您的个人令牌

　　如果生成token后部署失败，很有可能是你的仓库使用的是ssh协议而不是https协议，需要在这里切换。ssh -&gt; https

　　在那之后，肯定会好的。

　　看看我们最终效果部署成功，搞定，直接看效果~

　　其实你也可以使用 Github Actions 进行自动部署和构建。由于时间关系，大家可以自己试一试。官方文档有详细的文档，说的很清楚了~

　　我介绍了一些曲折的 Github Pages。接下来，我将介绍 Vercel。相信这里不会有太多的波折。因为我经常使用 Vercel，所以我觉得 Vercel 部署静态网站真的不需要做很多事情。什么都不说，直接上班。

　　首先，进入 Vercel，然后导入我们的 Github 存储库项目。

　　然后，你什么都不用做，直接点击发布，因为 Vercel 会帮我们识别仓库类型，只要支持，都是一键部署。

　　部署后的效果如下：

　　哎呀，我是不是误付了钱？我最信任的 Vercel 也离开了我？别着急，我们来仔细看看Vercel的强大能力，因为我们已经部署过一次Github Pages，所以我们的配置文件其实是按照Github Pages来配置的，所以比如说baseUrl这个字段在我们的项目中由于 Github Pages 的特殊性，配置为 /repo-name/，但 Vercel 没有 Github Pages 的限制。baseUrl就是/，所以我们新建一个分支，feature/vercel，修改配置后重新部署，回到Vercel，分支部署切换到feature/vercel，看看效果：

　　我不会多说，它是完美的。至此，介绍了两种非常方便的文件站部署方式。

　　丰富的功能

　　在文档内容站的初始化过程中，Docusaurus为开发者做了很多工作，比如首页的生成、路径的配置、暗黑模式的适配等。那么除了这些功能之外，还有其他我们没有接触过的功能吗？当然还有很多。在这里，我将简要介绍一些。其他观察者可以在自己搭建项目的过程中探索探索~

　　整套解决方案:SEO站群系统解决方案

　　站群客户需求：采用有机排名的机制和技术;建立站群;通过站群的形式化优化，得到网站关键词的排名，有效避免了分类信息或其他分类信息的排名不足。

　　方案要求

　　站群，一般指同一种

　　

　　用户要形成多个网站，为了提高每个网站在搜索引擎上的权重，分别为一个或几个网站配置一个独立的IP，这是网站SEO优化的重要部分，如果这些网站结构或内容好且大致相同，那么就更需要独立的IP来支持，否则这样的网站域名解析为同一IP， 搜索引擎很容易将其识别为垃圾邮件网站网站并且权重自然不会增加。VPS必须稳定，不稳定，即使它收录，重量也不会上升。

　　溶液

　　国内IP地址不足，需要记录网站域名，因此不太适合构建站群服务。我们可以选择海外服务器，独立的IP地址不贵，可以省去备案的麻烦。如果您对网站速度有严格的要求，可以选择香港服务器，韩国服务器。

　　

　　四、方案的价值

　　1） 低成本

　　2）选择性强：丰富的海外资源供您选择

　　3）稳定性强：24小时在线维护，保证服务器正常运行。