Il y a deux parties principales de la syntaxe : les références et les blocs de notes. Les références sont utilisées dans un corps de texte pour définir une note et, lors du rendu, sont remplacées par un lien court. La syntaxe de référence de base est similaire aux notes de bas de page :

Voici la référence[(Ceci est une note.)].

Outre la fonctionnalité de base fournie par les notes de bas de page, les références ont un certain nombre de fonctionnalités supplémentaires :

• Meilleure prise en charge des références multiples à la même note.
• Tu peux nommer une note et y faire ultérieurement référence par son nom à partir d'une autre référence. Les notes nommées peuvent être partagées entre différentes pages via la base de données de référence.
• Les notes peuvent être regroupées dans des espaces de noms. Par exemple, vous pouvez séparer les notes de bas de page des références bibliographiques.
• Les références peuvent être masquées du rendu et utilisées uniquement pour définir le texte de la note. Cela peut être pratique si vous souhaitez séparer les notes du corps du texte principal.

Les blocs de notes indiquent un emplacement de page où le texte des notes sera rendu. Ils sont facultatifs et s'il n'y a pas de blocs de notes explicites sur la page, toutes les notes seront rendues à la fin de la page. La syntaxe minimale pour le bloc note est :

~~REFNOTES~~

Outre la spécification de l'emplacement des notes, les blocs de notes peuvent être utilisés pour :

Afficher les notes d'un certain espace de noms. N'affichez qu'une partie des notes. Par exemple, cela peut être utilisé pour afficher les notes dans plusieurs colonnes. Modifiez la mise en forme des références et des blocs de notes.

Très souvent, il est nécessaire de se référer plusieurs fois à la même note. Les exemples courants citent la même source plusieurs fois ou ont un tableau de “comparaison des fonctionnalités” dans lequel les cellules ne contiennent que des valeurs “Oui/Non” mais il y a des informations ou des exigences supplémentaires associées à la cellule. DokuWiki permet de faire référence à une note de bas de page existante en copiant son texte. Pour empêcher le copier-coller du texte, l'extension RefNotes te permet de référencer une note avec la syntaxe [(#?)], où ? est le numéro de la note :

Exemple : C'est là que la note est introduite la première fois^#1. Et voilà que tu dois faire une seconde référence à la première note^#1.

