--- # 主题列表：juejin, github, smartblue, cyanosis, channing-cyan, fancy, hydrogen, condensed-night-purple, greenwillow, v-green, vue-pro, healer-readable, mk-cute, jzman, geek-black, awesome-green, qklhk-chocolate # 贡献主题：https://github.com/xitu/juejin-markdown-themes theme: juejin highlight: --- ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dd250be5a5974bb69166e5be2f76a383~tplv-k3u1fbpfcp-watermark.image?) ## 前言相信大家在使用公司文档的时候，都会有很多使用方面的痛点，怎么能更加有效的共建，如何选择更方便快捷，支持多种功能场景的文档中心就显得尤为重要。目前公司级的文档，部门、业务等场景的不同，统一上传wiki文档进行维护。业务种类的繁多，导致信息不能共建和共享，用户查询时间和使用复杂度不断提高，再加上wiki的使用和维护成本相对较高，所以更需要自建一套，属于自己的企业级文档中心。目前大厂的主流技术栈是[React](https://react.docschina.org/)，我也参考了市面上包括 [Next.js](https://nextjs.org/)、[Nextra](https://github.com/shuding/nextra)、[VuePress](https://vuepress.vuejs.org/)、[MkDocs](https://www.mkdocs.org/)、[GitBook](https://www.gitbook.com/)在内的文档框架，最终选型了基于React作为核心的[Docusaurus](https://docusaurus.io/zh-CN/)框架，来完成这一工程，同时我也建立了文档共建群，方便大家一起使用讨论。 ## 框架对比分析适合自身业务的框架才是一个好框架。相信每个人在这一阶段，或多或少都对自己的公司和业务有一定的了解，所以选对一个符合自身技术栈，对以后的开发、维护和推广是至关重要的。以下是我在做技术选型时候的一些分析, 首先看下其他设计框架相对来说的特性和问题： | 框架 | 优缺点 | | --- | --- | | [Gatsby](https://www.gatsbyjs.com/) | 学习成本高，GraphQL 是 Gatsby 的核心，但搭建不需要 GraphQL | | [Next.js](https://nextjs.org/) | 是一款热门的 React 混合框架。可以帮助构建出色的文档网站，但它并不着重于文档功能本身，而且需要你手动实现 Docusaurus 所自带的功能 | | [Nextra](https://github.com/shuding/nextra) | 是一款基于 Next.js 的静态站点生成器。它的功能与 Docusaurus 相比要匮乏 | | [VuePress](https://vuepress.vuejs.org/) | 基于Vue驱动，与技术展不符合| |[MkDocs](https://www.mkdocs.org/) | 纯js文档，技术比较陈旧，不过样式好看| [GitBook](https://www.gitbook.com/)| 整体框架的设计偏清爽，诸多开源项目都在使用。但随着它把重点逐渐从开源工具转向商业产品，它不再符合开源项目文档网站的需要。结果就是，许多项目转用了其他产品。GitBook 只对开源和非营利团队免费。 Docusaurus 则对所有人免费| 相对上述的框架，[**Docusaurus**](https://docusaurus.io/zh-CN/) 框架，有以下的几个特点： - 使用 React 实现扩展与自定义，符合我们的技术栈； - 提供你自己的 React 组件，插件也基于react，支持markdown生成页面，基础插件能力够用； - 使用基础模板搭建网站，随后使用进阶功能及插件，可开发高阶的组件进行使用； - 开放你的插件源码，与社区共享，有较强大的社区体系，持续在维护； ## 环境准备官方建议的Node版本相对较高，所以[Node.js](https://nodejs.org/en/download/)版本，至少16.14以上的版本。多版本切换可以安装[ nvm ](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Fnvm-sh%2Fnvm%2Fblob%2Fmaster%2FREADME.md "https://github.com/nvm-sh/nvm/blob/master/README.md") 管理，`Mac` 推荐 `HomeBrew` 安装，方便更新管理，附带：[Mac Homebrew 安装与卸载](https://link.juejin.cn/?target=https%3A%2F%2Fblog.csdn.net%2Fzz00008888%2Farticle%2Fdetails%2F113867051 "https://blog.csdn.net/zz00008888/article/details/113867051")。 Node.js 16.14 或更高版本（可以通过执行 `node -v` 命令来查看当前所用的 Node。js 版本）。你可以使用 nvm 管理同一台计算机上安装的多个 Node 版本。 ## 初始化运行初始化一个classic模版项目，并运行本地构建部署 ``` npm create-docusaurus@latest my-website classic cd my-website npm install npm run start ``` 默认情况下，浏览器将打开 http://localhost:3000 地址。用户所写的markdown文档都放在`docs`目录下，个人blog放在`blog`文件夹下，你也可以在 Markdown 独立页面中使用 React 的全部功能，具体可以参考 [MDX](https://mdxjs.com/) 文档，基本文档结构如下 ``` my-website ├── blog │ ├── 2019-05-28-hola.md │ ├── 2019-05-29-hello-world.md │ └── 2020-05-30-welcome.md ├── docs │ ├── doc1.md │ ├── doc2.md │ ├── doc3.md │ └── mdx.md ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── styles.module.css │ └── index.js ├── static │ └── img ├── docusaurus.config.js ├── package.json ├── README.md ├── sidebars.js └── yarn.lock ``` ## 构建 `Docusaurus` 是一个静态网站生成器，因此我们需要将网站构建到静态内容目录中，并将其放置在 Web 服务器上，以便可以对其进行查看。运行一下命令构建： ``` npm run build ``` 你可以将网站部署到类似 [Vercel](https://vercel.com/)、[GitHub Pages](https://pages.github.com/)、[Netlify](https://www.netlify.com/)、[Render](https://render.com/docs/static-sites)、[Surge](https://surge.sh/help/getting-started-with-surge) 等静态网站托管服务上。我建立的文档中心是部署在公司服务器上的，所以需要配置`Dockerfile`, 自动化执行打包构建的命令，通过`nginx`做资源代理, 具体内容可以移步gitlab `cloud-docs`项目具体了解，这里不做过多赘述。 ## 插件化 `Docusaurus`本身提供了很多功能插件，来实现复杂的交互场景，同时也支持用户可以自己创建`自定义plugin`来实现自身的业务场景，api配置可以参考官方的[plugins](https://www.docusaurus.cn/docs/api/plugins)。以下以多实例文档插件 [**@docusaurus/plugin-content-docs**](https://www.docusaurus.cn/docs/api/plugins/@docusaurus/plugin-content-docs) 举例： | 字段 | 功能描述 | | --- | --- | |id|唯一标识ID，这里需要与docs文件下的文档路径名保持一致| |path|文档内容目录的文件系统路径，相对于站点目录| |routrBasePath|站点文档部分的 URL 前缀。不要包含末尾斜杠。如果要部署没有基础路径的文档，请使用 /| |sidebarPath| 侧边栏配置的路径。 false 会禁用侧边栏，undefined 会创建一个完全自动生成的侧边栏, 也可以自定义路由菜单| 在 `docusaurus.config.js` 文件中，找到`plugins`，新增文件目录配置 ``` docusaurus.config.js plugins: [ [ '@docusaurus/plugin-content-docs', { id: 'example', path: 'docs/example', routeBasePath: 'example', sidebarPath: require.resolve('./sidebars.js'), }, ], ... ] ``` 通过上述配置就可以在网站自定义`example`路由实例。 ## 自定义路由 `Docusaurus`的基本路由结构 ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0c44b1539aec4531be9fec4f0db7edc7~tplv-k3u1fbpfcp-watermark.image?) 它可以自动根据文档结构生成路由，无需手动配置，但如果需要自定义某些路由，例如在顶部导航展示对应文档入口，也支持自定义路由。在 `docusaurus.config.js` 文件中，通过`sidebarPath`引入路由配置，默认如下： ``` const sidebars = { //默认 tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // By default, Docusaurus generates a sidebar from the docs folder structure ... // 自定义配置 tutorialSidebar: [ 'route1', 'route2', { type: 'route3', label: '可配置的路由', items: ['tutorial-basics/create-a-document'], }, ... ], }; ``` ## 主题配置 `docusaurus.config.js`中还可以配置`导航navs`、`底部footer`、`主题色切换`等交互功能，功能非常齐全，通过插件能力还可以引`全局搜索`功能，这在文档建设时是非常必要的. ``` // 引入全局搜索插件 themes: [ '@docusaurus/theme-live-codeblock', [ require.resolve('@easyops-cn/docusaurus-search-local'), { indexPages: true, hashed: true, language: ['en', 'zh'], highlightSearchTermsOnTargetPage: true, explicitSearchResultPath: true, }, ], ], // 主题配置 themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ colorMode: { defaultMode: 'light', // 默认白昼主题，可配置dark模式 }, docs: { sidebar: { // 侧边栏 hideable: true, }, }, announcementBar: { // 顶部公告配置 id: 'notice', content: '滚动的公告～', backgroundColor: '#2160fd', textColor: '#ffffff', isCloseable: true, }, navbar: { // 顶部导航 title: 'xxx', logo: { // logo ... }, items: [ // 顶部路由 ... ], }, footer: { links: [ { title: '友情链接', items: [ { label: '合作一', href: 'https://www.xxx.com', }, ], }, ... }, ``` ## 自定义页面和MarkDown `Docusaurus`支持react代码写法创建页面，你可以自行编写例如：首页、轮播、上传文件等复杂的功能界面，它也提供了开发者主题、插件能力，去更好的扩展体验。每个独立页面默认是没有任何样式的，你可以添加全局样式`global.css`去配置。 ``` /src/pages/helloReact.js import React from 'react'; import Layout from '@theme/Layout'; import '@css/global.css'; export default function Hello() { return (

