It's better when it's simple

User Tools

Site Tools


Back to RefNotes plugin

RefNotes Discussion Archive

As evidenced by the poorly organized page below, Wiki format is not particularly suitable for prolonged discussions. Please use bug tracker to report bugs or request new features.

Worked example?

I think it would more instructive to just have a worked example. I've been reading and experimenting for a couple of days and I still can't get it to do anything beyond the normal dokuwiki note syntax. My goal is to separte bibliographies from content (in the editor—otherwise its imposible to write anything with lots of footnotes), prefererably using bibtex or the database plugin. If you could just have a couple of pages with just the underying code to look at, along with the expected output. I see bits of syntax, but I still can't tell how to put it all together. Looks like a great plugin, but I can't tell how to use it. –Jack Daniels—

Bibtex, reference to template

I really love your plugin, it could be exactly what I need. I'm trying to get it work with bibtex references. I have created a file in wiki/data/pages/refnotes/biblio containing a Bibtex reference inside “code Bitex” snipets. :

<code bibtex>
  Title                    = {In Search of a Basic Principle for Model Driven Engineering},
  Author                   = {Jean Bézivin},
  Year                     = {2004},

  Abstract                 = {In November...}
</code >

I tried to get a reference to that with something like


, but whithout any success… Any ideas ? — Nils B.Fol

2014/12/08 22:30

First make sure that reference database is enabled in the plugin configuration and its namespace is set to :refnotes:. Then read reference database documentation page, namely where it says:

Do not confuse this namespace (part of DokuWiki page name) with namespaces of notes (RefNotes formatting) defined on the page — they are completely independent. For example, on :refnotes:programming page you can define a note called :ref:Knuth68. In order to reference this note from some other page you should refer to :ref:Knuth68.

Since you didn't specify any namespace for Bezivin2004 note, it falls into the root namespace. If you even consider using BibTeX, I guess, that wasn't the intention. Again, read the documentation:

The namespace can be either specified as part of the entry key or in a separate comment. The namespace specified in the comment is used for all following entries within the current code block that do not have namespace specified explicitly.

So I would recommend to start your BibTeX page with

  namespace = "biblio"

and use [(:biblio:Bezivin2004)] to add references to the note. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2014-12-10 23:44

It was a namespace problem indeed, adding the “@Comment{…}” had it working.

Thanks for your time! (and I should definitely learn to read…) — Nils B.Fol

2014-12-10 09:07

Structured references

why i cant get it work like this structured? i want a box with references info like on wikipedia people and books — Mona Texy 2014/04/05 11:20

You have to be more specific if you want to get some help. What are you doing? What do you expect to get? What do you get instead? — Mykola OstrovskyyMykola Ostrovskyy
pan One

2014-05-23 08:42

I have problems rendering structured text. I have used some of the examples, just to test:

refnote-id       : 1
reference-base   : text
reference-format : []
note-id-format   : []
note-id-base     : text

note-text : Harvard System of Referencing Guide
url       :

author     : Donald Knuth
title      : Arts of Programming, Volume 2: Seminumerical Algorithms
edition    : Third Edition
published  : 1997
publisher  : Addison-Wesley
note-pages : xiv + 762 pp.
isbn       : 0-201-89684-2
url        :

The subject of random number generation and has been extensively studied in computer science [(HarvRefSys)] and [(KnuthAoP2)].

What I get is


The subject of random number generation and has been extensively studied in computer science [1] and [2].

[1] > note-text : Harvard System of Referencing Guide url :

[2] > author : Donald Knuth title : Arts of Programming, Volume 2: Seminumerical Algorithms edition : Third Edition published : 1997 publisher : Addison-Wesley note-pages : xiv + 762 pp. isbn : 0-201-89684-2 url :


The citations in the text are ok, but the text in the references is not what I'm expecting.

What am I doing wrong?

— Miguel 2014/05/16 13:49

It looks like you are using an old version of the plugin. Just tried fresh install of DokuWiki 2014-05-05 with RefNotes 2012-07-15 – looks okay. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2014-06-17 08:07

Alternative note database lookup

