Skip to main content

配置文档

对于本站点的配置主要参考 技术笔记 进行设置, 根据个人需要进行灵活配置

danger

请根据需要灵活选择, 我是基本按安装了我的所有扩展, 导致我的部署时间变长了, 所以请理性安装

plugin-image-zoom​

单击图片放大插件，效果： 

npm install --save flexanalytics/plugin-image-zoom

plugin-ideal-image (图片懒加载)​

  • 作用 : 生成近乎理想的图像的 Docusaurus 插件（响应式、懒加载及低像素占位图）

如果你想要实现下面的各种扩展或者要写大文档, 建议安装此插件, 避免因为图片太多而导致页面加载时间变长, 关于安装请查看官网: plugin-ideal-image

修改首页方框内容​

20240519001713 修改上述图片中使用红框标识的部分, 前往 src/pages/index.tsx 中进行修改

function HomepageHeader() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <Heading as="h1" className="hero__title">
          {siteConfig.title}
        </Heading>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <Link
            className="button button--secondary button--lg"
            to="/docs/intro">
            Docusaurus Tutorial - 5min ⏱️ 
          </Link>
        </div>
      </div>
    </header>
  );
}

顶栏下拉框​

有时候需要在顶部栏中添加下拉框进行示例, 所以需要对 docusaurus.config.ts 文件进行一些修改

const config: Config = {
  themeConfig: {
    label: 'Docs',
    position: 'left',
    items: [
      {
        label: 'Tutorial',
        to: 'docs/intro',
      },
      {
        label: 'API',
        to: 'docs/api',
      },
      {
        label: 'Guides',
        to: 'docs/guides',
      },
    ],
  }
}

修改 / 页面的图片​

20240522160101

src/pages/index.module.css
.heroBanner {
  padding: 4rem 0;
  text-align: center;
  position: relative;
  overflow: hidden;
  color: white; 
    background-image:
        linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5)),
        url(./img/test.png);
    background-size: cover;
}

Github 部署​

部署项目​

在本地创建好 Docusaurus 网站, 随后在 Github 创建对应的存储库

tip

GitHub 会将命名为 .github.io 的仓库视为一个用户或组织的 GitHub Pages 站点。这意味着该仓库将被用于托管静态网站，并通过 GitHub Pages 服务自动部署到一个特定的域名。 所以如果你是第一个 GitHub Pages 站点,此仓库名称为 username.github.io , 如果有多个请查看 多仓库部署

之后, 前往 Github 个人设置界面创建一个 TOKEN

20240526101631

随后, 前往对应的仓库, 设置仓库的相关内容, 将刚刚获取到的 Token 设置到其中, 名字就不要变了,后面会用到的

20240526101803

将文件同步到 Github 仓库中, 并创建一个分支 gh-branch , 之后再创建一个新的文件

.github\workflows\documentation.yml
# Copyright 2022 zhaoguoxing
# 
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
name: Deploy Arden Github pages
on:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@main
      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.ACCESS_TOKEN }}
        BRANCH: gh-branch
        FOLDER: build
        BUILD_SCRIPT: npm install && npm run build

再进行一次同步操作, 随后再次前往设置操作界面进行再一次的配置, 随后你就会发现 Action 开始部署了, 如果你访问不到网站, 可以尝试重新运行 Github Action

20240526102115

多仓库部署​

如果你有两个相同的网站想要部署在 Github 上， 你可以按照原本的的流程制作， 比如一个是 user.github.io 而另一个可以将存储库设置为 Blog 这样的名称，同时修改 Blog 存储库中的 docusaurus.config.ts 20240525185210

之后进行部署就可以了， 效果如下：

20240525185241

tip

所以没必要买域名， 我傻逼还买了一个域名，真的是亏麻了

绑定自定义域名​

我是在阿里云买的 .top 域名, 10 年花费 188 元, 还是很值的但是需要定好自己的顶级域名不然很贵, 不需要买其他的服务, 也没有什么内容,之后使用 cloudflare 的 DNS, 具体教程可以看下面两个视频

如果你有两个要部署的网站, 但是不知道怎么部署, 你可以参考我的内容, 其实和正常部署一样

20240526002553

代码高亮​

docusaurus 使用 prism 来对不同的语言进行语法高亮，这里 是默认支持的语言列表，如果需要启用更多语言的支持，可以在 docusaurus.config.js 中配置下 additionalLanguages（点 这里 查看 prism 支持的所有语言的列表）:

prism: {
  // prism supported languages: https://prismjs.com/#supported-languages
  additionalLanguages: [
    'java',
    'json',
    'hcl',
    'docker',
    'bash',
    'diff',
    'scss',
    'lua',
    'makefile',
    'ignore',
  ],
  ...
}
tip

建议是按需启用，可尽量减少站点依赖的 js 文件体积。

admonitions 扩展​

原始的 admonitions 功能有限, 我想添加一个问题 admonitions, 就开始了搜索, 最终发现 Creating Custom Admonitions in Docusaurus React App

Question Iconquestion

question 内容

Podcast Iconpodcast

podcast 内容

Book Iconbook

book 内容

图标​

可以直接从 Iconify 进行查看 如果想要实现 admonitions 扩展功能, 建议不要安装 Iconify 了, 这样过于臃肿了, 建议查看 react-icons

20240528110431

卡片链接​

卡片链接测试

卡片链接测试

卡片链接描述信息

嵌入音乐/视频播放器​

只需要安装 react-player 即可

npm install react-player

使用的时候引入依赖直接使用即可

import ReactPlayer from 'react-player'

# 视频链接
<ReactPlayer controls style={{ margin: '0 auto' }} url='video.mp4' />

# 音频链接
<ReactPlayer forceAudio style={{ margin: '0 auto' }} controls url='xxx.mp3' />

更多使用请看官方文档 react-player

待扩展​