C'est là que la note est introduite la première fois[(Voici la première note.)].
Et voilà que tu dois faire une seconde référence à la première note[(#1)].

Chaque fois qu'une note est introduite dans le texte, elle reçoit un numéro séquentiel comme identifiant. La référence supplémentaire à la même note n'augmente pas le compteur de notes, donc dans l'exemple ci-dessus une référence [(#2)] serait ignorée car il n'y a pas de deuxième note.

Lorsque plusieurs références à une seule note sont rendues, DokuWiki utilise un identifiant séparé (numéro séquentiel) pour chaque référence. Avec RefNotes, vous pouvez choisir si vous souhaitez que plusieurs références aient des identifiants uniques ou partagent l'identifiant de la note à laquelle elles se réfèrent (voir config multi-ref-id).

Se référer à une note par son numéro est source d'erreurs car au cours de l'historique de la page ce numéro peut changer ! Une autre façon d'identifier le billet est de lui donner un nom unique. Pour le nom, tu peux utiliser n'importe quelle chaîne de caractères alphanumériques et de traits de soulignement commençant par une lettre. Le nom est séparé du texte de la note par un signe “>“ :

[(nom>Cette note s'appelle "nom".)]

En cas de références multiples, la note nommée peut être référencée en omettant le texte et en utilisant uniquement son nom. Les noms sont sensibles à la casse, alors assures-toi d'utiliser l'orthographe exacte. La note reçoit toujours l'identifiant numérique séquentiel, vous pouvez donc y faire référence dans les deux sens :

C'est là que la note est introduite pour la première fois[(nom>Ceci est une note.)].
Et voici une autre référence[(#1)] à la même note. Et encore une autre référence[(nom)] à cette même note.

L'avantage le plus important des noms par rapport aux identificateurs numériques est que la note nommée est définie au point où son nom est utilisé la première fois même si aucun texte n'y est attaché. Plus loin dans le texte, le corps de la note peut être redéfini avec la syntaxe habituelle :

C'est là que la note est introduite pour la première fois [(nom)].
Et voici une autre référence [(#1)] à la même note. Et encore
une autre référence[(nom>Ceci est une note.)].

En combinaison avec les Références cachées, cela permet de déplacer les définitions de texte de note hors du corps du texte principal et de les regrouper, par exemple, à la fin de la page. Le texte de la note peut être redéfini un certain nombre de fois mais la dernière définition avant le rendu de la note est la seule qui compte. Les notes nommées peuvent également être définies en dehors de la page qui y fait référence. Cela peut se faire soit depuis l'interface de configuration, soit dans la base de données de référence.

Les notes ayant un objectif similaire (par exemple, les citations) peuvent être regroupées dans un espace de noms séparé. Chaque espace de noms est rendu séparément et peut avoir son propre style pour le formatage des références et des notes. Les espaces de noms RefNotes suivent le style DokuWiki — l'espace de noms et le nom sont séparés par deux-points :

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

Toutes les références qui ne spécifient pas l'espace de noms pointent explicitement vers les notes dans l'espace de noms racine (:). Ainsi, les deux références suivantes pointent vers la même note :

La première référence[(note>Ceci est une note.)] et la seconde[(:note)].

The strict rules for the note naming are slightly released for fully qualified note names. If name starts with namespace specification, apart from alpha-numeric characters you can also use some extra symbols, so you can have notes named like, for example, “Smith&Johns(2012).” Note that this applies only to note names – namespace names are still restricted to alpha-numeric characters. The following symbols are allowed in the extended name syntax:

Les règles strictes pour la dénomination des notes sont légèrement relâchées pour les noms de notes complets. Si le nom commence par la spécification de l'espace de noms, outre les caractères alphanumériques, vous pouvez également utiliser des symboles supplémentaires, de sorte que vous pouvez avoir des notes nommées comme, par exemple, “Smith&Johns(2012).” Notez que cela ne s'applique qu'aux noms de note – les noms d'espace de noms sont toujours limités aux caractères alphanumériques. Les symboles suivants sont autorisés dans la syntaxe de nom étendu :

. & ( ) [ ] { } + -

Namespaces can be nested one into another. The nested namespace inherits all style properties from the parent namespace. This inheritance take place once during parsing of a page – at the point of first reference to the sub-namespace. 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).

Les espaces de noms peuvent être imbriqués les uns dans les autres. L'espace de noms imbriqué hérite de toutes les propriétés de style de l'espace de noms parent. Cet héritage a lieu une fois lors de l'analyse d'une page - au point de première référence au sous-espace de noms. À partir de là, le style des espaces de noms parent et secondaire peut être modifié indépendamment. Il est également possible de surcharger cet héritage en spécifiant explicitement un autre espace de noms (voir la description du style hériter).

Note text can be defined either as plain DokuWiki markup or as collection of named data fields. The fields are combined into the note text according to note-render style. Inside the reference the text is treated as fields if it starts (or is separated from name) with double ”>” sign:

Le texte de la note peut être défini soit comme un balisage DokuWiki simple, soit comme une collection de champs de données nommés. Les champs sont combinés dans le texte de la note selon le style note-render. A l'intérieur de la référence, le texte est traité comme des champs s'il commence (ou est séparé du nom) par le double signe “>“ :

[(GangOfFour>>
titre   : Modèles de conception : éléments de logiciels réutilisables orientés objet
auteurs : Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides
éditeur : Addison-Wesley
publié  : 1994
pages   : 395
)]

Dans une page wiki, la référence définie ci-dessus peut être incluse avec :

[(GangOfFour)]

Structured References pour plus de détail sur cette syntaxe.

Parfois, en particulier dans les tableaux, le texte de la note rompt la structure visuelle du balisage wiki et il est préférable de déplacer la définition de la note ailleurs. Les notes nommées vous permettent de référencer une note qui n'a pas encore de texte, mais éventuellement le texte doit être défini, ce qui normalement introduirait une référence supplémentaire à la note. Pour éviter ce comportement, toutes les références définies au début d'une ligne sont exclues du rendu.

|                    ^ Produit 1  ^ Produit 2  ^ Produit 3  ^
^ Caractéristique A  |  Oui       |  Oui[(a)]  |  Oui[(a)]  |
^ Caractéristique B  |  Oui       |  Oui[(a)]  |  Non       |
^ Caractéristique C  |  Non       |  Oui       |  Oui[(b)]  |

[(a>Une certaine exigence.)]
[(b>Une autre exigence.)]

Pour être masquées, les références doivent être placées dans un paragraphe séparé. Ainsi, dans l'exemple suivant, les références seront rendues même si elles sont au début d'une ligne :

Les références suivantes
[(a>Ceci est une note.)]
[(b>Une autre note.)]
sera rendu.

Toutes les références aux notes en ligne utilisent le texte de la note comme texte de référence. Les notes elles-mêmes ne sont pas ajoutées à la section des notes, de sorte que les références sont le seul endroit où le texte de la note est affiché. Comme il n'y a pas d'entrée dans la section des notes vers laquelle pointer, aucun lien n'est ajouté à la référence. Mais il est recommandé d'inclure un lien dans le texte de la note, afin que les références puissent pointer quelque part. Par exemple, un cas d'utilisation typique pour les notes en ligne est d'avoir des espaces réservés de référence manquants similaires à ^{[citation nécessaire]} de Wikipédia.

Les notes en ligne ne peuvent être créées qu'à partir de l'interface de configuration. Là, vous pouvez également contrôler les styles d'espace de noms appliqués aux références.