- Created by zhongluqiang, last modified on Jul 18, 2024
这里记录配置Confluence的过程。通过右上角的按钮进入Confluence的站点管理页面,后继除了空间独有的设置项外,其他大部分的通用选项都从这里进行配置。
配置站点标题和基本URL
这里注意一点,站点的基本URL对登录影响很大,如果不从基本URL进行登录,那么Confluence会提示基本URL不匹配并要求更新基本URL。比如,虽然从https://midlane.top/confluence/和https://www.midlane.top/confluence/都可以访问到本网站,但这俩对应不同的基本URL。实际需要根据情况配置基本URL,再从基本URL进行登录。基本URL不影响访客用户,访客只需要IP地址解析正确,可以从任何URL访问Confluence页面。
配置时间格式
Confluence默认的时间格式是12小时制,这里改成24小时制,修改“格式和国际化设置->时间格式”,将默认的H:mm a 改成HH:mm即可。
配置全局样式表
这里修改的是全局的页面样式,主要调整默认的字体和大小,以及优化等宽字体、也就是行内代码的显示风格,格式参考思源笔记,修改“外观->样式表”,在全局样式表中增加以下内容:
/* 调整字体和大小,优化中文显示效果 */ .wiki-content { font-family: "Helvetica Neue", "Luxi Sans", "DejaVu Sans", "Hiragino Sans GB", "Microsoft Yahei", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; font-variant-ligatures: no-common-ligatures !important; font-size: 16px; text-rendering: optimizeLegibility !important; } /* 优化等宽字体,也就是行内代码的显示效果 */ code { padding: 1px 5px 1px 5px; font-family: Consolas, Menlo, Monaco, Lucida Console, Liberation Mono, DejaVu Sans Mono, Bitstream Vera Sans Mono, Courier New, monospace, serif; background-color: #eeeeee; }
除了全局样式表,Confluence中的每个空间也可以单独设置样式,方法是在“空间管理->外观->样式表”中进行修改,修改方法类似。
禁用右侧目录随页面滚动
Confluence可以通过分栏,并在右侧插入目录宏的方式实现右侧目录显示功能,但坑爹的是这个目录是随页面滚动的,而我们在浏览时一般都需要目录固定以便随时跳转,这里通过全局样式表实现目录固定功能,参考上一节,在全局样式表中新增以下内容:
/* 固定右侧目录,使之不随页面滚动 */ div.cell.aside>.innerCell>.toc-macro { position:fixed; top:100px; height: 75%; overflow-y:scroll !important; overscroll-behavior: contain !important; } /* 不显示目录的滚动条 */ /* Hide scrollbar for Chrome, Safari and Opera */ #main-content > div > div > div.cell.aside > .innerCell > .toc-macro::-webkit-scrollbar { display:none; } /* Hide scrollbar for IE, Edge and Firefox */ #main-content > div > div > div.cell.aside > .innerCell > .toc-macro { -ms-overflow-style: none; /* IE and Edge */ scrollbar-width: none; /* Firefox */ }
配置侧边栏显示页面树
先通过“空间管理->配置侧边栏”删除原有的页面显示功能,再进入空间管理,选择“外观→侧边栏,页眉和页脚”,设置侧边栏为{pagetree:startDepth=3|searchBox=true}
,效果如下:
禁用保护管理员事务
Confluence默认对管理员相关的功能启用了管理员事务保护,也就是管理员即使已经登录了,在操作管理员相关功能时,也需要再次登录一次,如果要禁用的话,在“用户&安全→安全配置”中,去掉默认勾选的保护管理员事务即可。
修改synchrony最大堆内存
synchrony是Confluence用协同编辑的功能,默认堆内存为2G,这里可以修改成1G,或是禁用掉。
参考:
https://confluence.atlassian.com/doc/configuring-synchrony-858772125.html
https://confluence.atlassian.com/doc/recognized-system-properties-190430.html
https://confluence.atlassian.com/doc/configuring-system-properties-168002854.html
编辑/opt/atlassian/confluence/bin/setenv.sh文件,未尾增加如下内容:
重启服务,修改效果可以从“站点管理→协同编辑”进行查看,如下:
如果没有协同编辑需求,那么可以把这个功能关掉,这样在编辑页面还会出现预览选项,可以先预览再发布。
调整备份路径
自定义HTML
Confluence最强大的定制功能是自定义HTML,用户可以通过自定义HTML为Confluence中的每个页面都添加HTML代码,从而实现源码级定制。
自定义HTML可以插入到页面的三个位置中:
- HEAD尾部
- BODY头部
- BODY尾部
实际使用中,HEAD尾部一般插入JavaScript代码和CSS引用,BODY尾部一般插入自定义的HTML元素。下面讲解如果通过自定义HTML为页面增加更加丰富的定制功能。
使用JavaScript
参考:https://confluence.atlassian.com/confkb/how-to-use-javascript-in-confluence-313458839.html
这里需要注意的是,Confluence自带了JQuery,这就为操作页面元素提供了巨大的便利。虽然可以在HEAD尾部通过<script>
标签引入标准的JQuery库,但强烈推荐使用Confluence内置的JQuery,否则可能出现意想不到的问题,比如本站在尝试引入标准JQuery库和Bootstrap之后,出现过空间目录不显示内容的情况。
Confluence的JQuery通过AJS.$
的方式来使用,以下是一个示例:
AJS.$('div.foo');
如果想要通过AJS来执行代码,比如函数,那么必须将代码放到toInit
函数中执行,这样就可以保证代码一定是在AJS被初始化之后再调用,如下:
AJS.toInit(function(){ console.log("hello"); });
导航栏添加自定义链接
这里在导航栏上添加一个“空间目录”链接以直达空间目录列表,并将原来的“空间”下拉列表删除,方法如下,在HEAD尾部增加以下代码:
<script> AJS.toInit(function(){ AJS.$('.aui-header-primary .aui-nav').append('<li><a href="/confluence/spacedirectory/view.action" class=" aui-nav-imagelink">空间目录</a></li>'); AJS.$('.aui-header-primary .aui-nav li').first().css("display", "none"); }); </script>
效果如下:
自定义页脚并注明备案号
这里调整一下Confluence的默认页脚,删除不需要的信息,把备案号和工信部网站备案查询的链接加上,方法如下,在HEAD尾部增加以下代码:
<style> .no-after:after { content: none; } </style> <script> AJS.$('#poweredby').prepend('<li><a href="https://beian.miit.gov.cn">浙ICP备2021003588号</a></li>'); AJS.$('#poweredby > li').slice(-3).remove(); AJS.$('#poweredby > li').last().addClass('no-after'); }); </script>
效果如下:
实现back-to-top
Confluence默认没有回到顶部按钮,这里通过自定义HTML和JavaScript把这个功能补全。按钮的样式源码来自知乎,操作如下,首先在BODY尾部增加按钮图标,并通过CSS将其固定在右下角:
<button id="back-to-top" style="position: fixed; bottom: 12px; right: 12px; width: 40px; height: 40px; color: #8590a6; background-color: transparent; border-radius: 4px; border: none; outline:none; display:none;"> <svg fill="currentColor" viewBox="0 0 24 24" width="24" height="24"> <path d="M16.036 19.59a1 1 0 0 1-.997.995H9.032a.996.996 0 0 1-.997-.996v-7.005H5.03c-1.1 0-1.36-.633-.578-1.416L11.33 4.29a1.003 1.003 0 0 1 1.412 0l6.878 6.88c.782.78.523 1.415-.58 1.415h-3.004v7.005z"> </path> </svg> </button>
然后在HEAD尾部增加自定义JavaScript代码,实现按钮的淡入和淡出,以及点击回到顶部的功能:
<script> AJS.toInit(function(){ AJS.$(document).ready(function () { // 初始时回到顶部按钮为dysplay:none,根据滑动条位置控制是否显示回到顶部按钮 AJS.$(window).scroll(function () { if (AJS.$(this).scrollTop() > 50) { AJS.$('#back-to-top').fadeIn(); } else { AJS.$('#back-to-top').fadeOut(); } }); // 点击回到顶部 AJS.$('#back-to-top').click(function () { AJS.$('body,html').animate({ scrollTop: 0 }, 200); return false; }); // 鼠标悬停和离开时改变风格 AJS.$('#back-to-top').mouseover(function () { AJS.$('#back-to-top').css("background-color", "#d3d3d3") }).mouseout(function () { AJS.$('#back-to-top').css("background-color", "transparent")}); }); }); </script>
实际效果参考本站即可。
编写用户宏以支持思维导图
简单来说,可以把宏看成是Confluence内置的超级模板,宏可以插入到编辑器中,根据宏的功能和参数,在实际渲染后,宏就可以显示成各种不同的功能。以本站主页为例,页面显示的空间列表和最近更新都是通过宏来插入的。
Confluence内置了一系列宏,这些宏可以实现诸如显示目录,显示空间列表,最近更新,标签云,页面树等功能,具体可以参考Confluence编辑技巧。
除了使用内置的宏,还可以编写用户宏以实现更加复杂的功能,这里以jsmind宏为例,这个宏借助开源的JavaScript脑图库jsMind,实现了在页面中插入freemind格式的思维导图的功能,效果如下:
编写用户宏参考链接:
https://developer.atlassian.com/server/confluence/confluence-user-macro-guide/
https://confluence.atlassian.com/doc/writing-user-macros-4485.html
https://confluence.atlassian.com/doc/user-macro-template-syntax-223906130.html
https://developer.atlassian.com/server/confluence/confluence-objects-accessible-from-velocity/
首先将jsMind的代码上传到服务器公共目录,这里上传到/static/jsmind路径。注意这里用的jsMind和官方的不一样,为了适应Confluence环境,有些地方作了调整,可通过提交记录查看修改了哪些地方。上传完服务器公共目录之后就可以在自定义HTML中引入jsMind的源码,HEAD尾部添加以下内容:
<link rel="stylesheet" type="text/css" href="/static/jsmind/jsmind.css" > <script type="text/javascript" src="/static/jsmind/jsmind.js"></script>
然后通过”站点管理→用户宏“新增一个用户宏,命名为jsmind,宏正文处理选择无渲染,宏主体代码如下:
## Macro title: jsmind ## Macro has a body: Y ## Body processing: Unrendered ## Output: Rendered mindmap ## ## Developed by: midlane.top ## Date created: 2021/03/20 ## Installed by: midlane.top ## Confluence Server上的jsmind宏,用于显示freemind格式的脑图,用到了jsMind库,参考 https://github.com/hizzgdev/jsmind ## This macro renders freemind text into mindmap, jsMind is used, see https://github.com/hizzgdev/jsmind ## @param UUID:title=UUID|type=string|required=true|default=jsmind_container|desc=UUID,用作脑图div容器的id,必须唯一 ## @param Mode:title=Mode|type=enum|enumValues=side,full|default=full|desc=布局模式,full:子节点分布在两侧,side:子节点只分布在根节点右侧,默认为full ## @param Theme:title=Theme|type=enum|enumValues=belizehole,primary,warning,danger,success,info,greensea,nephrite,wisteria,asphalt,orange,pumpkin,pomegranate,clouds,asbestos|default=belizehole|desc=主题 ## @param Overflow:title=Overflow|type=boolean|default=false|desc=是否显示滑动条,默认不显示 ## @param Public:title=Public|type=boolean|default=true|desc=是否对访客用户公开 #if (($paramPublic==true) || ($action.authenticatedUser)) <ac:structured-macro ac:name="info"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:rich-text-body> <div id=$paramUUID></div> <script type="text/javascript"> AJS.$(document).ready(function() { let mind = { "meta":{ "name":`$paramUUID`, "author":"midlane.top", "version":"0.2", }, "format":"freemind", "data":`$body` }; let options = { container:`$paramUUID`, editable:false, theme:`$paramTheme`, mode:`$paramMode` }; // 这里用window对象记录一下Confluence的baseurl,freemind中使用相对路径的方式引用Confluence的内容,可避免修改Confluence的baseurl导致脑图路径失效问题 window.confluence_baseurl = `$settingsManager.getGlobalSettings().getBaseUrl()`; let jm = jsMind.show(options,mind); jm.add_event_listener(function(type, data) { if (type === jsMind.event_type.resize) { let height = jm.view.size.h; //console.log(height); $('#'+`$paramUUID`).height(height); } }); if(!$paramOverflow) { AJS.$('#'+`$paramUUID`+'> .jsmind-inner').addClass('no-overflow'); } }); </script> </ac:rich-text-body> </ac:structured-macro> #end
宏新增完后,就可以在编辑器中调用这个宏了,比如上面的脑图对应freemind源码如下:
<map version="1.0.1"> <node ID="root" TEXT="中心节点"> <attribute NAME="expanded" VALUE="true"/> <node ID="8d37d23e590eaf78" POSITION="right" TEXT="子节点1"> <attribute NAME="expanded" VALUE="true"/> </node> <node ID="8d37d2584595ede3" POSITION="right" TEXT="子节点2"> <attribute NAME="expanded" VALUE="true"/> </node> <node ID="8d37d27bc9aa6b4a" POSITION="right" TEXT="子节点3"> <attribute NAME="expanded" VALUE="true"/> </node> </node> </map>
以上也可参考https://github.com/zhongluqiang/jsmind/blob/master/jsmind-macro/README.md,这里有一份更详细的说明。
编写用户宏以支持Graphviz
Graphviz是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。这里采用JavaScript版的Graphviz实现viz.js来在网页上绘制图形,宏的工作原理与上面的jsmind宏类似。首先通过自定义HTML的HEAD头部引入依赖的JS文件,这里通过CDN的方式引入,便于快速加载,因为viz.js的主文件体积超过1M,放个人网站上占用宽带较大。
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/viz.js/2.1.2/viz.js"></script> <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/viz.js/2.1.2/full.render.js"></script>
接下来插入graphviz宏,通过”站点管理→用户宏“新增一个用户宏,命名为graphviz,宏正文处理选择无渲染,宏主体代码如下:
## Macro title: graphviz ## Macro has a body: Y ## Body processing: Unrendered ## Output: Rendered graphviz ## ## Developed by: midlane.top ## Date created: 2021/04/20 ## Installed by: midlane.top ## 将graphviz图形数据渲染成svg,使用了viz.js库,参考https://github.com/mdaines/viz.js/ ## This macro renders graphviz dot text into svg,see https://github.com/mdaines/viz.js/ ## @param UUID:title=UUID|type=string|required=true|default=graphviz_container|desc=UUID,用作graphviz div容器的id,必须唯一 ## @param Public:title=Public|type=boolean|default=true|desc=是否对访客用户公开 #if (($paramPublic==true) || ($action.authenticatedUser)) <ac:structured-macro ac:name="panel"> <ac:parameter ac:name="borderStyle">none</ac:parameter> <ac:rich-text-body> <div id=$paramUUID></div> <script type="text/javascript"> AJS.$(document).ready(function() { if(!window.viz) { console.log(' new Viz()'); window.viz = new Viz(); } //console.time(`$paramUUID`); window.viz.renderSVGElement(`$body`) .then(function(element) { AJS.$('#'+`$paramUUID`).append(element); }) .catch(error => { window.viz = new Viz(); console.error(error); }); //console.timeEnd(`$paramUUID`); }); </script> </ac:rich-text-body> </ac:structured-macro> #end
接下来就可以使用graphviz宏来插入图形了,下面是一个示例:
strict digraph { a [shape="ellipse" style="filled" fillcolor="#1f77b4"] b [shape="polygon" style="filled" fillcolor="#ff7f0e"] a -> b [fillcolor="#a6cee3" color="#1f78b4"] }
注意,viz.js在绘制较复杂的图形时非常占用CPU,比如在性能较差的客户端浏览器上绘制一个有9个节点和14条边的状态机可能会耗时1秒以上,这会造成页面加载卡顿,实际使用时应考虑到这一点,尽量用Graphviz来绘制较简单的图形,对于较复杂的图形,建议直接插入图片。
配置站点通知横幅
参考:https://confluence.atlassian.com/confkb/how-to-add-a-site-wide-banner-165609599.html
进站点管理页面,在自定义HTML中将相关代码插入到BODY首部。
示例1:通知横幅
<!-- Message Banner --> <div style="background-color: yellow; border: 2px solid red; margin: 4px; padding: 2px; font-weight: bold; text-align: center;"> 本网站将于今晚进行升级维护、数据更新,可能会导致部分网页访问受到影响,无法正常浏览,特此告知。 </div>
效果预览:
示例2:可关闭的通知横幅
<div class="aui-message closeable"> <p class="title"> <strong>通知</strong> </p> <p>本网站将于今晚进行升级维护、数据更新,可能会导致部分网页访问受到影响,无法正常浏览,特此告知。</p> </div>
效果预览:
配置应用程序导航器
站点管理→应用程序导航器,未添加链接时页面左上角不显示导航窗口,添加后可显示导航窗口,单击可快速跳转指定链接,效果如下:
- No labels