docs: overhaul the documentation site and how it is published

[BobDu]

Refs #206.

⚠️ Needs a repository setting change before this is merged

Settings → Pages → Build and deployment → Source has to be switched from the gh-pages branch to GitHub Actions. While the source is still a branch, a deployment originating from main is rejected, so merging first would just produce one red run. The site keeps serving its current content until the first Actions deployment lands.

Once it has deployed successfully, the gh-pages branch and the GH_TOKEN repository secret can both be deleted.

Publishing

The site was built in CI and pushed to gh-pages with peaceiris/actions-gh-pages, authenticated by a token kept in the GH_TOKEN repository secret. GitHub's own actions upload the build as an artifact and deploy it through an OIDC-verified deployment instead, so nothing has to be stored and no build output is committed to a branch. This is what maven-hpi-plugin, wxwork-notification-plugin, jelly and job-dsl-plugin already do.

Along with it: npm ci rather than npm install so the tracked lock file is what gets installed; the trigger narrowed to the paths that can change the built site, instead of rebuilding and redeploying on every push to main including the Java-only ones; and the build skipped on forks, which have no Pages site to deploy to.

bin/docs-release.sh is removed. It was the manual half of the same scheme and has not worked since the VitePress migration moved the output out of docs-dist/ in September 2022 — AGENTS.md already told contributors not to run local release scripts.

I smoke-tested the whole pipeline on my fork before opening this: build → artifact → OIDC deployment, green, serving.

What was broken

[受限的 markdonw](#受限的 markdonw) never rendered as a link — the anchor contains a space, so markdown-it left it as literal text. The pipeline page has been showing that raw markdown in two of its tables. The target section is on another page and the word is misspelt as well.

#MsgTypeEnum, #BtnLayoutEnum, #ButtonModel	never resolved; heading ids are lowercased
two ding-doc.oss-cn-beijing.aliyuncs.com screenshots	403 AccessDenied: Access denied by bucket policy
plugins.jenkins.io/dingtalk	404 — the plugin is published as dingding-notifications, which the home page badge already had right
liuweigl.github.io/dingtalk-plugin in an action card example	404
two dingtalk.com/qidian/help-detail-* references on the DTMD page	redirect to the help centre's front page

The five external screenshots in 效果展示 are replaced with the ones this repository already ships, so the section no longer depends on someone else's bucket. The DTMD example had the robot send an insult — the code says something civil now, though the screenshot still shows the old exchange and should be retaken by someone with a client handy; I only renamed the file to fix its dtmt spelling and left the pixels alone.

What disagreed with the code

The pipeline page's syntax block was missing singleUrl, documented at as a List when it is a Set, gave the default title as Jenkins 通知 when it is Jenkins 构建通知, and its copy of BtnLayoutEnum misspelt horizontal.

环境变量 listed two of the eight variables the plugin injects, and none of the things that make them surprising:

• PROJECT_* is the project, JOB_* is the build
• EXECUTOR_NAME and EXECUTOR_MOBILE are read before they are written, so a build can override them
• none of the eight exist in the dingtalk step — they are written into the notification's own snapshot of the environment. That is the behaviour behind Pipeline 中无法使用插件环境变量 #206, answered in that thread back in 2023 but never written down. Freestyle 项目高级功能 implied the opposite.

The security policy section warned that the keyword has to appear in the message, when DingTalkSender.addKeyWord appends it for you on all four message types.

What was missing

The raw mode had no documentation at all, so 自定义消息 is a new page: what the built-in message contains, what disabling it costs (no buttons, MARKDOWN only and therefore no tappable mention on mobile), that the title stays out of your hands, and how to rebuild the pieces with environment variables. 快速开始 gained the six notice occasions and the boundary of the three security policies — only two of them need anything on the Jenkins side.

The site itself

It declared lang="en-US" while being entirely in Chinese, had no search, and set lastUpdatedText without enabling lastUpdated — enabling it is why the checkout now needs the full history. The theme's remaining English labels are translated, the logo that was sitting unreferenced in assets/ is now the home page's, and the home page uses the hero layout. Public files move to docs/public, VitePress's default, which lets the explicit vite.publicDir go.

CONTRIBUTING.md told contributors to install yarn although the repository tracks package-lock.json and CI runs npm ci, and pointed at two jenkins-zh.cn articles whose domain no longer resolves and at the retired Confluence wiki.

Verification

npm run docs:build after each round, plus a scan of the built output for anchors without a matching id, markdown link syntax surviving outside <code>, and local image targets that do not exist — 16 pages, none left. Every external link in the docs checked individually; the only remaining non-200s are the name.com placeholders inside a syntax example.

The three binary changes in this PR are renames at 100% similarity; no image content is modified.