README

TL;DR

docker run --rm -it --pull always \
         -v "./Documentation:/project/Documentation" \
         -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
         -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest

简介

一个独立的项目（NodeJS，browsersync），用于将 TYPO3 ReST 文档的更改渲染到浏览器窗口。

文件通过官方 https://github.com/TYPO3-documentation/render-guides 项目进行渲染。有关 TYPO3 文档的更多信息，请参阅 https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingDocForExtension/Index.html。

此项目旨在作为 Docker 容器构建和使用。它不打算本地运行，因为它需要大量的依赖（PHP、composer、NodeJS、nvm），并且基础 TYPO3-Documentation/render-guides 项目不支持作为 Composer 包，因此本地使用不可行。

Docker 容器提供了一个代理服务器，将渲染后的 ReST 文档（作为 HTML）返回给浏览器。您对 ReST 文件的任何更改都将自动触发浏览器窗口的重载。

这允许您在无需手动重新加载浏览器窗口或反复渲染文档的情况下，以某种“所见即所得”的方式查看文档。所有操作都将按需执行。

ReST 非常依赖于所使用的渲染器和其功能，因此您无法真正拥有 ReST 文件的 WYSIWYG 编辑器。此类工具是最接近编辑文件并直接查看其影响的工具。

通用用法

此项目依赖于在您的宿主机上执行 Docker 容器的能力。

如果您更喜欢 Podman，也可以使用。在这种情况下，将 docker 命令替换为 podman。

您可以在任何项目目录中使用提供的 Docker 容器

docker run --rm -it --pull always \
         -v "./Documentation:/project/Documentation" \
         -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
         -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest

这将在 localhost 端口 5173 上启动一个服务器，因此您可以指向类似这样的 URL

https://:5173/Documentation-GENERATED-temp/Index.html

输出

Docker 容器将显示运行服务器的 vite 控制台，您可以与之交互。它将一直运行，直到您输入 q（“退出”）或使用 Ctrl-C 来结束进程。

每当您修改 .rst 或 .html 文件时，您将看到有关执行操作的控制台输出。

演示项目

有一个简单的演示项目，展示了如何使用模拟的文档目录。

https://github.com/garvinhicking/demo-typo3-documentation-browsersync

"docker run" 命令参数说明

上面的 docker 命令以这些选项启动 Docker 容器 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest

• --rm：Docker 完成后，容器将停止。
• -it：运行交互式 shell，以便您可以向 vite 代理服务器输入命令。
• --pull always：确保始终获取引用的 Docker 图像的最新版本。
• -v "./Documentation:/project/Documentation"：在 Docker 容器中（挂载）使目录 Documentation 可用，以便可以访问和监视 .rst 文件。
• -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp"：在 Docker 容器中（挂载）使输出目录 Documentation-GENERATED-temp 可用，以便可以在此处写入和监视 .html 文件。
• -p 5173:5173：这将使运行在 Docker 容器内端口 5173 上的代理 HTTP 服务器可供主机使用，这样您就可以使用主机的浏览器查看渲染的 HTML 输出。如果您想运行多个端口，可以选择除 5173 以外的任何数字作为此参数的 第一部分，例如 -p 8080:5173。
• ghcr.io/garvinhicking/typo3-documentation-browsersync:latest：这指定了正在运行的 Docker 容器。使用 :latest 标签是为了运行项目的最新发布版本。您也可以使用类似 :0.1 的特定版本，尽管这并不推荐。

如果您想了解 Docker 容器内包含的内容，请检查构建它的 Dockerfile。

https://github.com/garvinhicking/typo3-documentation-browsersync/blob/main/Dockerfile

一旦 Docker 启动并运行，它将监视 Documentation 目录中的任何更改，触发渲染并将创建的 HTML 代理到您的浏览器。

更改默认端口和目录

如果您想在不使用默认端口和不同目录的情况下运行，可以提供这些环境变量

• LOCAL_RENDER_PORT=5173
• LOCAL_RENDER_INPUT=Documentation
• LOCAL_RENDER_OUTPUT=Documentation-GENERATED-temp

因此，使用此命令完全运行 Docker，并通过 URL 直接打开浏览器窗口，看起来像这样

