活文档

[WangShuXian6]

活文档

[WangShuXian6]

docusaurus

https://docusaurus.io/zh-CN/docs/
https://www.docusaurus.cn/docs

⚡️ Docusaurus 能够帮助您快速创建一个 精美的文档网站。

💸 定制一套技术栈是非常昂贵的。相反，Docusaurus 让您 只需专注于内容，编写 Markdown 文件即可。

💥 准备好迎接更多功能了吗？还有版本控制、i18n、搜索和主题定制等 高级功能。

💅 向 最好的 Docusaurus 网站 借鉴灵感。

🧐 Docusaurus 是一款 静态网站生成器。它利用 React 的全部功能来构建具有快速客户端导航功能的 单页应用程序（single-page application），从而使您的网站具有交互性。它提供了开箱即用的 文档功能，也可用于创建 任何类型的网站（例如 个人网站、产品展示、博客、营销落地页面等）。

🎯 搜索引擎友好：
为每个可能的路径生成静态的 HTML 文件。
页面级的搜索引擎优化，帮助用户直接访问与他们手头问题相关的官方文档。
📝 Powered by MDX:
通过嵌入到 Markdown 中的 JSX 和 React 编写交互式组件。
在实时编辑器中演示您的代码，让您的用户当场爱上您的产品。
🔍 搜索：您的整个网站都支持搜索功能。
💾 文档版本管理：帮您保持文档与项目版本同步。
🌍 国际化 (i18n)：将您的汪涵翻译成多种语言。

安装

npx create-docusaurus@latest my-website classic

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

启动网站

cd my-website
npx docusaurus start

部署

为生产环境构建网站的静态文件

pnpm run build

在部署到生产环境前，事先进行本地测试
注意这之前必须先 build

pnpm run serve

常见的托管选择：

Self hosting with an HTTP server like Apache2 or Nginx.
Jamstack providers (e.g. Netlify and Vercel). 我们会以它们为参考，但同样的道理也可以适用于其他提供商。
GitHub Pages (by definition, it is also Jamstack, but we compare it separately).

Self-Hosting

pnpm run serve --build --port 80 --host 0.0.0.0

Deploying to Netlify

docusaurus.config.js

export default {
  url: 'https://docusaurus-2.netlify.app', // 不带尾斜线的网站地址
  baseUrl: '/', // 相对于仓库的站点根目录
  // ...
};

Deploying to Vercel

Deploying to GitHub Pages

Docusaurus 提供了一种轻松发布到 GitHub Pages 的方法，每个 GitHub 仓库都免费附带该服务。
概述​

通常，发布过程会涉及到两个仓库（至少是两个分支）：包含源文件的分支，以及包含将使用 Github Pages 提供（给用户）的构建输出的分支。 在下面的教程中，它们将分别被称为“源”和“部署”。

每个 GitHub 仓库都关联有一个 GitHub Pages 服务。 如果部署仓库名为 my-org/my-project（其中 my-org 是组织名称或用户名），则部署后的网站将显示在 https://my-org.github.io/my-project/。 如果部署仓库名为 my-org/my-org.github.io（组织 GitHub Pages 仓库），则网站将显示在 https://my-org.github.io/。
信息

如果您想将自定义域名用于 GitHub Pages，请在静态目录下创建一个CNAME文件。静态目录中的所有内容都将复制到构建目录的根目录中以供部署。使用自定义域名时，您应该能够将baseUrl：'/projectName/'移回baseUrl：'/'，并将您的url设置为自定义域名。

您可以参考 GitHub Pages 的文档用户、组织和项目页面以获取更多详细信息。

GitHub Pages 从默认分支（通常是master/main）或gh-pages分支中，从根目录或/docs文件夹中提取部署就绪的文件（docusaurus build的输出）。您可以通过仓库中的设置 > 页面
进行配置。 这个分支会被称作「部署分支」。

我们提供了一个docusaurus deploy命令，它可以帮助您将您的网站从源分支部署到部署分支，只需一个命令：克隆、构建和提交。

