Druxt docs

druxtjs.org

Nuxt 前端和 Drupal 后端，由 Druxt 构建。

此仓库是 druxtjs.org 的源代码，该网站是 Druxt 的文档站点。它也是一个可运行的 Druxt 站点示例：页面内容来自 Drupal，并由 Nuxt 渲染。

该站点在一个仓库中包含两个应用。nuxt/ 是前端。它通过 DruxtEntity 及其封装组件，使用 Druxt 渲染文档。drupal/ 是供编辑人员使用的 Drupal 11 后端。

参与开发

在你的计算机上同时运行整个站点，包括前端和后端。可选择以下三种方式之一。

方式	你需要
开发容器	VS Code 和 Dev Containers、GitHub Codespaces 或 DevPod
mise	mise 和三个 PHP 扩展
手动操作	PHP 8.3 或更高版本、Composer 和 Node 16.20.1

开发容器

工具	操作
VS Code	克隆仓库并打开，然后选择 Reopen in Container
GitHub Codespaces	在仓库页面打开 Code 并选择 Codespaces
DevPod	点击徽章，或运行 devpod up https://github.com/druxt/druxtjs.org

容器中包含 Node 16.20.1、PHP 8.4、Composer 和 mise。创建容器时会运行 npm install 和 npm run setup，因此容器打开时 Drupal 已在运行。然后运行 npm run dev。

mise

.mise.toml 固定了 Node 16.20.1 和 PHP 8.4 版本。PHP 需要 gd、pdo_sqlite 和 sodium 扩展。

mise install
npm install
npm run setup
npm run dev

手动操作

安装 PHP 8.3 或更高版本（含 gd、pdo_sqlite 和 sodium 扩展）、 Composer 和 Node 16.20.1。然后运行：

npm install
npm run setup
npm run dev

你将获得什么

命令	功能
npm install	安装根目录工具并启用 Git 钩子
npm run setup	在临时 SQLite 数据库上安装 Drupal，获取固定版本的 druxt.js 以用于 API 页面，然后启动 Drupal
npm run dev	启动连接到该 Drupal 的 Nuxt 开发服务器。首次运行时会安装前端所需的软件包
npm run login	输出一个一次性 Drupal 登录链接

服务	地址
Drupal	http://127.0.0.1:8888，或下一个可用端口。运行 npm run info 可查看端口
Nuxt	http://localhost:3000

npm run setup 会将 Drupal 的地址写入 .env，而 npm run dev 会从该文件读取地址。 设置过程需要网络连接，以便获取 Composer 软件包和 GitHub 上固定版本的文档。

编写文档

1. 运行 npm run login，并打开它显示的链接。
2. 在 Drupal 中，转到 内容 并编辑一个页面，或添加页面。布局 段落编辑器通过组合文本、代码和图像片段来构建页面。
3. 保存，然后在 http://localhost:3000 上重新加载页面。

编辑表单上的预览会显示未保存的更改。 docs/backend.md 介绍了其中的选项卡。

在此处所做的编辑仅保存在本机数据库中：它用于预览和测试网站， 并非发布页面文本的方式。请参阅更改的去向，了解不同内容应放在哪里。

编辑者也可以在 http://localhost:3000 上登录，并通过页面专属的 URL 查看该页面的最新草稿。 docs/backend.md 介绍了相关 工作流和登录方式。

Modules、API reference 和 Components 页面来自 druxt.js 软件包。npm run docs:generate 会在本地的固定版本 druxt.js 检出目录中构建这些页面。该命令会先安装并构建 druxt.js，因此首次运行较慢。

更改的去向

更改	去向
内容模型、编辑器或网站设置	在 drupal/ 中使用 vendor/bin/drush config:export 导出，并在拉取请求中提交 drupal/config/sync/
前端	在拉取请求中提交 nuxt/ 中的更改
页面文本	Drupal，编辑者在此更改页面文本。数据库是事实来源，页面文本目前尚不能通过拉取请求提交

网站的内容存储在生产环境的数据库中。本地 Drupal 初始没有页面， 在其中进行的编辑也只保留在本地。

前端中的 Druxt

nuxt/ 是一个使用 Druxt 构建的 Nuxt 2 应用，其编写目的是作为 Druxt 站点的示例供人阅读。

内容	方式
页面	每个章节页面都使用 Druxt 路由器解析路径，然后通过 <DruxtEntity mode="full"> 渲染 Drupal 页面。
封装组件	nuxt/components/druxt/ 存放 Druxt 按名称查找的封装组件。页面组件是 entity/node/DocPageFull.vue，entity/paragraph/ 中则为每种段落类型各设一个组件。其余组件包括字段（field/）、布局区段（layout-paragraph/）、区块（block/）、区块区域（block-region/）和菜单（menu/）。
显示设置	应用构建时，druxt-schema 会读取 Drupal 的视图和表单显示配置，因此前端会遵循编辑者在 Drupal 中更改的显示设置。
布局	druxt-layout-paragraphs 会渲染页面的布局区段。
页眉、侧边栏和页脚	druxt-blocks 会渲染放置在 Drupal 中 druxtjs 主题区域内的区块。主题以及站点名称和徽标来自 druxtjs_org 消费者的解耦设置，由 nuxt/modules/decoupled-settings 在构建时读取。
UI	nuxt/components/dui/ 存放不依赖 Drupal 的展示组件：代码块、图表、富文本和分栏。它们将移至共享的 Druxt UI 库。
体验区	nuxt/components/global/DruxtExample.vue 会在所选后端的独立运行时中渲染任意 Druxt 组件（nuxt/utils/druxt-runtime.js），并使用 nuxt/utils/live-examples.js 中关于各组件的信息。同一张卡片也显示在模块和组件参考页面上。

若要更改某项内容的外观，请找到 Druxt 查找的封装组件名称（可在 Vue devtools 中查看），然后在 nuxt/components/druxt/ 下对应的路径中添加组件。组件解析 介绍了命名规则。

部署

该站点在 Lagoon 上运行，Drupal 和 Nuxt 共处一个环境。Nuxt 会优先提供预渲染页面，并实时渲染尚未存储或存储时间已超过存活时间的页面。docs/hosting.md 介绍了部署时的操作。

命令

命令	作用
npm run setup	安装后端，然后启动
npm run dev	连接后端运行 Nuxt 开发服务器
npm run storybook	连接后端在端口 3030 上运行 Storybook
npm run start / stop	启动或停止 Drupal
npm run info	查看 Drupal 的位置及其运行的版本
npm run login	获取 Drupal 的一次性登录链接
npm run docs:generate	构建 Modules、API 参考和 Components 页面
npm run lint	运行所有检查工具（不包括文案检查）
npm run lint:prose	运行 Vale，需先执行一次 npm run lint:prose:install
npm test	运行脚本和前端模块的 Node 测试

贡献

有关提交消息、检查以及文件中绝不能包含的内容，请参阅 CONTRIBUTING.md。 请在 druxt/druxtjs.org 上提交问题和拉取请求。 docs/backend.md 介绍了页面历史记录和预览。

许可证

MIT