RefNotes Syntax

• RefNotes plugin
• RefNotes Syntax
• RefNotes Style Reference
• RefNotes Reference Database
• RefNotes plugin discussion

There are two major parts of the syntax: references and note blocks.

The basic reference syntax is similar to the footnotes:

[(This is a note.)]

As with the footnotes, the reference is replaced with a link to the note text. The text itself is typically rendered elsewhere. There are number of ways to customize the reference link (see style) but by default it looks like a footnote: a sequential number with right parenthesis.

Quite often it is required to refer multiple times to the same note. Common examples are citing the same source multiple times or having a “feature comparison” table where cells contain only “Yes/No” values but there is some extra information or requirement associated with the cell. DokuWiki allows to refer to an existing footnote by copying its text. To prevent copy-pasting of the text, using RefNotes you can reference a note with [(#?)] syntax, where ? is the number of the note:

This is where the note is introduced the first time[(This is a note.)].
And here is another reference[(#1)] to the same note.

Every time a note is introduced in the text it gets a sequential number as an identifier. The extra reference to the same note does not increase the note counter, so in the example above a reference [(#2)] would be ignored as there is no second note.

When multiple references to a single note are rendered, DokuWiki uses a separate identifier (sequential number) for every reference. With RefNotes you can choose whether you want multiple references to have unique identifiers or to share identifier of the note they refer to (multi-ref-id style).

Referring to a note by it's number is error-prone as over the history of the page this number can change. Alternative way of the note identification is giving it a unique name. For the name you can use any alpha-numeric string that starts with a letter. The name is separated from the note text with a ”>” sign:

[(name>This is a named note.)]

In case of multiple references, the named note can be referred to by omitting the text and using only its name. The names are case sensitive, so make sure you use the exact spelling. The note still gets the sequential numeric identifier, so you can reference it both ways:

This is where the note is introduced the first time[(name>This is a note.)].
And here is another reference[(#1)] to the same note. And yet another reference[(name)].

The most important advantage of names over numeric identifiers is that the named note is defined at the point where its name is used the first time even if there is no text attached to it. Later in the text the note body can be re-defined with the usual syntax:

This is where the note is introduced the first time[(name)].
And here is another reference[(#1)] to the same note. And yet
another reference[(name>This is a note.)].

In combination with the hidden references this allows to move the note text definitions out of the main text body and group them, for example, at the end of the page. The note text can be redefined a number of times but the last definition prior to the note rendering is the only one that counts. The named notes can also be defined outside of the page that refers to them. This can be done either from the configuration interface or in the reference database.

The notes with similar purpose (e.g. citations) can be grouped into a separate namespace. Every namespace is rendered separately and can have it's own style for references and notes formatting. The RefNotes namespaces follow DokuWiki style — the namespace and name are separated by a colon:

[(cite:>[[wp>DokuWiki|Wikipedia]])]
[(cite:dev>[[http://www.dokuwiki.org/development|DokuWiki Development]])]
[(cite:#1)]

All the references that don't specify the namespace explicitly point to the notes in root namespace (:). So the following two references point to the same note:

The first reference[(note>This is a note.)] and the second[(:note)] one.

The namespaces can be nested into another namespaces. The nested namespace inherits all style properties from the parent namespace. This inheritance take place once during the sub-namespace creation, from that point the style of the parent and sub-namespaces can be changed independently. It is also possible to override this inheritance by explicitly specifying another namespace (see the inherit style description).

Sometimes, especially in the tables, the note text breaks visual structure of the wiki markup and it's preferable to move the note definition elsewhere. The named notes allow you to reference a note that has no text yet, but eventually the text has to be defined, which normally would introduce an extra reference to the note. To prevent this behavior all references that are defined at the start of a line are excluded from rendering.

|            ^  Product 1  ^  Product 2  ^  Product 3  ^
^ Feature A  |     Yes     |   Yes[(a)]  |   Yes[(a)]  |
^ Feature B  |     Yes     |   Yes[(a)]  |     No      |
^ Feature C  |     No      |     Yes     |   Yes[(b)]  |

[(a>Some requirement.)]
[(b>Another requirement.)]

In order to be hidden the references have to be placed in a separate paragraph. So in the following example the references will be rendered even if they are at the start of a line:

The following references
[(a>This is a note.)]
[(b>Another note.)]
will be rendered.

All references to the inline notes use the note text as reference text. The notes themselves are not added to the notes section, so the references are the only place where the note text is displayed. There is no extra formating added to the text and, as there is no entry in the notes section to point to, there is no link. But it is recommended to include some link into the note text, so that references can point somewhere.

It may seem that inline notes are just a fancy way to put some text in superscript, but the main idea behind this feature is to have a mechanism that would allow to implement the iconic^{[citation needed]}

The inline notes can be created only from the configuration interface.

By default all the notes are rendered at very bottom of a page just above the footnotes. There is no need to add any markup on the page in order to get this behavior.

Yet it's possible to specify the notes location explicitly with the following syntax:

~~REFNOTES~~

During rendering this keyword is replaced by all the notes from the root namespace. You can provide extra attributes to this command to specify the namespace to be rendered or to limit number of notes that will be rendered:

~~REFNOTES cite ~~
~~REFNOTES cite 10 ~~
~~REFNOTES cite /2 ~~

If the notes limit specification starts with a slash, the plugin will render only specified part of the notes. For example, /2 will render half of the notes, /3 will render a third, etc. This can be handy if you want to render the notes in multiple columns:

===== Citations =====
<columns 100% 50%> ~~REFNOTES cite /2 ~~ <newcolumn> ~~REFNOTES cite ~~ </columns>

Every namespace can have its own style for rendering references and notes. You can define this style either via the configuration interface or directly on the page using alternative notes syntax:

<refnotes>
refnote-id       : a
reference-format : []
note-id-format   : []
note-id-base     : text
</refnotes>

This syntax combines the style definition with the notes rendering. If you want to keep the styling separate from the rendering you can place such definition somewhere on the top of the page before any references — if there are no notes in a given namespace the rendering commands are ignored.

The style definitions have to be separated either by a new line character (one definition per line) or by semicolon. Of course you can also specify the namespace and the rendering limit:

<refnotes cite /2> refnote-id: i; note-preview: none </refnotes>

All omitted styles are either derived from the parent namespace or are set to their default value. The default style resembles the footnotes formatting as close a possible.

All supported styles are listed on the style reference page.

Every time you render the notes you introduce a new scope. The scope includes all references above the note block and the block itself. References and notes below the rendering instruction belong to the next scope. By default every scope has its own reference and note counters, so by rendering the notes you effectively reset the numbering of the references. Though, it is possible to merge all the scopes of a namespace into a single one using the scoping style.

Every namespace has its own scoping. All styling applied to the namespace being rendered is used in the current scope and all scopes that follow.