I had difficulties making the plugin work, so I fixed it to work on my system, see hereElie Rouxeroux

2013/10/10 18:20

Eliminating multiple references?

I use RefNotes to add references to a bibliography. It works great but for one thing: if I have multiple occurrences of [(xxx)] in a page, then I get multiple occurrences of it in the bibliography (REFNOTES) section.

I've read the documentation several times, but cannot figure out how to eliminate it.

Can anyone help?

Fil Salustri 2013/07/28 20:45

It heavily depends on what “xxx” stands for. If it is literally “xxx” then I would suggest to use named notes: first reference is [(x3>xxx)] and all subsequent ones [(x3)].

Mykola OstrovskyyMykola Ostrovskyy
pan One

2013/08/02 21:14

An actual example: I changed the first occurrence of [(Eek00)] to [(eekels>Eek00)]. I left all other occurrences unchanged. You can see what I get at the bottom of

I wish I could understand what I was doing wrong.

Fil Salustri 2013/08/05 19:53

Change it back :-)

In plugin terminology, those things that are repeated in the notes block are called back-references. Your problem seems to be that you use back-ref-format: note (the default). Try to play with other styles that are available for back-ref-format. For example, back-ref-format: a; back-ref-base: sup; note-id-font-weight: bold might look better.

Mykola OstrovskyyMykola Ostrovskyy
pan One

2013/08/06 22:09

Ah-hah! I get it now. Thanks for your patience. Problem resolved.

Fil Salustri 2013/08/06 18:52

Missing popup in Angua

I have a localhost wiki with the latest (Angua) version installed. When I upgraded, I noticed that the mouseover tooltip popup is now longer displaying. I have also tested this with a clean install (not an upgrade install) and just this one plugin, and get the same result. If I uncheck “Use footnotes syntax”, then the tooltips work as expected, but also the named footnotes (((name>footnote text))) render as the name, and not the footnote itself. — AshtagonAshtagon

2012/02/25 23:29

In Angua there were significant changes in JavaScript, some of which are apparently breaking backward compatibility. I guess that's the reason for missing popup.

The “Use footnotes syntax” check box behavior is correct. When you uncheck it ((text)) syntax is handled by DokuWiki core (not by the plugin), so you get properly working popup but loose all extra features provided by the plugin (e.g. named notes). — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/02/26 16:35

Fixed in version 2012-07-15. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/15 22:59

I upgraded from Rincewind to Adora Belle and lost the popups. I have the latest refnotes and don't have the “use footnotes syntax” box checked — huithuit

2012/11/13 01:37

Could you please verify it on a clean Adora Belle install? — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/11/16 01:00

Use with data plugin

Is it possible to combine this with the data plugin, or another structured/semantic plugin? I would love to have one page for each publication (automatically generated, optionally with additional notes on etc), with a ref table on each. If I could use the data plugin to store the reference information, I could also generate lists of publications by author, by keyword, etc. — houshuanghoushuang

2011/04/30 03:32

Sounds interesting, but currently there are no plans for such integration. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2011/05/04 10:57

Implemented in version 2012-07-15. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/16 00:13

I am very excited by this plugin, it does exactly what I was looking for - with a bit of tweaking. I keep my bibliography in Bibtex (through BibDesk), and wanted to write a script that automatically created a bunch of pages in DokuWiki, one for each publication. I would then write notes about the publication on that page, and cite it in other pages, with a link back to that page.

So I set the :ref: namespace as my reference database namespace, create a few pages (manually for now) for each publication (use the bibtex cite key as the name of the page), and insert a table in each page with the citation info.