docusaurus.config.js设置​
首先，修改您的docusaurus.config.js并添加以下参数：

参数	描述
organizationName	拥有部署仓库的 GitHub 用户或组织。
projectName	部署仓库的名字。
deploymentBranch	分支的名称。对于非组织的GitHub Pages仓库（projectName不以.github.io结尾），它默认为'gh-pages'。否则，它需要通过配置字段或环境变量显式定义。
这些字段也有环境变量对应项，优先级更高：ORGANIZATION_NAME、PROJECT_NAME和DEPLOYMENT_BRANCH。

示例：

docusaurus.config.js

export default {
  // ...
  url: 'https://endiliey.github.io', // Your website URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  trailingSlash: false,
  // ...
};

默认情况下，GitHub Pages 通过 Jekyll 运行已发布的文件。由于 Jekyll 会丢弃任何以 _开头的文件，建议您通过在静态目录中添加一个名为 .nojekyll的空文件来禁用 Jekyll。

Environment settings

参数	描述
USE_SSH	设置为使用SSH而非默认的HTTPS连接GitHub仓库。如果源仓库的URL是SSH URL（例如[email protected]:facebook/docusaurus.git），则USE_SSH会被推断为true。
GIT_USER	拥有部署仓库推送权限的GitHub账户的用户名. 对于你自己的仓库，这一般会是你自己的 GitHub 用户名。 不使用 SSH 时必填，使用 SSH 时则会被忽略。
GIT_PASS	git用户的个人访问令牌（由GIT_USER指定），用于非交互式部署（例如持续部署）
CURRENT_BRANCH	源分支。通常情况下，分支将是主分支或主分支，但也可以是除 gh-pages 以外的任何分支。如果未为此变量设置任何内容，则将使用调用 docusaurus 部署的当前分支。
GIT_USER_NAME	git config user.name 推送至部署仓库时使用的值
GIT_USER_EMAIL	git config user.email 推送至部署仓库时使用的值

GitHub 企业安装版应该和 github.com 的工作方式一致。你只需要在环境变量中设置组织的 GitHub 企业主机即可。

参数	描述
GITHUB_HOST	你的 GitHub 企业网站的域名。
GITHUB_PORT	你的 GitHub 企业网站的端口。

Deploy

最后，要把你的网站部署到 GitHub Pages 上，请运行：

GIT_USER=<GITHUB_USERNAME> yarn deploy

从 2021 年 8 月开始，GitHub 要求所有命令行登录都使用个人访问令牌，而不是密码。当 GitHub 提示你输入密码时，请输入个人访问令牌。更多信息请参阅GitHub 文档。
或者，你可以使用 SSH（USE_SSH=true）登录。

通过 GitHub Actions 触发部署

GitHub Actions 允许您直接在代码库中自动化、自定义和执行软件开发工作流。
以下工作流示例假定您的网站源代码位于代码库的主分支中（源代码分支为主），并且您的发布源配置为使用自定义 GitHub Actions 工作流进行发布。

我们的目标是：
-- 当有人向
main
分支提出新的拉取请求时，有一个操作可以确保网站成功构建，而无需实际部署。这个操作称为
test-deploy
。
-- 当拉取请求合并到主分支或有人直接推送到主分支时，它将被构建并部署到 GitHub Pages。这个工作将被称为部署。

下面是两种通过 GitHub Actions 部署文档的方法。根据你的部署仓库的位置，选择下面相应的选项卡：
-- 源代码仓库和部署仓库是同一个仓库。
-- 部署仓库是一个远程的仓库，与源代码不同。此方案的说明假设发布源代码是gh-pages分支。

源代码仓库和部署仓库是同一个仓库

虽然你可以在同一个工作流文件中定义这两个工作，但原始的部署工作流在 PR 检查套件状态中总是被列为跳过，这并不能反映实际状态，对审查过程也没有任何价值。所以，我们建议把它们作为单独的工作流来管理。

