Simple Cite Confluence plugin

Scope

This Wiki page is the basic user documentation for the Simple Cite Confluence plugin. It contains (hopefully) all necessary detail to use the plugin effectively.

This documentation only covers the latest released version.

What is it?

The Simple Cite Confluence plugin brings citation functionality to Confluence. The functionality can be compared to the citation you know from Wikipedia. You can define your own custom cites, refer to BibTeX cites included in an attachmend bib-file or refer to DOIs.

How to get it?

There are two ways of getting the plugin for Confluence Server:

• Atlassian Marketplace
• via the download section of this repository (you want to download the jar)

The version for Confluence Cloud version can be installed via the Marketplace:

• Atlassian Marketplace

Privacy policy

Please refer to the our privacy policy.

License

Copyright 2017 by Andreas Purde

Licensed under the Apache License Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

How it works

In the image above you see the tree different types of macros you will be using. The macros shown in the first line are used to initially define a cite on a page. The second line shows the Single Cite Short macro which is used to refer to cite which has already been defined. The last row shows the macros you can use to show a list of references.

Basic macros

The following macros reflect the basic functionality. You will have to use at least "Single cite" (or "BibTeX cite" or "DOI cite") and "Cite summary" in combination to get what you want.

Macro "Single cite" and "Single cite plain"

A single cite (e.g. the reference to a book) is reflected by that macro. It consists out of a unique ID an optional page range and the reference itself - like: ID: Miller92, pages: 1-10, reference: Miller, "The art of citation", London 1992. Unique ID and page range are parameters of the macro which you have to enter when you add the macro. The reference has to be specified in the macro body (the white part of the box) what allows you to add formatting, links etc.

Cloud only: as Atlassian broke the functionality to use macros with rich text bodies inline we added the "Single cite plain" macro. You can use it to define plain text cites and if needed add a link to them.

Macro "Single cite Short"

Once a cite has been fully qualified by the single cite macro it is possible to use that macro to refer to the same reference again just using the unique ID and the page-range if needed.

Remark: it is also possible to use the single cite macro mentioned before for that purpose (leaving the reference (the macro body) empty). However the single cite short macro renders more nicely in the Confluence editor as you will see in the following screenshots.

Macro "Single cite import"

You may use this macro to refer to a cite you defined on another Confluence page. Simply select the page you want to import the cite from and specify the ID of the cite.

Macro "Cite summary"

At the end of a page containing cites you will probably want to have a reference section which shows you all the references you made in the article. This is achieved by the Cite Summary Macro.

The server version has the following additional parameters:

• local summary: check this box in case you want to include a local cite summary which only shows the cites defined between the last Cite Summary or the beginning of the beginning.
• CSL format: this parameter is only relevant when you want to show BibTeX or DOI cites. Please refer to the section CSL styles to learn which styles are supported.
• Show cites as tooltip: when checked the cites are additionally shown as tooltip when you hover over a reference (e.g. [1]).
• Override citation (BibTeX and DOI only): override the citation like [1] with the style provided by the CSL format.
• Enumeration style: you can select between some enumeration styles like 1., [1], (1).
• Show citation links: show the link to each citation next to the enumeration

When rendered the macro provides links back from the Cite Summary to the specific cite.

How does it look like?

When rendered:

In the editor (only parts are shown):

DOI support

Macro "DOI cite"

With the DOI cite macro you can refer to a DOI (Digital Object Identifier) which automatically gets rendered in the specified CSL style (e.g. apa). In the server version the CSL style defined in the Cite Summary is used in the cloud version you have to specify the CSL style in each DOI cite macro. Please refer to the section CSL styles to learn which styles are supported.

The DOI 10.1109/VETECS.2010.5493979 requested in apa CSL style results in:

Kusume, K., Dietl, G., Abe, T., Taoka, H., & Nagata, S. (2010). System Level Performance of Downlink MU-MIMO Transmission for 3GPP LTE-Advanced. 2010 IEEE 71st Vehicular Technology Conference. doi:10.1109/vetecs.2010.5493979

BibTeX support on Confluence Server

Macro "BibTeX Cite"

The BibTeX cite macro allows you to reference to a cite provided in a BibTeX file (*.bib). Simply specify the cite ID as well as the page where the BibTeX file is attached and the file name of the BibTeX file. The dialog provides a selection of files ending with ".bib" on the specified page. In case the BibTeX entry you are referring to contains the url tag you can include a link to it (shown in the summary) by checking "Include link".

