要想制作一个有用的Confluence页面,需要几个前提:
  1. 准备有用的内容,有吸引力的内容。从读者的角度考虑,页面中应该有哪些内容,如何布局等等。
  2. 转换思维。Confluence页面不同于Word或PDF文档,不能像离线文档那样放入几十页内容,而应该将内容拆分到不同的页面,并为不同类型的读者提供自然的页面跳转链接,将内容串联起来。
  3. 掌握Confluence编辑器技能。包括设计页面布局、使用表格、添加链接、引入多媒体内容等,最重要的技能,也是本文的重点,掌握几十种内置宏(Macro)的用法
下表列出了Confluence中最常用的一些宏,例如状态宏、标签宏、目录宏、摘要宏、Jira宏等等。也可以通过视频课程学习它们的使用场景和用法( Confluence内容管理培训Confluence文档和知识库管理培训)。
Confluence中最常用的宏(Macro)
宏(Macro)常用理由要点参考文档推荐指数
状态宏(Status Macro)让内容可视化,醒目、高亮。瞬间提升内容档次
  • 通常结合表格使用,放在某个单元格中
状态宏文档✭✭✭✭✭
展开宏(Expand Macro)使页面信息简洁
  • 默认折叠信息,需要用户点击再显示详细内容
展开宏文档✭✭✭✭✭
代码块宏(Code Block Macro)用代码块宏展示代码才够专业
  • 可以展示代码、命令,甚至日志内容
  • 您还可以在系统管理界面中,添加自定义的代码类型(高亮类型)
代码块宏文档✭✭✭✭✭

面板宏(Panel Macro)

列宏(Column Macro)

段宏(Section Macro)

页面布局三件套
  • 设置灵活的页面布局
  • 也可以在表格单元格中使用
  • 突出视觉重点

面板宏文档

列宏文档

段宏文档

✭✭✭✭✭
目录宏(Table of Contents)让读者快速跳转到感兴趣的内容
  • 使内容更整洁
  • 内容较多时使用
  • 最好使用平铺目录,这是不同于离线文档的地方
目录宏文档✭✭✭✭✩
摘要宏(Excerpt Macro) 和 包含摘要宏(Excerpt Include Macro)在一个页面中引用另一个页面或另一些页面的摘要。
  • 避免复制内容,保持内容源头一致性
  • 制作引导用户的信息聚合页面
  • 需要两个宏结合使用,先设置摘要宏,再配置包含摘要宏
摘要宏文档包含摘要宏文档✭✭✭✭✩
Jira图表宏(Jira Chart Macro)和 Jira Issues宏(Jira Issues Macro)Jira和Confluence结合使用的必备技能
  • Jira和Confluence是天生的一对,使用时需要整体考虑呈现效果
  • 不常用Jira的用户也需要看到Jira中的数据

Jira图表宏文档

Jira Issues宏文档

✭✭✭✭✩
页面属性宏(Page Properties Macro)和 页面属性报告宏(Page Properties Report Macro)制作同类页面的索引页,汇总每个页面的属性信息
  • 每类页面都有特定的属性,例如,需求类页面有负责人、实现状态等属性。
  • 将同类页面的属性信息汇总到一个页面上,能帮助阅读者,可以快速找到想要的内容,或者对比不同页面的属性信息

页面属性宏文档和页面属性报告宏

✭✭✭✭✩
锚点宏(Anchor Macro)让读者快捷跳转到页面的指定位置
  • 页面较长时要考虑设置锚点
锚点宏文档✭✭✭✩✩
团队日历宏(Team Calendar Macro)在日历上列出重要事件,还能集成Jira上的事件
  • 项目组或开发团队使用Confluence时,必须有按日期总览事件的视角
  • 可以添加Jira中的事件
  • 也可以添加自定义的事件
团队日历宏文档✭✭✭✩✩
信息宏、提示宏、注意宏、警告宏(Info, Tip, Note, and Warning Macros)让信息类别更直观
  • 记住,在Confluence中不要写文档,而是要制作网页
  • 作者,也就是输出信息的人,有必要在大量信息中划出重点,以便读者理解或引起重视
信息宏、提示宏、注意宏、警告宏文档✭✭✭✩✩
搜索宏(Livesearch Macro)Confluence不是文档服务器,它是一个网站。用好搜索宏才能更理解这句话
  • 为空间设置一个搜索引擎
  • 为某类标签的内容设置一个搜索引擎
搜索宏文档✭✭✭✩✩
图表宏(Chart Macro)图表胜过千言万语
  • 太有用了,但是需要投入精力学习才能用好
  • 图表不只是展示统计结果,更是为了帮助阅读者发现问题或解决问题。因此要根据阅读者的需求,精心设计整个页面,包括如何布局、展示哪些内容、以什么形式呈现等等
图表宏文档✭✭✭✩✩
画图宏文档里需要配上各种图形说明,包括:流程图、时序图、设计图、拓扑图、ER图、组织图、UML图、数据图表、whiteboard......
  • Confluence中没有内置画图功能,需要安装插件。画图插件主要分为2类:直接绘图类和文本生成类
  • 直接绘图类,直接在画布上绘制,类似windows中的画图或visio工具。这类插件无需培训,没有使用门槛,对非IT人士更易上手。
  • 文本生成类,通过文本代码生成图像,例如:PlantUML、Mermaid、Kroki等。这类插件需要用户掌握一点语法技能,更适用于IT人士。它们的优点是能进行版本管理,也更容易与AI结合进行智能绘图。
  • 可以参考这篇文章:Confluence画图插件

直接绘图类:

xdraw

excalidraw

tldraw

文本生成类:

Mermaid

PlantUML

Kroki

✭✭✭✭✩

(未完待续......)
个人资料图片宏
页面信息宏
用户信息宏
博客宏
标签内容宏
标签宏

......

(本文将持续更新,欢迎点赞、评论、收藏、转发、打赏,谢谢支持!)

友情链接:
Logo

DEVPOD社区,旨在打造高质量的DevOps工具知识库。包括商业工具:Atlassian Jira,Confluence,Jfrog,极狐, CodeBeamer等。开源工具栈如:Gitlab,ArgoCD, Jenkins等。 致力于帮助企业建实现云原生时代DevOps转型。

更多推荐