GitHub 操作文件

添加这两个工作流文件：

这些文件假设你使用的是 Yarn。如果你使用 npm，请相应地将 cache: yarn、yarn install --frozen-lockfile、yarn build 改为 cache: npm、npm ci、npm run build。

如果你的 Docusaurus 项目不在仓库根目录，你可能需要配置一个默认工作目录，并相应地调整路径。
.github/workflows/deploy.yml

name: 部署到 GitHub Pages

on:
  push:
    branches:
      - main
    # 如果你想要进一步定义触发、路径以及其他内容，请检阅 Github Actions 文档
    # https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: 构建 Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          #cache: yarn

      - name: 安装依赖
        run: yarn install
        #run: yarn install --frozen-lockfile
      - name: 构建网站
        run: yarn build

      - name: 上传构建制品
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

      - name: Cache Yarn dependencies
        uses: actions/cache@v2
        with:
          path: ~/.cache/yarn
          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-

  deploy:
    name: 部署到 GitHub Pages
    needs: build

    # 给予 GITHUB_TOKEN 进行 Pages 部署所必须的权限
    permissions:
      pages: write # 以部署到 Pages
      id-token: write # 以验证部署来自恰当的源

    # 部署到 Github Pages 环境
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: 部署到 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

.github/workflows/test-deploy.yml

name: 测试部署

on:
  pull_request:
    branches:
      - main
    # 如果你想要进一步定义触发、路径以及其他内容，请检阅 Github Actions 文档
    # https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: 测试部署
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          #cache: yarn

      - name: 安装依赖
        run: yarn install
        #run: yarn install --frozen-lockfile
      - name: 测试构建网站
        run: yarn build

      - name: Cache Yarn dependencies
        uses: actions/cache@v2
        with:
          path: ~/.cache/yarn
          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-

新建 gh-pages 分支

确保 设置-pages-Build and deployment-Branch 正确

确保github acitons workflows 具有写入仓库的权限[默认只能读取仓库]

设置-actions-general-Workflow permissions-Read and write permissions

网站未正确部署？

在推送到 main 分支后，如果你没有看到你的站点被发布到想要的位置（比方说，访问后发现“这里没有 Github Pages 站点”，或是显示你仓库里的 README.md 文件），尝试以下步骤：
等3分钟，然后刷新一下。 GitHub 页面可能需要几分钟时间才能接收到新文件。
检查你仓库的入口页上次提交的标题旁是否有个绿色的小对勾。如果有，那就表明 CI 通过了。 如果你看到的是一个叉，那就说明构建或者部署失败了，你应该检查日志以获取更多调试信息。
点击对勾，确保你看到的是“部署到 Github Pages”工作流。 如果你看到的名称是类似“pages build and deployment /deploy”（即“页面构建和部署”）这样的，这就表明你的自定义部署工作流根本无法触发。确保将 YAML 文件放置在 .github/workflows 文件夹下，并正确设置触发条件（例如，如果您的默认分支是“master”而不是“main”，则需要更改 on.push 属性）。
在仓库的设置 > 页面下，确保将“源”（这是部署文件的源，而不是我们术语中的“源”）设置为“gh-pages”+“/（根目录）”，因为我们使用gh-pages作为部署分支。
如果你正在使用自定义域名：
如果你正在使用自定义域名，请验证你是否设置了正确的 DNS 记录。请参阅GitHub pages 文档中有关配置自定义域名的内容。此外，请注意，DNS 修改可能需要24小时才能通过互联网传播（注：即 DNS 解析生效）。

部署仓库是一个远程的仓库，与源代码不同

最终页面地址

https://wangshuxian6.github.io/cornerstone3D-doc/
wangshuxian6 为组织或用户名
cornerstone3D-doc为仓库名

注意

docusaurus.config.ts 的 onBrokenLinks: 'warn',//'throw',//页面的链接到本地文件的链接无效时会如何

如果是 'throw' ，则在 Docusaurus found broken links! 时报错。