It's better when it's simple

User Tools

Site Tools


textinsert Plugin

Compatible with DokuWiki

  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes
  • 2014-05-05 "Ponder Stibbons" yes
  • 2013-12-08 "Binky" yes

plugin Replace macro variables with words, phrases, paragraphs, and include other macros, and entities, in the macro definitions

Last updated on

Similar to easyvar, fields, kixovar, macros, replace

Tagged with entities, entity, macro, replace


Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. If you cannot use the Dokuwiki download Manager to install this plugin, install it manually. Refer to manual_instructions for how to install plugins manually.


This plugin provides an administrative panel where you enter macro names and their substitution texts. These are saved in the meta directory (in meta/macros/macros.ser). You can save individual words, and strings of text, including lengthy paragraphs. The substitutions accept html, quotation marks and other punctuation. The macro names can accept spaces, dots, underscores and hyphens.

So, Macro_1.txt is a valid macro name and could, for instance, have the following substitution: /var/usr/lib/php/readme.txt.

You could have a footer message, FOOTER-1, which has the following text substitution:

All Roads Lead to "Here" except for the ones which don't

The textinsert plugin will allow you to create macros for extended texts. You can create paragraph length texts with HTML markup which have to be repeated, for instance, as instructions at the tops of pages. If you want the HTML to be rendered as such, then the macro name must have the _HTML suffix:


Note: The underscore is required.

Macro Inclusions

Some of the functionality of this plugin at its simplest can be implemented with Dokuwiki's own entities facility: entities. But for complex substitutions and for control over where and how substitutions are made, textinsert offers a wide variety of solutions and techniques.

One advantage of TextInsert comes when dealing with extended blocks of text and with its ability to include other macros inside the primary macro definition. That is, it can accept:

MACRO_1  This macro can include #@MACRO_2@# inside it.
MACRO_2  a second macro

The result with syntax #@MACRO_1@# is:

  This macro can include a second macro inside it.

It accepts only one level of macro inclusion, so that if MACRO_3 were included in MACRO_2, MACRO_3 would not be rendered. If an include macro requires treatment as HTML, then the primary macro must be named as an HTML macro.

Entity Inclusions

TextInsert will also accept entities in its macro definitions. These are defined in dokuwiki/conf/entities.conf and dokuwiki/conf/entities.local.conf. Entities will be replaced in included macros as well as in the primary macro. For instance, if MACRO_2 above were defined as follows, using Dokuwiki's long dash entity:

 MACRO_2  a second---macro---

The final result would be: This macro can include a second—macro—inside it.

Standard Namespace Macros

Textinsert will accept namespace macros as used in Dokuwiki namespace templates. See Namespace Templates for the list of these. Textinsert can accept all but the MAIL and NAME macros, which go out of scope when the page is saved. Like regular textinsert macros these can also be embedded in other textinsert macros; see macro_inclusions. For instance, a macro named current_user and a user named jack:

Macro Definition
#@current_user@#The Current user is #@USER@#

This would give you: The Current user is jack.

There is a configuration option which governs whether or not standard namespace macros are accepted. It is set to true by default.

Example of Multi Paragraph Text Block

If you want to create multi-pragraph blocks, then you need to use the HTML paragraph tag, <P>. . .</P>. The textinsert plugin will accept paragraphs like the the following, which is the introductory header found on the textinsert administration page:

This panel enables you to add and delete macros and their replacement
texts, and to edit them after they have been saved.  A macro name can contain letters, 
numbers, underscores, hyphens and periods. For example:&nbsp;&nbsp;<TT>Macro_one.txt</TT>
The replacement texts can accept HTML and can be of any length.
You can add up to six macros at a time.  The sixth is a text area which will allow for extended texts.
Enter the macro name in the <b>Macro</b> column and the texts which they represent in the
<b>Substitution</b> column. 
Deletions are unlimited; check off the box(es) next the macro(s) to be deleted and click
the Delete button at the bottom of the screen. Editing is done through the Edit screen, where you are presented
with all your macros.  You can edit the texts of any number of macros.

Screen Shot of Edit Panel



In the second format, HTML tags, like <P>text. . .</P> will be rendered as HTML; otherwise they will be rendered as HTML entities, as in &lt;P&gt;.

The Macro names are case sensitive, so that Macro-A and macro-A are two different names.

Macro names are silently deaccented.

Expanded Functionality

The current version of textinsert handles foreign language translation and supports macros which accept parameters. If you don't need these features or if this version causes any issues you can download the earlier version: simplified version.

Parameter Interpolation


Macro Definition as defined on page:

  #@macro_name~param1,param2,param3. . .param<n>~@#

Replacement String defined in Macro database:

  string %1 more string %2 . . .%<n>

%1 will be replaced by param1,%2 by param2, etc.


MacroMacro Replacement String
Mountain_RangesIn Europe there are the %1, in North America the %2 and in South America the %3

Result: In Europe there are the Alps, in North America the Rockies and in South America the Andes

Language Translation

This version of textinsert makes translation substitutions based on ISO-derived namespaces.1) Macros found in an ISO-derived namespace will be read within the language context specified by the ISO designation.

Macros of this type must use the following syntax:


A default entry for this type of macro must be entered into the textinsert database as LANG_name. The translation strings must be stored in textinsert/lang/<ISO>/lang.php in the $lang array, using 'name' for the key. If you have a macro named LANG_greeting, then in lang.php the entry will be:


If a translation is not found, the default string will be used.


This example is based on the namespace de, which references German pages.

You create a page named de:my_file into which you enter the following macro: #@LANG_greeting#@. In the database you enter a default entry under the name LANG_greeting. In textinsert/lang/de/lang.php, you create an entry for $lang['greeting'].

In each lang.php, you need only a single entry, for instance:

  $lang['greeting'] = 'Hello from Germany'; 

When you include #@LANG_greeting@# in your document, the country identified by the IS0 namespace will be printed with its HTML formatting.


Translation macros can be included in standard and HTML macros. They also accept Dokuwiki-defined entities, as described above. There is no special HTML translation macro. Any HTML features which appear in a language-based macro will automatically be output as HTML when the macro occurs in a language context.

Macro Name Definition
1 LANG_nation <h2>I live in Canada</h2>
2 nation_HTML #@LANG_nation@#
3 LANG_city Toronto

If the default replacement string contains HTML, then you should use form 2 in the above table when not in a language context; otherwise the HTML will appear in your output as plain text and the HTML will be lost.

In a language context, any HTML that you place in your definition will be output as HTML. Assume this is ths definition for LANG_nation in the lang/de/lang.php:

 $lang['nation'] = 'Ich lebe in <b>Kanada</b>';

In the German namespace, #@LANG_nation@# will be output as HTML: Ich lebe in Kanada.

It is also possible to include macros in your translations:

 $lang['city'] = 'Berlin ';
 $lang['nation'] = 'Ich lebe in <b>#@LANG_city@#</b>, in Deutschland';

This results in: Ich lebe in Berlin, in Deutschland

Configuration and Settings


Change Log

20 Sep 2011: Removed debugging output to file in root directory accidentally left in in syntax.php

Known Bugs and Issues

ToDo/Wish List


Question: What about macros with arguments? I'd like - for example - substitute @#google(DokuWiki)#@ with

This has now been addressed. See syntax for expanded version above.


I get the following error message: ksort() expects parameter 1 to be array, boolean given in C:\xampp\htdocs\testdoku\lib\plugins\TextInsert\admin.php on line 98

and: Invalid argument supplied for foreach() in C:\xampp\htdocs\testdoku\lib\plugins\TextInsert\admin.php on line 139

can you help?



I've uploaded a possible fix to github. But it may merely get rid of the error message, while the plugin itself may still not work properly. See the latest version. But truthfully, I'm not sure why this is happening, unless the macro database file is not saving correctly. This may be a Windows issue and I'll have to look into that further if you don't have any success.


The plugin doesn't seem to work using the latest Dokuwiki release (Weatherwax). A new “insertext” page appears on the admin board, but clicking on the buttons doesn't do anything.

I think you will find that this is now fixed. I was using a discontinued jquery-like function that Dokuwiki previously provided.

The info text in the Administration → Plugins has some gotchas! (namely the site is misspelled, and there is no link to this page)

Thanks. Some of that was left over from the initial development. I've cleaned up the Info and all should be OK now.

Much better. Nice work.

When searching, macros aren't being replaced, so if I have COMPANY macro set to “Example Corp.”, I'll find nothing for “example” term while will succeed with “COMPANY” term. This is quite inconvenient and not user-friendly at all.

This has nothing to do with textinsert.
Myron TurnerMyron Turner

2013/12/05 03:01

When using TextInsert with a plugin that adds syntax, such as Wrap, any of the new syntax defined in macro definitions is not processed, instead displaying as-is, possibly due to TextInsert processing the page after Wrap does. Anything to be done here?

My test does not show this: wrap_with_textinsert

Myron TurnerMyron Turner

2014-11-14 11:34

Try it the other way around. Define some Wrap syntax inside a macro, as if trying to simplify making an infobox.

Macro substitution not working inside of a header. Given MYMACRO defined as neat stuff!:

====== #@MYMACRO@# Woo! ======
#@MYMACRO@# Woo!

Renders as

#@MYMACRO@# Woo!

neat stuff! Woo!

You can't put markup inside a header:

This is a header **trying** to be bold

Feature Request

:!: Hy, regarding the macro not working in headings. I am using numbered headings plugin and it works perfectly. I am not sure what is the difference in code, but it would be awesome if this plugin could do the same.

The numberedheadins plugin doesn't add markup; it just adds text – the numbering. And the indentation levels shown on the plugin page are a function of the old dokuwiki default template, which indented headings according to the heading levels. — Myron TurnerMyron Turner

2016-02-13 04:48

:!: It would be awesome if this plugin could process wiki syntax and be combined with other plugins

A previous user asked a similar question (above). You can include textinsert in other plugins, such as the wrap plugin, but this would have to be tested for each plugin. The question would be whether the other plugins accept nested plugins. As for including markup, for most syntax features you don't need another plugin since you can already include html in textinsert macros. — Myron TurnerMyron Turner

2015-06-17 15:51
1) This is consistent with the scheme used by the translation plugin.
plugin/textinsert.txt · Last modified: 2016-02-27 22:48 by turnermm