侧边栏壁纸
  • 累计撰写 74 篇文章
  • 累计创建 45 个标签
  • 累计收到 4 条评论

目 录CONTENT

文章目录

在线文档生成工具Docusaurus入门:如何安装

码峰
2022-08-31 / 0 评论 / 0 点赞 / 190 阅读 / 1,486 字 / 正在检测是否收录...
温馨提示:
本文最后更新于 2022-08-31,若内容或图片失效,请留言反馈。部分素材来自网络,若不小心影响到您的利益,请联系我们删除。

Docusaurus简介

Docusaurus是一个静态网站生成器,它是用 React 写的源代码,然后编译成静态的 HTML + CSS + JS。支持 Markdown语法,并且Markdown 是用的mdx,也就是支持 jsx 语法的Markdown,无缝结合 React, 还可以引入自定义组件,支持插件,还有主题也可以写自定义的组件,把默认的主题的某一个组件给覆盖掉,特别方便,尤其适合用于写在线的手册,文档之类的场景,还可以写博客。
中文官网:https://www.docusaurus.cn/

如何安装

环境要求

Node.js:16.14及以上版本

可以通过执行 node -v 命令来查看当前所用的 Node.js 版本),可以使用 nvm管理同一台计算机上安装的多个 Node 版本。
当安装 Node.js 时,建议选中与依赖项相关的所有复选框。

脚手架项目模板

安装Docusaurus 最简单的方法是使用脚手架模板搭建 Docusaurus网站的雏形。可以在新的空仓库中或已有的仓库中的运行如下命令:

npx create-docusaurus@latest my-website classic

这个命令将创建一个包含脚手架文件的新目录。如下图所示:
image-1661955569344
这里推荐使用 classic 模板,可以快速上手,classic模板包含 @docusaurus/preset-classic 插件,这个插件包含了对标准文档、博客、独立页面(custom pages)和 CSS 框架(支持夜间模式)的支持。使用 classic 模板可以快速启动并运行,在以后对 Docusaurus 比较加熟悉滞后,可以做自定义。
另外,还可以通过传递 --typescript 参数来生成 TypeScript 版本的脚手架文件,命令如下:

npx create-docusaurus@latest my-website classic --typescript

执行 npx create-docusaurus@latest --help 或查看其 API 文档,可以了解所有可用参数的详细信息。

项目结构

假设,已经选择了classic模板,并且站点命名为 my-website,在新目录 my-website/ 下可以看到以下目录结构:

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

目录结构说明

  • /blog/ - 包含博客的 Markdown文件。如果不需要使用博客功能,则可以删除改目录。如果要使用博客,还可以通过设置path 参数来改变该目录的名称。
  • /docs/ - 包含文档的 Markdown文件。可在 sidebars.js 中设置文档在侧边栏中的顺序。如果不需要使用文档的功能,则可以删除该目录。
  • /src/ - 非文档的文件,例如独立页面(pages)或自定义的 React 组件。将非文档的文件集中在此目录下可以更轻松地进行管理,以方便进行某些格式校验或处理。
  • /src/pages - 这个目录中的任何后缀名为JSX/TSX/MDX的文件都将被转换为网站的独立页面(page)。
  • /static/ - 存放静态文件的目录。此处的所有内容都将被复制到最终的 build 目录的根目录下。
  • /docusaurus.config.js - 包含站点配置的配置文件。
  • /package.json - Docusaurus 网站实际上是一个React应用程序,所以,可以在其中安装和使用所需的任何 npm软件包。
  • /sidebars.js - 生成文档时使用此文件来指定侧边栏中的文档顺序

单一仓库(Monorepos)

如果在现有的项目中使用 Docusaurus 的话,单一仓库(monorepo)模式可能更合适。单一仓库模式(Monorepos)可以在多个类似项目之间共享依赖关系。例如,你的网站可能需要使用本地的软件包来展示最新的功能,而不是依赖已发布的版本;你的项目的贡献者也可以在实现某些功能时方便地更新文档。一个单一仓库(monorepo)的文件夹的结构如下:

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

在这种情况下,应该在 ./my-monorepo 目录下运行 npx create-docusaurus 命令。

预览编辑的文档

如果想要在编辑文件时预览更改,可以启动一个本地服务器并启动你的网站,最新的修改就能立即反映出来了。

cd my-website
npm run start

默认情况下,浏览器将打开 http://localhost:3000 地址,如下图:
image-1661956090803

image-1661956108513
如果看到以上输出,那么恭喜你!你成功创建了第一个 Docusaurus 网站!

构建生成

实际上,Docusaurus是一个静态网站生成器,因此我们需要将网站构建到静态内容目录中,并将其放置在 Web 服务器上,以便可以对其进行查看。运行如下命令来构建网站:

npm run build

生成的内容将被放置到 /build 目录下,该目录可以复制到任何静态文件托管服务上,例如 GitHub pages、Vercel 或 Netlify。

0

评论区