Remarks: * potential errors of a BibTeX cite will be shown in the cite summary * Simple Cite only evaluates the url tag not the howpublished tag

Macro "BibTeX Cite with custom link"

This macro adds some functionality to the BibTeX Cite macro to show text (with or without a custom link) in addition to the BibTeX cite in the cite summary or the BibTeX cite itself is shown as a link it the summary. Unfortunately the usability of that additional functionality is poor due to some technical constraints. What you need to know:

• The placeholder $BiBTeX has to appear in the macro body - otherwise you get an error message in the cite summary
• The placeholder $BibTeX is replaced by the BibTeX cite
• All links (including a link on $BibTeX) will remain - in case you just want to show the BibTeX cite as link just let the macro body be >>$BibTeX<< with a link on that expression

Remark: potential errors of a BibTeX cite will be shown in the cite summary

The two examples below should help to understand the functionality. The first picture shows the editor the second the rendering result.

renders to

Macro "BibTeX Listing"

The BibTeX Listing shows all entries of the specified BibTeX-file in a table. In case the BibTeX entry you are referring to contains the url tag you can include a link to it by checking "Include link".

Credits

I want to thank Lars Willighagen for providing citation.js.

BibTeX support on Confluence Cloud

Macro "BibTeX Cite"

The BibTeX cite macro allows you to reference to a cite provided in a BibTeX file (*.bib). Simply specify the bib-file and provide the cite ID from the bib-file to show. Unlike in the server version you have to specify the CSL style individually for each cite (e.g. apa). Please refer to the section CSL styles to learn which styles are supported. You may add an external or internal link to the cite.

Please note that changes of the used bib-file are not detected automatically. In case you update the affected entry in the bib-file you must open the editor again and rebuild your cite.

Credits

I want to thank Lars Willighagen for providing citation.js.

Additional functionality

Macro "Space Cite Summary"

The space cite summary macro allows you to specify a list of spaces (comma-separated list of space keys) and then shows all cites used in these spaces. The table generated allows to get an overview of e.g. which pages refer to a certain reference like a standard.

On the server version the macro takes one optional parameters:

• CSL format (server version only): this parameter is only relevant when you want to show BibTeX or DOI cites. Please refer to the section CSL styles to learn which styles are supported.

on Confluence Cloud it might take a while before new cites show up here - Confluence has to update the search index first

CSL styles

For the DOI and BibTeX macros you have to specify a CSL style which indicates how the cite is rendered. In the server version the style is a parameter of the Cite Summary or Space Cite Summary, in the cloud version the style has to be specified in each single cite. Please refer to the listings below to identify allowed styles:

BibTeX (server version until 1.6.0)

• acm-siggraph
• apa-5th-edition
• apa
• chicago-author-date
• council-of-science-editors
• gost-r-7-0-5-2008
• harvard-anglia-ruskin-university
• ieee
• iso690-author-date-en
• iso690-numeric-en
• modern-language-association-6th-edition-note
• modern-language-association
• sist02

BibTeX (cloud version and server version starting 1.7.0)

According to the documentation almost any of the styles from here can be used. However I did not try all of them.

DOI (server and cloud version)

According to the documentation any of the style from here. However not all of them might work.

Certain behavior

Multiple definition of a reference for the same unique ID

In case you define a reference multiple times using the same cite ID only the one reference will make its way to the cite summary (reference list). In the server version the first reference wins, on the cloud version the last reference wins.

Using single cite short too "early" (server only)

In case you use the singe cite short macro to refer to a cite ID which you did not fully specify before (cite ID and reference) you will get a sentence in the cite summary that tells you that.

Jumps from the Cite to the Cite Summary when having multiple Cite Summaries

When you use multiple Cite Summaries on one page you may notice that the link from the Cite to the Cite Summary always jumps to first occurrence of the Cite in a Cite Summary.

Preview

When inserting the macro you see a preview on the right hand side of the dialog. In this preview mode the cite number as well as the cite summary might not show the actual result. Background: Simple Cite only needs the saved page content to calculate the cite number and build the cite summary.

Getting support

Please use out ticketing system to create a support request regardless wether you found a bug or have a feature request. Existing bugs or feature requests are here for the server version and here for the cloud version.