LOCAL_RENDER_PORT=5175 \
LOCAL_RENDER_INPUT=Documentation \
LOCAL_RENDER_OUTPUT=Documentation-GENERATED-temp; \
\
open "https://:${LOCAL_RENDER_PORT}/Documentation-GENERATED-temp/Index.html" && \
docker run --rm -it --pull always \
  -e LOCAL_RENDER_PORT=$LOCAL_RENDER_PORT \
  -e LOCAL_RENDER_INPUT=$LOCAL_RENDER_INPUT \
  -e LOCAL_RENDER_OUTPUT=$LOCAL_RENDER_OUTPUT \
  -v "$(pwd)/${LOCAL_RENDER_INPUT}:/project/Documentation" \
  -v "$(pwd)/${LOCAL_RENDER_OUTPUT}:/project/Documentation-GENERATED-temp" \
  -p "${LOCAL_RENDER_PORT}:5173" \
  ghcr.io/garvinhicking/typo3-documentation-browsersync:latest

查看此存储库中的 alias.sh 文件，您可以将这些行放入 Shell 的别名中，或者将其放入 /usr/local/bin/render-wysiwyg.sh 文件中并调用它。

环境变量之所以被调用两次，是因为 docker run 命令需要访问它们，然后它们还需要传播到 Docker 容器中。

注意：在主机侧对文件执行写入操作！

重要：渲染过程将 更改并覆盖 输出目录（Documentation-GENERATED-temp）中的文件。请确保只有在其中没有可能被覆盖的文件时才执行容器！

如果目录为空，则 Docker 容器启动时将启动首次渲染。

如果输入目录缺失，监视服务器将失败。

输入目录（Documentation）仅用于读取。

构建本地容器

通过 GitHub Actions，此项目通过多阶段构建过程在 ghcr.io 上创建 Docker 容器。

包含的 Dockerfile 执行以下操作

• 使用 TYPO3-Documentation/render-guides 基础 Docker 容器（:latest）
• 在顶部放置 NodeJS alpine 环境
• 配置 PHP（以便可以原生使用 render-guides 基础）
• 设置 NPM 和 vite
• 定义入口点

如果您检查此项目，您可以自己构建 Docker 容器

docker build . -t typo3-documentation-browsersync:local
## or: make docker-build

然后通过以下方式执行它

docker run --rm -it --pull always \
         -v "./Documentation:/project/Documentation" \
         -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
         -p 5173:5173 typo3-documentation-browsersync:local

## or enter: make docker-enter

注意

最初的想法是也提供一种本地执行渲染和代理的本地方式（无 Docker）。为此所必需的依赖链非常严格，并且 render-guides 项目不支持作为依赖项使用。

因此，目前这是“超出范围”。此存储库有一个基础的 composer.json 文件和本地运行的能力，但这只是一个占位符。

此项目中的唯一关键要素是

• package.json、package-lock.json：NPM 依赖项
• vite.config.js：实际的“代码”
• Dockerfile：构建 Docker 容器的说明
• .dockerignore：Docker 容器排除的文件
• .nvmrc：NVM 版本配置
• .github/workflows：GitHub 工作流程定义，用于自动向世界提供 Docker 容器

替代方案（PHPStorm）

PHPStorm 实际上提供了一个创建本地代理服务器的方法；当你选择一个渲染的HTML文件并右键点击 打开方式 > 浏览器 > 默认 时，它将在你的主机上打开一个浏览器窗口并显示HTML文件的内容，还具有热重载功能。因此，当你更改HTML文件中的任何内容时，PHPStorm代理服务器也会直接重新加载你的输出。然而，当编辑此类文件时，它不会自动渲染ReST文件。

如果你的操作系统支持 inotifywait（在Linux上），你可以使用这个

inotifywait -e close_write,moved_to,create -m . |
while read -r directory events filename; do
  docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
done

来自动“监视” Documentation 文件夹内ReST文件的任何更改，然后重新渲染HTML，这会自动重新加载你的浏览器窗口。

遗憾的是，inotifywait 在 macOS 上不可用，构建自定义的 PHP pecl inotify 软件包的替代方案超出了我的个人能力范围，同样使用其他工具如 fswatch 也不行。

我想为任何人都提供一个轻松预览更改的方法，所以我希望不要求使用PHPStorm或特定的inotify启用操作系统。

相反，NodeJS 生态系统提供了一个 browsersync 软件包，它可以完成所有需要的监视和代理。我将它与 vite 结合使用，因为像 gulp 或 grunt 这样的替代方案已经过时，并且在它们的依赖项上报告了许多安全问题。