跳到主要内容

docusaurus搭建个人wiki

1. docusaudrus简介​

Docusaurus是 Facebook 开源的一个静态网站生成器，主要用来给开源项目生成帮助文档或博客，其功能和Hexo或Jekyll功能类似，可以根据Markdown文件生成静态页面，然后部署到Github Pages之类的纯静态环境。

docusaurus_logo

2. 安装Docusaurus​

参考Docusaurus快速使用教程。

note

Docusaurus是使用Node.js开发的，安装前需确保电脑上已经安装了Node.js。

使用npm安装：

npx create-docusaurus@latest my-website classic

其中my-website就是项目或者文档的名称，classic 是 Docusaurus 的默认模板名称。

安装完成后，进入my-website路径，已生成网站的对应文件

项目结构概要

  • /blog/ - 包含博客的 Markdown 文件。如果你关闭了博客功能，则可以将此目录删除。你还可以通过设置 path 参数来改变此目录的名称。在 博客功能指南 文档中可以找到更多详细信息
  • /docs/ - 包含文档的 Markdown 文件。可在 sidebars.js 中自定义文档在侧边栏中的顺序。如果你关闭了文档功能，则可以删除该目录。你还可以通过设置 path 参数来改变此目录的名称。在 文档功能指南 中可以找到更多详细信息
  • /src/- 非文档文件，例如独立页面（pages）或自定义的 React 组件。你不必严格地遵守将非文档文件放到这里，但是将它们集中在此目录下可以更轻松地进行管理，以便您需要进行某些格式校验或处理
  • /src/pages - 此目录中的任何扩展名为 JSX/TSX/MDX 文件都将被转换为网站的独立页面(page)。 可以在 独立页面（pages）指南 中找到更多详细信息
  • /static/ - 存放静态文件的目录。此处的所有内容都将被复制到最终的 build 目录的根目录下
  • /docusaurus.config.js - 包含站点配置的配置文件。与 Docusaurus 1 中的 siteConfig.js 文件等价
  • /package.json - Docusaurus 网站也是一个 React 应用程序。你可以在其中安装和使用所需的任何 npm 软件包
  • /sidebar.js - 生成文档时使用此文件来指定侧边栏中的文档顺序

运行项目：

npm run start

Docusaurus 编译后会启动一个本地服务器，在浏览器中输入 http://localhost:3000/ 即可访问页面

docusaurus_demo

此时编辑docs或blog文件夹下的markdown文件，会在该页面实时更新。

需要编译静态部署页面可执行如下命令：

npm run build

编译完成后会生成build文件夹，可通过如下命令查看编译生成的网页：

npm run serve

3. 站点信息配置​

  1. 在项目根目录下的’docusaurus.config.js 文件，用于配置站点信息、页头、页脚。
  2. 在项目根目录下的 sidebars.js 文件，用于侧边栏配置。
  3. 在项目根目录的 src 目录，src 目录中又有一个 pages 目录，pages 目录中的 index.js 就是首页文件。在 index.js中有一个 features 数组，数组中的内容就是首页的项目描述。

详细的配置信息可以根据个人喜好进行配置。

tip

官方分享的Docusaurus案例展示，可以借鉴。

4. 部署到GitHub Pages​

4.1 创建GitHub项目仓库​

  • 创建一个项目，然后在setting里面设置GitHub Pages, 把构建的分支改为gh-pages,这个分支是要自己建立的，目前里面什么都不用有，把当前的项目代码都推到master分支。

github_pages_set

  • 参考Github Pages中的路径，配置docusaurus.config.js中的页面url和baseUrl等信息
  url: 'https://taoyukai.github.io', 
  baseUrl: '/tyk_wiki/',

4.2 设置自动部署​

  • 设置push到master分支之后自动部署，这个时候就要用到刚才建立好的gh-pages分支了，在根目录建立.github/workflows/deploy_documentation.yml文件，参考阮一峰大佬的博客

  • 要注意一下ACCESS_TOKEN的配置，这个要提前在github中配置一下。参考github官网

  • 要注意一下CNAME文件，如果你有自己的域名用的不是username.github.io这个域名的话，需要建立CNAME文件，并在里面写上自己的域名。

deploy_documentation.yml文件内容如下：

name: Deploy Github pages
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master
      with:
        persist-credentials: false
    - name: Install and Build
      run: |
        npm install
        npm run-script build
    - name: Deploy
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
        ACCESS_TOKEN: ${{ secrets.DOC_DEPLOY }}
        BRANCH: gh-pages
        FOLDER: build
        BUILD_SCRIPT: npm install && npm run build

4.3 推送项目​

把当前的项目文件都推送到master分支上，这个时候如果没有什么问题，github的action就开始工作自动部署了。

github_pages_actions

5. 部署到Vercel​

Vercel，一个开箱即用的网站托管服务，类似于Github Pages，但比Github Pages强大，速度也快得多。

5.1 注册并登录Vercel​

推荐使用Github账号一键登录。

vercel_login_page

5.2 导入github上的网站项目​

  • 在vercel的Overview菜单下，点击按钮 New Project
  • 在Import Git Repository选项下，选择需要导入的项目，点击Import

vercel_import

5.3 部署项目​

  • 点击Deploy按钮，vercel就开始构建和部署了

    vercel_deploy

构建完之后，可以在Overview菜单下，看到新建的项目,至此项目已经创建完成，可以通过vercel自动配置的子域名访问了。

vercel_deploy_ok

5.4 添加自己的域名​

vercel支持使用自己注册的域名访问。

在Settings->Domains页面下，输入框中填入想设置的域名，点击Add按钮，并设置相应的解析即可。

vercel_add_domains