Then I made a tiny change to the syntax/references.php around line 860 (in the refnotes_harvard_note_renderer class), and changed this:

    private function renderTitle($field) {
        $text = $field['title'] . '.';
        if (array_key_exists('url', $field)) {
            $text = '[[' . $field['url'] . '|' . $text . ']]';
        return $text;

to this“:

    private function renderTitle($field) {
        $text = $field['title'] . '.';
            $text = '[[' . $field['note-name'] . '|' . $text . ']]';
        return $text;

That means that the title of the citation is always a link back to the page (I use the page name as the note-name).

Now the only thing that would really make my day, would be some way of making the 1) more like an APA citation (like Johnson & Morell (1990))… I would love to contribute to the code, but I need some guidance. feature request


2011/04/30 03:18

Actually, all of this is in a TODO list:

  • Basic BibTeX support in the reference database
  • Custom note/reference renderers based on semantic fields (structured notes)
  • Structured references (a.k.a. APA citations)

I think the first two items are too advanced to be used widely. The work on the last one has been started, but currently I don't have time for it :-(Mykola OstrovskyyMykola Ostrovskyy
pan One

2011/05/04 11:07

Hi there,

I am currently working on some of these features for my brother, as he needs them urgently for his work.

Currently, I nearly finished implementing:

  • A Bibtex parser based on bibtexParse from the Bibliophile project
  • A Bibtex entry formatter based on OSBiB (same project as bibtexParse), which is also used in the MediaWiki Plugin for bib files
    • this could also be used for other kinds of sources, it easily provides styles, like the requested APA one (the code of OSBiB is quite old and sometimes a pain in the ass, but it works, if you spend some time on it ;) )
  • some detail improvements of the code

Mykola, I would like to contact you in the next few weeks, when I finished with programming, testing and documentation - perhaps you can have a look on it and we put up an update for this plugin together? —Oliver Schmidt

I would add that this code requires using the structured mode. huithuit

Most of the discussed features are added in version 2012-07-15. Though, for the custom reference rendering you would still have to hack the code. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/15 22:56

@houshuang your tweek is exactly what I was looking for only that I would like to set an icon in between the backlinks and the reference itself - but even after quite some time of digging through code I can't seem to get it to work… any suggestions on where the problem resides?

Hack to hide namespaces

I prefer that the namespaces in the reference database sheets and cards be hidden. I was able to make it work by hacking refnotes/namespace.php, inserting the following around line 28:

function refnotes_parseName($name) {
+   $name = trim($name,'[]');	// hack to allow links as note names.  This will strip [[]] surrounding names
    $pos = strrpos($name, ':');

It allows you to use internal links, such as [[:ref:Knuth68]], for note names–refnotes will ignore the surrounding brackets with this hack. It works because DokuWiki hides internal link namespaces.

With this change your reference database may look like1):

Note name Note text
Knuth68 Knuth, Donald E. The Art of Computer Programming, Volume 1: Fundamental Algorithms, First edition, Addison-Wesley, 1968, ISBN 0-201-03801-3.
Knuth69 Knuth, Donald E. The Art of Computer Programming, Volume 2: Seminumerical Algorithms, First edition, Addison-Wesley, 1969, ISBN 0-201-03802-1.
Fowler99 Fowler, Martin; Beck, Kent; Brant, John; Opdyke, William; Roberts, Don. Refactoring: Improving the Design of Existing Code, Addison-Wesley, 1999, ISBN 0-201-48567-2.

Rik BlokRik Blok

2011/02/14 05:08

I have a bad feeling about this hack.

From looking around the source it seems to me, that this function is also used for lookups in the ref-database - so this might/should break namespaces in some way.

Maybe a more appropriate place to hack this is in refnotes/syntax/references.php line 715, 721 (or rather 188? dunno…). Looks more like the place, where the entries are rendered to the page.


2011/04/22 08:24

Multibyte languages support

Can't handle multibyte language? When I use Chinese for namespace, I can't create pages under it. When using Engligh, everything is OK. — lainme 2010/05/13 15:18

I'm not sure what you mean by “I can't create pages under it” as RefNotes namespaces have nothing to do with pages. Nevertheless you are right, multibyte languages are currently not supported. — Mykola Ostrovskyy 2010/05/24 19:24

Note block formatting issues


Thanks for the excellent work done with this plugin. My only issue is that if I try to add a References section per your example, I get a double underline between the header of the section and the references per se: one is coming from the section formatting, the other from the REFNOTES formatting. Any trick to solve this? The solution previously suggested (in previous Discussions) is not working.

Sylvain Foisy 2010/05/03

Did you try notes block separator style? For example:

===== References =====

<refnotes ref> notes-separator: none </refnotes>

Of course, you can also set this style in the configuration if you want to disable the separator permanently for a given namespace. — Mykola Ostrovskyy 2010/05/07 14:50


Thanks for the input :-) I try the block separator routine but no success. — Sylvain Foisy 2010/05/09

