Skip to main content

Docusaurus2 快速建站部署GitHub Pages

· 预计阅读时间：3 分钟
摘要

Docusaurus 2 是一款基于React的，性能卓越的静态网站生成器，可用于快速创建常见的内容驱动型网站（例如文档、博客、产品落地页和营销页等），官网文档。 本文将简单讲述Docusaurus的安装创建个人博客项目使用和部署到github ...

1、系统环境准备#

1.1、Node版本#

Node.js >= 10.15.1 版本（运行 node -v 命令查看版本）。你可以使用 nvm 在已经安装了 Node.js 的计算机上管理多个版本的 Node.js

1.2、Yarn版本#

Yarn >= 1.5 版本（运行 yarn version 命令查看版本）。Yarn 是 JavaScript 生态中的高性能软件包管理工具，可取代 npm。虽然这不是严格必须的，但强烈推荐。

2、安装创建项目#

Docusaurus 本质上是一组可以通过 npm 安装的 npm 软件包。安装 Docusaurus 的最简单方法是使用命令行工具，该工具可帮助您搭建 Docusaurus 网站的雏形。

您可以在新的空仓库中或已有的仓库中的运行此命令回车后创建项目

语法

npx @docusaurus/init@latest init [name:项目名称] [template:主题模板]

示例

npx @docusaurus/init@latest init is-zhou classic

3、项目结构#

is-zhou├── 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 文件。如果你不想或不需要博客，则可以将此目录删除。在 博客指南 中找到更多详细信息。
  • /docs/ - 包含文档的 Markdown 文件。可在 sidebars.js 中自定义文档侧边栏的顺序。在 文档指南 中可以找到更多详细信息。
  • /src/ - 非文档文件，例如页面或自定义的 React 组件。你不必严格地将非文档文件放到这里，但是将它们集中在此目录下可以更轻松地进行管理，以便您需要进行某些格式校验或处理
  • /src/pages - 此目录中的所有文件都将转换为网站页面(page)。可以在 页面（pages）指南 中找到更多详细信息。
  • /static/ - 静态文件目录。此处的所有内容都将复制到最终的 build 目录下。
  • /docusaurus.config.js - 包含站点配置的配置文件。与 Docusaurus 1 中的 siteConfig.js 文件等价。
  • /package.json - Docusaurus 网站也是一个 React 应用程序。你可以在其中安装和使用所需的任何 npm 软件包。
  • /sidebar.js - 生成文档时使用此文件来指定侧边栏中的文档顺序。

4、运行项目（本地）#

npm run start
yarn run start

浏览器将打开 http://localhost:3000 。

5、构建项目（本地）#

npm run build
yarn run build

生成的内容将被放置到 /build 目录下，该目录可以复制到任何静态文件托管服务上，比如 GitHub pages

6、基本配置#

6.1、元数据配置#

进入项目根目录下的docusaurus.config.js文件进行设置（查看更多详细配置：https://www.docusaurus.cn/docs/docusaurus.config.js ）

module.exports = {  title: 'is-zhou',  tagline: '你好，我是周周，一名前端工程师',  url: 'https://is-zhou.github.io',//站点顶级主机名  baseUrl: '/',//站点根路径，主机名之后的路径  onBrokenLinks: 'throw',//站点遇到无效链接时采取的行为（抛出错误）构建生产环境时才检测  onBrokenMarkdownLinks: 'warn',//站点遇到断开markdown链接（打印警告）  favicon: 'img/favicon.ico',//网站图标  organizationName: 'is-zhou', // 拥有此源码仓库的 GitHub 用户或组织。部署命令（deployment command）会用到此参数。.  projectName: 'is-zhou.github.io', // GitHub 源码仓库的名称。部署命令（deployment command）会用到此参数。  //此对象包含你所使用的主题所需要的数据。对于 Docusaurus 的默认主题 classic，通过 themeConfig 可以自定义网站的导航条（navbar）和页脚链接（footer links）  themeConfig: {    navbar: {      title: 'is-zhou',//标题      logo: {//图标设置        alt: 'My Site Logo',//图标替代文字        src: 'img/logo.svg',//图标位置      },      //导航栏条目自行增加      items: [        { to: 'blog', label: 'Blog', position: 'right' },        {          to: 'docs/',          activeBasePath: 'docs',          label: 'Docs',//在导航栏上显示的文字          position: 'right',//在导航栏上显示的位置        },        {          href: 'https://github.com/facebook/docusaurus',          label: 'GitHub',          position: 'right',        },      ],    },    footer: {      style: 'dark',      links: [        {          title: '社区',          items: [            {              label: 'GitHub',              to: 'https://github.com/is-zhou',            },            {              label: 'CSDN',              to: 'https://blog.csdn.net/weixin_46473109',            },            {              label: '简书',              to: 'https://www.jianshu.com/u/52f23c4bcc6c',            },          ],        },        {          title: '友情链接',          items: [
          ],        },      ],      copyright: `Copyright © ${new Date().getFullYear()} is-zhou Built with Docusaurus.`,    },  },  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          sidebarPath: require.resolve('./sidebars.js'),          // Please change this to your repo.          editUrl:            'https://github.com/facebook/docusaurus/edit/master/website/',        },        blog: {          showReadingTime: true,          // Please change this to your repo.          editUrl:            'https://github.com/facebook/docusaurus/edit/master/website/blog/',        },        theme: {          customCss: require.resolve('./src/css/custom.css'),        },      },    ],  ],};

7、部署到Github#

Docusaurus提供了一种发布到GitHub Pages的简便方法，每个GitHub存储库都免费提供托管。 首先，修改您的docusaurus.config.js并添加所需的参数：

7.1、Github仓库#

（1）、创建github仓库

  • 登录GitHub创建仓库，仓库名为[github user name].github.io的仓库 （2）、修改docusaurus.config.js文件
Name描述
organizationName拥有存储库的GitHub用户或组织。如果您是所有者，则为您的GitHub用户名。对于Docusaurus，它是拥有Docusaurus的GitHub组织“ facebook ”。
projectNameGitHub存储库的名称。例如，Docusaurus的存储库名称为“ docusaurus”，因此项目名称为“ docusaurus”。
urlGitHub页面的用户/组织页面的URL。这通常是https://_username_.github.io
baseUrl项目的基本URL。对于托管在GitHub页面上的项目，其格式为“ / projectName /”。对于https://github.com/facebook/docusaurus，baseUrl为/docusaurus/。
docusaurus.config.jsmodule.exports = {  // ...  url: 'https://endiliey.github.io', // Your website URL  baseUrl: '/',  projectName: 'endiliey.github.io',  organizationName: 'endiliey',  // ...};

7.2、发布到Github#

发布方式三选一即可（通过命令生成静态文件并将静态文件发布到github上）

（1）、在git Bash中运行如下命令

GIT_USER=<GITHUB_USERNAME> yarn deploy
GIT_USER=<GITHUB_USERNAME> USE_SSH=true yarn deploy

（2）、Windows cmd

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

(3)、PowerShell

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

8、文档功能#

文档功能

9、博客功能#

博客功能

文章目录