docs: overhaul the documentation site and how it is published

.github/workflows/doc.yml

@@ -4,23 +4,59 @@ on:
   push:
     branches:
       - main
+    paths:
+      - docs/**
+      - package.json
+      - package-lock.json
+      - .github/workflows/doc.yml
+  workflow_dispatch:
+
+# Grant GITHUB_TOKEN the permissions required to make a Pages deployment.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and
+# the latest queued one. In-progress runs are not cancelled, so a deployment always completes.
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  deploy:
+  build:
+    # A fork has no Pages site to deploy to.
+    if: github.repository_owner == 'jenkinsci'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+        with:
+          # the lastUpdated option reads each page's git history
+          fetch-depth: 0
       - uses: actions/setup-node@v7
         with:
           node-version: 22
           cache: npm
-      - run: npm install 
+      - run: npm ci
 
       - name: Build
         run: npm run docs:build
 
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
         with:
-          github_token: ${{ secrets.GH_TOKEN }}
-          publish_dir: docs/.vitepress/dist
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v5

AGENTS.md

@@ -4,7 +4,6 @@
 - `src/main/java` and `src/main/resources` contain the Jenkins plugin source and resources.
 - `src/test/java` holds JUnit 5 tests.
 - `docs/` contains the VitePress documentation site.
-- `bin/` includes helper scripts such as `docs-release.sh`.
 
 ## Key Classes
 - `io.jenkins.plugins.DingTalkRunListener`: listens to build lifecycle events and triggers notifications.
@@ -23,10 +22,10 @@
 ## Build, Test, and Development Commands
 - `mvn hpi:run` runs the plugin in a local Jenkins for development (use the Maven tool window in IntelliJ as noted in `CONTRIBUTING.md`).
 - `mvn test` runs the JUnit 5 test suite.
-- `yarn` installs documentation dependencies for the `docs/` site.
-- `yarn docs:dev` starts the VitePress docs dev server.
-- `yarn docs:build` builds the static docs site.
-- `yarn docs:serve` serves the built docs locally on port 5173.
+- `npm ci` installs documentation dependencies for the `docs/` site.
+- `npm run docs:dev` starts the VitePress docs dev server.
+- `npm run docs:build` builds the static docs site.
+- `npm run docs:serve` serves the built docs locally on port 5173.
 
 ## Coding Style & Naming Conventions
 - Java code follows Google Java Style; use your IDE formatter with the Google style XML.
@@ -68,8 +67,8 @@
 - Documentation releases are triggered via GitHub Actions; do not run local release scripts.
 
 ## Docs Flow
-- Edit content under `docs/` and preview with `yarn docs:dev`.
-- Build the static site with `yarn docs:build` and verify locally using `yarn docs:serve`.
+- Edit content under `docs/` and preview with `npm run docs:dev`.
+- Build the static site with `npm run docs:build` and verify locally using `npm run docs:serve`.
 - Use the GitHub Actions workflow to publish docs when changes are ready.
 
 ## Lessons Learned (Jelly & Jenkins UI)

CONTRIBUTING.md

@@ -4,8 +4,20 @@
 
 ## 开发服务
 
-在 `IDEA` 右侧 `maven` 控制面板中添加 `hpi:run` 到启动配置：
-![启动配置](./docs/assets/contribuiting-config.png) 
+命令行启动一个带本插件的本地 Jenkins：
+
+```shell
+mvn hpi:run
+```
+
+跑测试：
+
+```shell
+mvn verify
+```
+
+`IDEA` 下也可以在右侧 `maven` 控制面板中把 `hpi:run` 添加到启动配置：
+![启动配置](./docs/assets/contribuiting-config.png)
 
 ## 开发约定
 
@@ -15,15 +27,18 @@
 
 ## 参考文档
 
-1. [Plugin tutorial](https://wiki.jenkins.io/display/JENKINS/Plugin+tutorial#Plugintutorial-SettingUpEnvironment)
-2. [Jenkins 插件开发之旅：两天内从 idea 到发布(上篇)](https://jenkins-zh.cn/wechat/articles/2019/05/2019-05-06-jenkins-plugin-develop-within-two-days-part01/)
-3. [Jenkins 插件开发之旅：两天内从 idea 到发布(下篇)](https://jenkins-zh.github.io/wechat/articles/2019/05/2019-05-08-jenkins-plugin-develop-within-two-days-part02/)
+1. [Jenkins 插件开发教程](https://www.jenkins.io/doc/developer/tutorial/)
+2. [Jenkins 插件开发文档](https://www.jenkins.io/doc/developer/plugin-development/)
 
 ---
 
 ## 文档服务
 
-1. 安装 node.js 环境
-2. 安装 yarn 包管理器
-3. 在项目根目录执行 `yarn` 安装依赖
-4. 执行 `yarn docs:dev` 启动文档开发环境
+文档站用 [VitePress](https://vitepress.dev/) 构建，源文件在 `docs/` 下。
+
+1. 安装 Node.js
+2. 在项目根目录执行 `npm ci` 安装依赖
+3. 执行 `npm run docs:dev` 启动文档开发环境
+4. `npm run docs:build` 构建静态站点，`npm run docs:serve` 预览构建结果
+
+推送到 `main` 后由 GitHub Actions 自动发布，不需要手动执行发布脚本。

docs/.vitepress/config.js

@@ -1,30 +1,65 @@
-import path from 'path'
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
   base: '/dingtalk-plugin/',
+  lang: 'zh-CN',
   title: '钉钉机器人插件',
   description: '在 Jenkins 中使用钉钉机器人发送消息',
-  head: [['link', { rel: 'icon', href: '/dingtalk-plugin/favicion.ico' }]],
+  head: [['link', { rel: 'icon', href: '/dingtalk-plugin/favicon.ico' }]],
+  lastUpdated: true,
+  sitemap: {
+    hostname: 'https://jenkinsci.github.io/dingtalk-plugin/'
+  },
   vue: {
     template: {
       compilerOptions: {
         isCustomElement: tag => ['font'].includes(tag)
       }
     }
   },
-  vite: {
-    build: {
-      emptyOutDir: true
-    },
-    publicDir: path.resolve(__dirname, 'public')
-  },
   themeConfig: {
-    lastUpdatedText: 'Updated Date',
+    logo: '/dingtalk-logo.png',
+    outline: [2, 3],
+    outlineTitle: '本页目录',
+    lastUpdatedText: '最后更新',
+    returnToTopLabel: '回到顶部',
+    sidebarMenuLabel: '目录',
+    darkModeSwitchLabel: '外观',
+    docFooter: {
+      prev: '上一页',
+      next: '下一页'
+    },
+    search: {
+      provider: 'local',
+      options: {
+        translations: {
+          button: {
+            buttonText: '搜索文档',
+            buttonAriaLabel: '搜索文档'
+          },
+          modal: {
+            noResultsText: '无法找到相关结果',
+            resetButtonTitle: '清除查询条件',
+            displayDetails: '显示详细列表',
+            footer: {
+              selectText: '选择',
+              navigateText: '切换',
+              closeText: '关闭'
+            }
+          }
+        }
+      }
+    },
+    socialLinks: [
+      {
+        icon: 'github',
+        link: 'https://github.com/jenkinsci/dingtalk-plugin'
+      }
+    ],
     editLink: {
       pattern:
         'https://github.com/jenkinsci/dingtalk-plugin/edit/main/docs/:path',
-      text: 'Edit this page on GitHub'
+      text: '在 GitHub 上编辑此页'
     },
     nav: [
       {
@@ -61,6 +96,10 @@ export default defineConfig({
             text: '用户属性扩展',
             link: '/advance/user-property'
           },
+          {
+            text: '自定义消息',
+            link: '/advance/custom-message'
+          },
           {
             text: '@ 人',
             link: '/advance/at-mention'

docs/advance/custom-message.md

@@ -0,0 +1,73 @@
+# 自定义消息
+
+项目级配置里有两个都能写内容的输入框，区别是**在内置消息之上追加**还是**把内置消息整个换掉**：
+
+| 配置项      | 是否勾选 `禁用内置消息` | 效果                            |
+|----------|----------------|-------------------------------|
+| `自定义内容`  | 不勾选            | 内置消息照发，你写的内容追加在最后            |
+| `自定义消息`  | 勾选             | 内置消息完全不发，只发你写的内容              |
+
+两个框都在项目配置的 `钉钉配置` 里，勾选机器人后点 `advanced` 展开。
+
+## 内置消息长什么样
+
+不勾 `禁用内置消息` 时，插件发的是这样一条 `ACTION_CARD`：
+
+```markdown
+# [项目名](项目地址)
+---
+- 任务：[#42](本次构建地址)
+- 状态：成功
+- 持续时间：1 min 20 sec
+- 执行人：张三
+
+这里是你在「自定义内容」里写的东西
+```
+
+外加『更改记录』『控制台』两个按钮。
+
+## 禁用内置消息之后
+
+勾上 `禁用内置消息`，上面那些就全没了，只剩你在 `自定义消息` 里写的内容。想保留项目名、状态之类的信息，
+自己用[环境变量](../guide/environment-variables.md)拼：
+
+```markdown
+# ${PROJECT_NAME} ${JOB_STATUS}
+
+- 构建：[${JOB_NAME}](${JOB_URL})
+- 耗时：${JOB_DURATION}
+- 触发人：${EXECUTOR_NAME}
+
+> 分支 ${GIT_BRANCH}，提交 ${GIT_COMMIT}
+```
+
+有几件事跟着一起变了，配之前先知道：
+
+- **按钮没有了。**『更改记录』『控制台』两个默认按钮只属于内置消息，自定义消息发的是 `MARKDOWN`
+  类型，这个类型不支持按钮。想留住这两个入口就在正文里写成链接：
+  `[更改记录](${JOB_URL}changes)`、`[控制台](${JOB_URL}console)`。
+- **消息类型固定是 `MARKDOWN`**，目前不能选。所以 `@` 在手机端不可点击，详见 [@ 人](./at-mention.md)。
+- **标题不受这里控制。** 钉钉在会话列表里透出的那行字始终是 `项目名 + 状态`，例如 `my-job 成功`
+  （用关键词安全策略的话后面还会自动拼上关键词），改不了。正文里的 `# 一级标题` 是消息内部的标题，
+  两回事。
+- **`通知人` 依然生效。** 里面配的 `@` 会追加到消息末尾，除非正文里已经写过同样的 `@`。
+
+## 关于换行
+
+`自定义消息` 和 `自定义内容` 都是多行文本框，直接按回车换行就行。
+
+::: tip
+
+钉钉的 markdown 只支持一个子集，能用哪些语法见 [Markdown 语法](./markdown.md)。
+
+:::
+
+## 只想给某几种结果换内容
+
+`自定义消息` 是整个机器人配置共用的，不区分构建结果。想让成功和失败发不一样的东西，两个办法：
+
+- 同一个机器人在正文里用 `${JOB_STATUS}` 把状态带出来，内容本身保持通用
+- 在系统设置里配两个机器人（webhook 可以填同一个群），项目里就会出现两条独立配置，
+  各自勾不同的 `通知时机`、写不同的 `自定义消息`
+
+需要完全自由的控制流就别用项目级配置了，改用 [pipeline 的 `dingtalk` 步骤](../guide/pipeline.md)。

docs/advance/markdown.md

@@ -1,5 +1,7 @@
 # Markdown
-官方文档 https://open.dingtalk.com/document/orgapp/enterprise-internal-robots-send-markdown-messages#title-w87-omz-3es
+
+钉钉官方文档：[企业内部机器人发送 markdown 消息](https://open.dingtalk.com/document/orgapp/enterprise-internal-robots-send-markdown-messages#title-w87-omz-3es)
+
 ## 钉钉支持的语法
 
 目前只支持 md 语法的子集，具体支持的元素如下：

docs/advance/user-property.md

@@ -31,4 +31,9 @@
 
 ![user-detail](../assets/user-detail.jpg)
 
-:::
+:::
+
+## 拿不到真实用户的场景
+
+定时构建、webhook 触发这类没有登录用户的构建，这里配的属性用不上。可以改用
+`EXECUTOR_NAME` / `EXECUTOR_MOBILE` 环境变量直接指定，见[环境变量](../guide/environment-variables.md)。

docs/examples/action-card.md

@@ -41,7 +41,7 @@ pipeline {
 
 ```groovy
 singleTitle: '查看更多',
-singleUrl: 'https://liuweigl.github.io/dingtalk-plugin/'
+singleUrl: 'https://jenkinsci.github.io/dingtalk-plugin/'
 ```
 
 :::details 查看结果
@@ -84,7 +84,7 @@ singleUrl: 'https://liuweigl.github.io/dingtalk-plugin/'
 
 :::details 查看结果
 
-![action-card-at-all-example](../assets/action-card-btn-layout-example.jpg)
+![action-card-btn-layout-example](../assets/action-card-btn-layout-example.jpg)
 
 :::