Nevermind… I goofed with the namespace :-( Everything looks great now. Keep up the good work! — Sylvain Foisy 2010/05/10

Consecutive numbering

Is there a way to achieve consecutive numbering of the notes? Independent of where the notes come from. If I mix notes from the reference database and footnotes, I get multiple references with the same number.

Tammo 2010/04/05

Every namespace has independent numbering. It doesn't matter if the notes are defined on the page or in the database. As long as you keep them in the same namespace the numbering will be consecutive. — Mykola Ostrovskyy 2010/04/07 20:30

I guess I don't understand something then. Here is a minimal example:

  * Test 1: [(This is a test reference)]
  * Test 2: [(:refnotes:lit:king65)] 


King65 is a book. I would like to have one database with all my books such that I can easily reference them on different pages, etc.

Thank you for your fast responses.

Tammo 2010/04/08

The namespaces are introduced for different formatting of the references and notes rather than for organizing your references collection. If you really want to keep King65 in :refnotes:lit: then all the notes, which you want to be in the same notes block (and have consecutive numbering), also have to be in that namespace:

  * Test 1: [(:refnotes:lit: > This is a test reference)]
  * Test 2: [(:refnotes:lit:king65)]

But I would rather suggest to use something along the lines:

  * Test 1: [(:ref: > This is a test reference)]
  * Test 2: [(:ref:lit_king65)]

Mykola Ostrovskyy 2010/04/09 20:13

Ok. The named note is a good idea. I will keep a single page will all my literature references. Now I get consecutive numbering. Thank you very much.

Tammo 2010/04/09

In version 2012-07-15 it is possible to merge namespaces, so you also could do something like:

~~REFNOTES : :refnotes:lit: ~~

Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/15 22:38

Citation page number

Is there a way to add a per citation page number to the reference? Something like [(:ref:knuth97>205)] leading to the following output: Knuth, Donald E., 1997. Random numbers. In Arts of Programming, Volume 2: Seminumerical Algorithms. Third Edition. Reading, Massachusetts: Addison-Wesley. p.205

Anonymous 2010/04/18

No. But I'm thinking about adding such thing in some future release (if there will be a future release). However, it will require significant changes to the syntax, so there is no timeline for this feature. — Mykola Ostrovskyy 2010/04/18 17:04

Added in version 2012-07-15. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/15 22:56

Namespaces confusion

Sorry I can't understand this. The preset namespace on the configuration page is :refnotes: and my database page is :refnotes:johnson1985. Now what note name am I supposed to give the entry? johnson1985, :ref:johnson1985, :refnotes:ref:johnson1985? I tried all variants but neither is working.

I tried to elaborate a bit on the difference between DokuWiki and RefNotes namespaces. Hope that helps. — Mykola Ostrovskyy 2010/04/11 23:45

Thanks, it is much clearer now. However, it is still not working when I do this:

On the page :refnotes:programming I insert a note.

Note name Note text
:ref:Knuth68 Knuth, Donald E. The Art of Computer Programming, Volume 1: Fundamental Algorithms, First edition, Addison-Wesley, 1968, ISBN 0-201-03801-3.

On another page I insert the [(:ref:Knuth68)]. This gives me a reference but then the note is not rendered at all when I add the note block using ~~REFNOTES~~. As opposed to that, when I add [(:ref: > This is a note.)] after the first reference, it is rendered correctly as note 2 (while note 1 is missing).

Am I missing something?

One thing to check is if configuration is okay:

  • The database is enabled (by default it's off).
  • The database namespace is :refnotes:.

Another is to verify that refnotes:programming page is mentioned in the page index (/data/index/page.idx). This index is used by the plugin to discover the database pages.

If both are true, then there might be something wrong. Report it on the bugtracker. — Mykola Ostrovskyy 2010/04/12 16:14

Complete formatting for inline notes

I tried to use bug tracker but I have yet to figure out how I can specify the plug-in, and what type of defect it is. I post my request here, just in case.

Inline notes can not be formatted completely in the configuration editor. Superscript for example seems to be enabled permanently. It would be best if all formatting could be done in the configuration editor.

Tammo 2010/04/05

See the rest of this discussion on the bug tracker. — Mykola Ostrovskyy 2010/04/18 17:18

More flexible formatting for inline notes is added in version 2012-07-15. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/07/15 22:59

Error after editing page

I get the following error(s) after I simply edited a page that contains references. The page displayed without problems. The editing was restricted to editing text (not references). The error messages are

  1. Warning: Cannot use a scalar value as an array in […]\DokuWikiStick\dokuwiki\lib\plugins\refnotes\syntax\references.php on line 242
  2. Warning: Cannot modify header information - headers already sent by (output started at […]\DokuWikiStick\dokuwiki\lib\plugins\refnotes\syntax\references.php:242) in […]\DokuWikiStick\dokuwiki\inc\common.php on line 1472

After closing the page and reopening it, everything displays fine. Simply reloading does not work. This is a rather annoying problem. Otherwise this is a great plugin. Thank you for your work.

Tammo 2010/04/02

It might be fixed in the latest version. If the problem persists, please report it on the bug tracker. — Mykola Ostrovskyy 2010/04/05 20:22

This seems to have fixed it. Thank you.

Configuration page doesn't work

The Configuration RefNotes gives error corrupted data from the server and I can not configure it. Installation without problems with the Manager plugins. This happens in Release 2009-12-25c “Lemming” of DokuWiki.

Any ideas? — Anonymous 05/11/2010

The only obvious thing that comes to my mind is to reinstall and try again. If that doesn't resolve the problem, please report it on the bug tracker. — Mykola Ostrovskyy 2010/05/24 19:14

I have the exact same problem in release 2011-11-10 No way to change the setup. The installation worked fine. I reinstalled, and obtained the same result. I wonder what to do. Michel 2012-01-01

There was an unreleased fix for webhosts that add extra stuff to served pages. If you don't run your own HTTP server, you could try to update action.php and admin.js to their latest versions. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/01/12 08:06

Note blocks

Hi I'm just a little confused with how to get the reference section like you did in the screenshot. Could you give the code you used? Specifically I want to have a References section with all my citations just like Wikipedia does.

Also the ~~REFNOTES~~ doesn't seem to work (i.e. doesn't place the note block where I put this tag) unless it's specified with the namespace (i.e. ~~REFNOTES cite~~ works fine.)

– Marc 20-Jan-10

Just create a section and put ~~REFNOTES ns~~ in it:

===== References =====

~~REFNOTES ref~~

As mentioned in the documentation, ~~REFNOTES~~ without namespace specification renders notes from the root namespace. If all your notes are in cite namespace ~~REFNOTES~~ will not render anything. — Mykola Ostrovskyy 2010/01/20 08:22

Ok I understand it better now. I guess I was confused by the huge amount of documentation and jargon. Thanks! The plugin works perfectly. — Marc 2010/01/21

Notes from reference database are not rendered

Could you give an example (ideally live) of linking to the reference database from an article?

I have…

  • configured the reference database to use the :ref: namespace
  • added bibliographic reference information in a card in :ref:longley2005 (using the namespace template)
Note name :ref:longley2005
Note text Longley, Paul A. Goodchild, Michael F. Maguare, David J. & Rhind, David W., 2005. Geographic Information Systems and Science. 2nd ed. Chichester: John Wiley & Sons Ltd.
  • linked to this in an article [(:ref:longley2005)]
  • nothing! no note text appears in the article

Anonymous 2009/10/03 20:19

From what you describe this is exactly how it's supposed to work. Please create an issue on the bug tracker and I will try to fix it. — Mykola Ostrovskyy 2009/10/04 16:22

See also

If you like you can create wikilinks for each reference so they don't appear broken.
plugin/refnotes/discussion.txt · Last modified: 2016-10-09 00:00 by