如何在Confluence页面代码块中添加链接与宏以遍历代码并描述字段？

我之前在Confluence里折腾过类似的需求，给你分享几个实用的实现思路：

适合只需要处理单个页面、代码量不大的场景，不需要额外权限：

• 放弃原生的纯代码块宏，把代码拆成内嵌代码片段（用`包裹），给需要描述的字段加页面锚点链接：

  `POST /api/users`
  `Content-Type: application/json`
  `{`
    `  "[username]": "your-name",` // 查看[字段说明](#username-desc)
    `  "[email]": "your-email@example.com"` // 查看[字段说明](#email-desc)
  `}`
  

• 在页面下方对应位置添加锚点和详细描述：
  {anchor: username-desc}
  username：用户的唯一登录标识，支持英文字母、数字和下划线，长度限制为6-20位。
  {anchor: email-desc}
  email：用户的有效邮箱地址，用于接收账户验证、密码重置等系统通知。

如果需要频繁处理这类带字段描述的代码块，推荐创建自定义用户宏，能自动解析标记并生成联动内容（需要Confluence Server/Data Center版的管理员权限）：

1. 进入Confluence管理后台的「用户宏」页面，新建一个宏：
   • 宏标题设为「带字段描述的代码块」
   • 勾选「宏包含内容」，内容处理选「将Wiki标记转换为HTML」
2. 用Velocity语言编写宏模板，示例如下：

   ## Macro title: 带字段描述的代码块
   ## Macro has a body: Y
   ## Body processing: Convert wiki markup to HTML
   ## Output: HTML
   ## Parameters:
   ##   - descriptions: 字段描述，格式为「字段名:描述内容;字段名2:描述内容2」
   
   #set ($codeText = $body.replaceAll("\\r\\n", "<br>").replaceAll("\\n", "<br>"))
   #set ($descMap = {})
   #if ($param_descriptions)
     #foreach ($item in $param_descriptions.split(";"))
       #set ($kv = $item.split(":", 2))
       #if ($kv.size() == 2)
         #set ($void = $descMap.put($kv[0].trim(), $kv[1].trim()))
       #end
     #end
   #end
   
   <div style="margin-bottom: 16px;">
     <pre style="background: #f4f5f7; padding: 12px; border-radius: 4px;">
       <code>$codeText.replaceAll("\\[(\\w+)\\]", '<span style="color: #0052cc;"><a href="#field-$1" style="color: #0052cc; text-decoration: underline;">$1</a></span>')</code>
     </pre>
   </div>
   
   #if (!$descMap.isEmpty())
     <h3 style="margin-top: 24px;">字段详细说明</h3>
     <ul style="list-style-type: disc; padding-left: 20px;">
       #foreach ($field in $descMap.keySet())
         <li id="field-$field"><strong>$field:</strong> $descMap.get($field)</li>
       #end
     </ul>
   #end
   

3. 使用宏时，在内容区域写带[字段名]标记的代码，在「descriptions」参数里填写字段对应关系（比如username:用户登录标识，6-20位字母数字下划线;email:用户有效邮箱），就能自动生成带可点击链接的代码块和描述列表。

如果是Confluence Cloud版没有权限创建用户宏，可以在官方应用市场找代码块增强类插件，这类插件通常自带字段标记、内嵌链接、描述联动的功能，直接在插件编辑器里给字段添加注释或关联描述即可。

注意事项 #

• 原生Confluence代码块宏是纯文本渲染，不支持内嵌HTML和链接，必须用上述变通方法；
• 用户宏需要管理员权限才能创建和维护；
• 锚点链接名称要避免特殊字符，确保跳转正常。

内容的提问来源于stack exchange，提问作者Zitin