RefNotesPlugin

Footnotes for Foswiki

Description

This plugin brings a footnotes / endnotse / references solution to Foswiki on par with plugins on other wiki engines such as mediawiki or dokuwiki. Previous work exists such as FootNotePlugin which did not allow to display reference lists on a page freely, breaks custom skins such as NatSkin and had a few other limitations. The TWiki solution EndNotePlugin has never been ported to Foswiki. In fact FootNotePlugin has been based on EndNotePlugin but suffered the same limitations. To further progress a full rewrite is provided in this plugin. Features:

• named references to be reused multiple times on a page
• multiple groups of references such as "Notes", "Figures", "Literature" etc.
• extended formating features for reference lists
• improved styling of reference links

Examples

You type:

 Tim Berners-Lee%REF{ Tim Berners-Lee is now director of the World Wide Web Consortium, and Professor of Computer Science at Southampton ECS. }% invented the World Wide Web. 

You get (if installed):

Tim Berners-Lee%REF{ Tim Berners-Lee is now director of the World Wide Web Consortium, and Professor of Computer Science at Southampton ECS. }% invented the World Wide Web.

You type:

 This is page content.%REF{ "_LibreOffice For Starters_, First Edition, Flexible Minds, Manchester, 2002, p. 18" id="libreoffice" }% LibreOffice%REF{id="libreoffice"}% forked from OpenOffice%REF{id="Corbet" "Corbet, Jonathan. _[[https://lwn.net/Articles/637735/][Development activity in LibreOffice and OpenOffice]]_. LWN.net. 30 September 2018. Eklektix, Inc." }% which in turn was derived from StarOffice. 

You get (if installed):

This is page content.%REF{ "_LibreOffice For Starters_, First Edition, Flexible Minds, Manchester, 2002, p. 18" id="libreoffice" }% LibreOffice%REF{id="libreoffice"}% forked from OpenOffice%REF{id="Corbet" "Corbet, Jonathan. Development activity in LibreOffice and OpenOffice. LWN.net. 30 September 2018. Eklektix, Inc." }% which in turn was derived from StarOffice.

You type:

 This is a note reference.%REF{"Wonder what this note is all about." group="notes"}% 

You get (if installed):

This is a note reference.%REF{"Wonder what this note is all about." group="notes"}%

Syntax

REF

Reference Links are established the content using the %REF makro:

Parameters	Description	Default
"..." or text="..."	reference note; may be omitted when reusing a named reference
id="..."	assign a citation key to the reference or reuse an already defined reference	random
group="..."	optional group which lists this reference	default
label="..."	label for this reference only; see label format below	(1)
tooltip="on/off"	toggle displaying the reference note in a tooltip	on
hidden="on/off"	only define a named reference but don't display nor add it to the references list unless being used by another %REF reusing this named reference	off
overwrite="on/off"	this allows to redefined a named reference; if not specified explicitly an error will be produced when an already known citation key is being defined	off

REFERENCES

In general all references are to be displayed at the bottom of the page. You may do so explicitly using the %REFERENCES macro. Note that NatSkin does so automatically.

Parameters	Description	Default
group="..."	name the group to render all references for; renders all groups if left empty
showhidden="on/off"	display all references, even hidden ones not used on the topic	off
labels="..."	label for all references in this group; this overrides the label format specified per reference
header="..."	header string prepended to the output	<ul class='refNotes foswikiNoBullets $group'>
format="...."	format string for each reference note in the list	<li id="$id"><b>$label</b> $text </li>
separator="..."	separator string between each note rendered
footer="..."	footer string appended to the output	</ul>
<_group>_title="..."	custom title for a group	default_title="References"

The format parameter may contain the following variables:

• $index: running reference number
• $id: key of a reference as provided by the user or a random one otherwise
• $label: label used to display the reference link
• $text: net content of the reference note

In addition header, separator and footer may have:

• $group: name of the refernce group
• $count: number of references in a group
• $numGroups: number of groups
• $title: title of reference group (e.g. "Reference" for the default group)

REFIMPORT

