Annotations Application

Last modified by Oana-Lavinia Florean on 2021/11/02 13:55

annotations.pngAdd annotations to documents
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard


2.3+ (possibly 2.2 and 2.1 as well, but with tweaks)


The Annotations Application improves wiki experience by allowing users to annotate text in a XWiki document.

In order to be able to annotate documents you also need the annotations component, bundled with XWiki Platform starting from version 2.3. This extension only contains an UI for this component, allowing users to manipulate the annotations from the default XWiki UI.

Anca's talk at FOSDEM 2011 demoing XWiki's Annotation and explaining how they work:

Make annotations

To make an annotation to a piece of text all you have to do is select the text, hit Ctrl + M (Meta + M) and a dialog will appear where you may enter the text you want to associate with the selection. Click "Add annotation" and you're done.


Note that while annotations will work on scripted content (content rendered by wiki macros, or content generated by the script macros, such as the velocity macro), there is a limitation:

  • annotations will not be automatically updated (see the section below about "Edit Annotated text") when external content changes

Show annotations

By default annotations are not shown within the page.


To see the annotated items highlighted:

  • Click on the Annotations link at the top of the page for Colibri Skin


With the Flamingo Skin, you have to click on the "Annotate" item in the Content menu:


  • Check "Show annotations"


To see an annotation for a text item click on the yellow icon next to it.


All annotations can also be displayed at the bottom of the page in the Annotations tab. To enable the Annotations tab follow these steps:

  • Hover over "Wiki" and click on "Administer Wiki"
  • Click on "Page Elements"
  • Set the "Show document annotations" to "Yes"


Edit annotations

There are two ways to edit an annotation.

You can edit an annotation straight from the page. Click on the annotation icon to view the annotation and then click on the yellow pen. Once you are done with the changes click "Update".


The alternative is to edit annotations from the Annotations tab at the bottom of the page. Similarly you need to click the yellow pen, change the text and click "Update" when you are finished modifying the text.


Delete annotations

There are three ways of deleting an annotation.

To delete an annotation from the page click on the annotation icon to view the annotation and then click the red "X" button.


You have the same option if you're editing the annotation from the page.


You may delete annotations from the Annotations tab at the bottom of the page by clicking the "X" button next to the annotation.


Edit annotated text

Congratulations! You've successfully added annotations to your text. 

Taking into consideration the text is on a wiki there's a high probability it will be modified. As a result you may be confronted with the issue of whether an existing annotation is relevant to the newly changed piece of text. You'll notice the icon next to the annotated piece of text is orange instead of yellow. This helps you easily identify which of the annotated pieces of text have suffered changes, without consulting page history.

When clicking on the orange icon a popup will appear. You have the following options:

  • Validating the annotation for the new text by clicking the green button
  • Editing the annotation to better describe the modified text
  • Deleting the annotation altogether


You may validate the annotation from the Annotations tab as well.

Delete annotated text

When an annotated piece of text is deleted, the annotation for the deleted text can still be seen in the Annotations tab. The annotation will have the following message: "This annotation could not be displayed because the annotated text was not found in the document"


Filter annotations by author

By default when you check "Show annotations" all annotations for that page are displayed. To filter annotations by author click on "Refine the display criteria" and check those authors for which you would like to see annotations.


Configure annotations

The annotations feature can be configured in the dedicated section in the wiki administration section (Wiki -> Administer Wiki).


In this section, you can configure:

  • If annotations are active on the whole wiki or a subset of locations
  • If annotations are displayed by default or only when checking "Show annotations" on each page
  • If the annotations highlight should be displayed always or only on hovering an annotation or the structure of annotations (through an xwiki class).

After changing the configuration of the annotations in the Administration section you need to clean your browser's cache, otherwise the new settings will not be taken into account (or force refresh the pages with annotations, if you don't want to clear all the cache).

Threaded Annotations

Starting with version 4.0M2, annotations have been merged by default with comments. More specifically, this means:

  • You can now reply to an annotation (threaded annotations)
  • The Annotations tab is now replaced by the Comments tab where you can see both annotations and comments
  • The default annotation class is now XWiki.XWikiComments instead of AnnotationCode.AnnotationClass


If you are using a custom annotations class other than the previously default AnnotationsCode.AnnotationsClass in the annotations configuration then the merging-with-comments feature will not be available to you. What you can do is to enable back the Annotations tab by going to the Administration > Look and Feel > Page Elements and changing the value of "Show document annotations" from "No" to "Yes". Now you will still be able to use your custom annotations without being affected by the changes.

Annotations Shortcuts


Ctrl + M or Meta + M
Ctrl + I or Meta + I

Annotate a piece of text

Alt + A

Show annotations

Get Connected