这里记录配置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文件，未尾增加如下内容：

重启服务，修改效果可以从“站点管理→协同编辑”进行查看，如下：

如果没有协同编辑需求，那么可以把这个功能关掉，这样在编辑页面还会出现预览选项，可以先预览再发布。

调整备份路径

参考： https://confluence.atlassian.com/conf710/configuring-backups-1031840918.html#ConfiguringBackups-configoption 

自定义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");
});

导航栏添加自定义链接

参考：https://confluence.atlassian.com/confkb/how-do-i-add-links-to-confluence-5-x-s-top-global-header-navigation-bar-358908020.html

这里在导航栏上添加一个“空间目录”链接以直达空间目录列表，并将原来的“空间”下拉列表删除，方法如下，在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宏来插入图形了，下面是一个示例：

这个图形对应的Dot源码如下：

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