This macro is only available if feature "bibtex" is available on your platform (see section #Extended_Features below).

This macro allows to import a bibtex file to the list of available references. The citation key of a bibtex entry can then be used as an id in the %REF macro.

Parameters	Description	Default
"..." or attachment="..."	name of the bibtex file attached to a topic
topic="..."	name of the topic where the bibtex file is attached	current topic
group="..."	name of the reference group which the entries are assigned to	default
labels="..."	define the default label for all imported references

Note that importing large bibtex files (+1000 entries) might cause a significant delay when first importing it. A further request will fetch them from a cache. The cache is kept in sync if you update the bibtex file later on. To force-refresh the bibtex cache using the ?refresh=bibtex or ?rerfesh=on url parameter.

Label Formats

The format of reference links can be configured using the REFNOTESPLUGIN_LABELFORMAT preference setting. This setting will then be used for all reference links and notes within its scope. Each individual %REF can have its own label format as specified by the label="..." parameter.

Examples:

default arabic labels in round brackets:

 * Set REFNOTESPLUGIN_LABELFORMAT = (1)

arabic labels with a right bracket only:

 * Set REFNOTESPLUGIN_LABELFORMAT = 1)

alphabet labels with brackets:

 * Set REFNOTESPLUGIN_LABELFORMAT = (a)

hexadecimal labels with square brackets:

 * Set REFNOTESPLUGIN_LABELFORMAT = [x]

romanian labels without brackes:

 * Set REFNOTESPLUGIN_LABELFORMAT = i

Possible label types:

• 1 - numeric
• a - alphabetic
• A - upper case alphabetic
• i - romanic (only available if feature "roman" is available)
• I - upper case romanic
• k - citation key
• K - upper case citation key
• x - hexadecimal
• X - upper case hexadecimal

Brackets are specified by the character before and after the label type. Note that romanic labels are only available if you installed the required depencies (see below).

Using predefined references

Sometimes there is a set of references that are the same on each page of a documentation. These can be predefined in a separate topic, say "CommonReferences". In this topic references are defined like this:

 %REF{ "Voudouris, C., Tsang, E.P.K., Partial Constraint Satisfaction Problems and Guided Local Search, Proceedings of the Second International Conference on the Practical Application of Constraint Technology (PACT'96), pp 337-356, London, UK, 1996 " id="voudouris1996" hidden="on" }% 

%REF{ "Voudouris, C., Tsang, E.P.K., Partial Constraint Satisfaction Problems and Guided Local Search, Proceedings of the Second International Conference on the Practical Application of Constraint Technology (PACT'96), pp 337-356, London, UK, 1996 " id="voudouris1996" hidden="on" }%

Note the hidden parameter. This will define the reference name only but not display it unless being refered to later on. To include all common references use %INCLUDE{"CommonReferences"}% somewhere at the start of the documentation. Predefined reference can then be used by:

%REF{id="voudouris1996"}%

and this added to the reference list from there on:

Guided local search%REF{id="voudouris1996"}% is a metaheuristic search method. A meta-heuristic method is a method that sits on top of a local search algorithm to change its behavior.

PatternSkin integration

To display reference lists on the bottom of a page add the refnotes skin overlay to your SKIN preference setting as in:

 * Set SKIN = natedit, refnotes, pattern

Extended Features

There are a couple of features that might or might not be available on your platform depending on the instaled CPAN packages. Installing these optional dependencies will enable them as required:

Feature	Dependency	Description
roman	Roman	enables roman letters as reference labels
bibtex	BibTex::Parser, Sereal::Decoder, Sereal::Encoder	enables importing bibtex files

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

 cd /path/to/foswiki perl tools/extension_installer <NameOfExtension> install 

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Roman	>=1.0	Optional
BibTeX::Parser	>=1.0	Optional
Sereal::Encoder	>=5.0	Optional
Sereal::Decoder	>=5.0	Optional

Change History

18 Oct 2025	added bibtex importer; added label format k and K
17 Oct 2025	added toolip
13 Oct 2025	initial implementation