Edit pages/helloReact.js and save to reload.

); } ``` MarkDown只要是符合写法规范，`Docusaurus`会自动编译成页面，就和掘金文档一样，同时`Docusaurus` 内置了对 [MDX v1](https://mdxjs.com/) 的支持，这让你可以在 Markdown 文档中编写 JSX 并渲染为 React 组件。 ``` /src/pages/helloReact.js export const Highlight = ({children, color}) => ( {children} ); --- title: my hello page title description: my hello page description hide_table_of_contents: true --- # Hello How are you? Docusaurus green and Facebook blue are my favorite colors. I can write **Markdown** alongside my _JSX_! ``` ## 结语在使用`Docusaurus`搭建文档中心的过程中，我能感受到它强大的文档能力。好的框架能走的长久，也需要拥有较好的社区性和稳定性，这一点`Docusaurus`做的也很好。从1.x发展到2.x版本，该框架始终保持着高频率的更新速度，issues也有很多开发者提出优化跟讨论，最重要的是贴合自身的技术栈，大家都可以参与到项目的共建中来，减少了跨站的技术痛点跟学习成本。无论在开发扩展性、体验性能、构建效率上，它都有非常不错表现，随着需求日益更新，我相信还会越来越好。如果你也想使用 `Docusaurus` ，可以去github为他们提供 showcase，提交的案例也会在官网的 [showcase](https://link.juejin.cn/?target=https%3A%2F%2Fv2.docusaurus.io%2Fshowcase "https://v2.docusaurus.io/showcase") 里展示，一起成为共建者。