Columns Plugin

—- plugin

description: Arrange information in multiple columns. author : Michael Arlt email : type : syntax lastupdate : 2009-08-30 compatible : 2009-02-14 depends : conflicts : similar : tags : boxes downloadurl: bugtracker : sourcerepo :

You can arrange your information in multiple columns. Column breaks must be inserted manually. I use a table with one <td> for each column. This worked best together with the S5 plugin from Andreas Gohr.

Simply add two lines around your information and enter your column breaks.

The first parameter is the width of the table. The following parameters are for the columns. If you do not want to specify a value for the table- or column-width use “-” instead.


information in column 1


information in column 2

<columns 100% 50% - ->

information in column 1 (50% width)


information in column 2


information in column 3


The syntax is mostly identical to the original version, except that the new column keyword has to be specified within angle brackets1):

<columns 100% 50% - ->

information in column 1 (50% width)


information in column 2


information in column 3


By default the text in columns is justified. This can be changed by adding asterisks on either side of the column width specification. The asterisk indicates non-justified side of the text block, so to achieve left alignment add the asterisk on the right side.

<columns 100% 25% 25%* *-* *->

Justified text


Aligned on the left side




Aligned on the right side


Following a number of requests, the plugin is re-designed to support headings and vertical alignment of the columns content. In order to support the new features syntax of the plugin is extended with extra attributes that should be specified in front of the column width:

<columns 100% first column attributes 50% second column attributes ->

Content of the first column.


Content of the second column.


With this extra attributes the columns declaration gets more and more cluttered. To prevent that you can specify column attributes in the <newcolumn> tag. In this case the order of the attributes and column width is not important:

<columns 100% first column attributes 50%>

Content of the first column.

<newcolumn second column *-* attributes>

Content of the second column.



The headings are specified the using the standard DokuWiki syntax:

<columns 100% 50% ->

===== Heading =====

Content of the first column.


Content of the second column.


By default plugin puts the content within a column without explicitly specifying the section level. This works fine when the entire columns block belongs to a single section but can produce unexpected results when the headings are used within the block:

====== Level 1 Heading ======

<columns 100% 50% ->

Implicit level 1 content.

===== Level 2 Headline 1 =====

Level 2 content.


Implicit level 1 content that should be in level 2 section.

===== Level 2 Headline 2 =====

Level 2 content.


You can force the beginning of the second column to be in level 2 by specifying “continue” attribute (or shorthand “...”):

====== Level 1 Heading ======

<columns 100% 50% ->

Implicit level 1 content.

===== Level 2 Headline 1 =====

Level 2 content.

<newcolumn continue>

Level 2 content.

===== Level 2 Headline 2 =====

Level 2 content.



The vertical alignment is specified with new alignment attributes. There are four horizontal alignment attributes (left, center, right and justify) and three vertical alignment attributes (top, middle and bottom). There may be multiple alignment attributes per column:

<columns 100% left 50% right bottom ->

Aligned on the left side.


Aligned to the right-bottom corner.


All attributes can be abbreviated to the first letter, the single letter attributes may be merged together:

<columns 100% l 50%>

Aligned on the left side.

<newcolumn rb>

Aligned to the right-bottom corner.

<newcolumn m *-*>

The old alignment syntax is still supported.
Content of this column is centered both ways.


Starting from version 2009-08-22 the plugin supports export to OpenDocument Format via Open Office Export plugin. Just as in the case of XHTML rendering, the columns layout is implemented with tables. While most of the columns formatting can be exported to an ODT document, there are some limitations:

  • Horizontal alignment of the columns is not supported. According to the ODF specification the text alignment should be applied on a paragraph level and there is no way to specify it for a table column.
  • The ODF specification has very limited support for relative units in the width attributes, so the relative units are converted into the absolute ones:
    • em — converted to points (pt) using coarse approximation based on the default paragraph font size as specified in styles.xml.
    • % — converted to page width units (typically cm). This conversion works reliably only on the top-level column blocks. If you plan to export nested columns to ODT it is better to define width of all blocks (width of the table) as 100%, and widths of the individual columns in some absolute units (e.g. cm, in, etc.)

The keywords can be customized - see DokuWiki: administration → configuration.

Language Start End Next Column
German <spalten> </spalten> ~~NEUESPALTE~~
Spanish <columnas> </columnas> ~~NUEVACOLUMNA~~

Install the current release with the plugin manager. Have a look at the DokuWiki plugin configuration.

2009-08-30 Download Columns3
2009-01-31 Download Columns2
2007-10-22 Download Latest version of the original plugin by Michael Arlt


  • Added CSS style sheet for printing
  • More appropriate placement of the section edit buttons. If columns start with a heading, the buttons are placed at the end of the column where the section text ends instead of the start of the next column.


  • Added support for ODT export
  • Fixed Include plugin compatibility
  • Fixed crash in case of too many columns specified in the <columns ... > tag
  • Fixed broken page layout if the first heading happens to be inside of a column


  • Added section continuation support
  • Fixed section edit issue
  • Fixed in-line columns handling

2009-03-15 (beta)

  • Added support for headings within the columns
  • Added vertical alignment support
  • New extended syntax
  • The plugin is split into syntax and action plugins


  • Fixed alignment of tables within a column


  • Added nesting support
  • Removed extra margin at the bottom of the columns block, which together with paragraph margin of the column content often caused double margin


  • Added Spanish localization (thanks to Digna Gonzalez Otero)
  • Added Russian localization


  • Added extended syntax to specify text alignment in the columns
  • To make the syntax fully compatible with the original plugin, the angle brackets around the new column keyword can be disabled from the configuration manager


  • Fixed issue with the backlinks
  • Columns styling is moved from configuration to style.css file
  • Slightly different syntax: the new column keyword is wrapped in angle brackets (i.e.


  • First public release
  • All desired features of the author are implemented

Andreas Gohr for DokuWiki and now: S5!

This product is released under the GPL 2

Please report bugs or feature requests at the bug tracker.

Does not work for me at all. It is installed, I see the plugin in admin. But the plugin is doing nothing at all, just as if it were not installed. I can see ~~NEWCOL~~ as plainly as any other text. — Anonymous 2010/01/12 00:19

Since version 2008-08-23 the default syntax of the column separator is

. You can enable the legacy ~~NEWCOL~~ syntax on the configuration page but some of the new features will not be supported. — Mykola Ostrovskyy 2010/01/14 08:24

I can't get the “continue” or “…” feature to work. Even the example shown above doesn't work. I took the «code» tags out, previewed it, and it behaves exactly like the previous example that's supposed to demonstrate the problem. Has anyone gotten this to work? (And what happened to the signature button in the editor?) — DGM2 2009/11/05

I did. Though, I guess, this is not really representative. It always works on developer's machine ;-)

If you really sure that you found a bug, please report it to the bug tracker.

(The signature button doesn't show up if you are logged out) — Mykola Ostrovskyy 2009/11/06 18:08

Not sure if this is where to put this - but it seems that this plugin breaks the bottom toolbar - and the Edit / Old revisions / Subscribe / etc buttons all show as form buttons, rather than the 'normal' style. I tested with the examples above, and they all seem to do it.

It seems it has something to do with using headers (of any level) within the columns - remove those and it all formats OK. -Nick W 2009/08/04 09:11

I don't see it. Could you send me screen shots and HTML of correctly rendered page (without headings) and the broken one (with headings)? Preferably create a new page and try to reproduce the problem with minimal text/markup. What do you use in terms of software (browser, versions of DokuWiki, PHP, plugin)? — Mykola Ostrovskyy 2009/08/04 19:00

Fixed in version 2009-08-22. — Mykola Ostrovskyy 2009/08/22 17:04

Installing the columns plugin in above-mentioned DokuWiki version results in the following error on every page:

Fatal error: Call to a member function on a non-object in …/dokuwiki/lib/plugins/columns/action.php on line 255

Pekka <> 2009/07/18

I can confirm this. Same for me.
hgi [at] gmx [dot] at 2009/07/24

As far as I can tell this has nothing to do with 2009-02-14b. At least I was able to reproduce it with 2009-02-14. The problem seems to be caused by a mismatch of the number of columns in the <columns ... > tag with the actual number of columns. The plugin chokes when there are to many columns in the tag.

I will make a new release. Hopefully soon, but I want to figure out what is the story with include plugin first. In the mean time you can try to fix your syntax if it's indeed broken. — Mykola Ostrovskyy 2009/07/26 18:54

Fixed in version 2009-08-22. — Mykola Ostrovskyy 2009/08/22 17:04

Hello. Thanks for this great plugin!

Could you please add support for the ODT plugin? This is a great plugin to export wiki content in a static file. I guess this plugin may receive pure XHTML as input, but doesn't get display different columns by now.

I'd be happy to help testing… but am too bad a coder to hack your code to that extend. Thanks!

berteh, 3rd of June 2009

Implemented in version 2009-08-22. — Mykola Ostrovskyy 2009/08/22 17:04

When using the include plugin, PARSER_HANDLER_DONE is triggered multiple times. This may lead to the reuse of internal variables in the columns plugin - which are not valid anymore.

Therefore I made the following modifications in action.php:

  function action_plugin_columns() {

 * Reset class vars
  function reset() {
	$this->block = Array();						// empty block array
	$this->block[0] = new columns_root_block();
      $this->currentBlock = $this->block[0];
      $this->currentSectionLevel = 0;

And calling

	$this->reset(); 	// reset in case PARSER_HANDLER_DONE is triggered multiple times for a page (may happen with include plugin)

at the end of handle()

— Anonymous 2009/06/06

Fixed in version 2009-08-22. Thanks for the patch. — Mykola Ostrovskyy 2009/08/22 17:04

When the </column> command is added after a heading, if a person tries to edit using section edit, that close tag will appear in a section of text where the opening tags are not present, and it creates an error. Is there any way to avoid this? Is there a way to add some kind of interim tag like <same column> that could go after headings to allow section edit? (I don't know, I'm new here….) — Anonymous 2009/03/27 00:49

Fixed in version 2009-03-29. — Mykola Ostrovskyy 2009/04/04 13:21

The new release does not process headlines inside columns. e.g. the following code results on the plain ===== Headline =====:

<columns 100% 50% - > ===== Headline ===== <newcolumn> nonono </columns>

Rodrigo Reboucas 2008/10/12 16:27

I'm not sure it's a bug per definition. AFAIK, there is no error in the plugin that would cause it. It seems that DokuWiki has a limitation that doesn't allow to include headings into other modes.

While the headings look like a nice feature at the first glance, there are number of questions that arise when you consider it in detail:

  • If there are two columns in a block and the first one uses heading, should the left margin associated with the heading level be applied also to the contents of the second column?
  • If there is a nested columns block in the first column, should the margin be applied to every nested column?
  • What about text after the columns block (out of plugin scope), should the margin be applied there?

While you can come up with some answers to these questions, it seems to be too complicated and against the DokuWiki rules. So for now keep the headings out of columns. — Mykola Ostrovskyy 2008/10/13 8:30

I started using the 2007-10-22 release, now without problems with headings. You can see an example here: Reboucas 2008/10/13 12:54

While you can come up with some answers to these questions…

So your answer is no margin. Works fine with your template but will look not so nice with the default one.

The 2007-10-22 release also has a number of problems and I'm afraid it won't be easy to take best of both. Though, never say never. If more people will ask I might reconsider ;-)Mykola Ostrovskyy 2008/10/13 20:32

If it?s just a question of feedback: Enabling headings would be more as a nice feature. In future versions of DokuWiki you?ll have the same problem. Maybe margins for headings can be overwritten by your CSS. Mainly I think it?s a question of structuring the text optically – so far I think your plugin is very very interesting! — Stefan 2008/12/28

Seconded. No headings is a deal breaker for me. I've started using the 2007 release as well, but it would be nice to have the new syntax and some of the features from columns2. I think headings/margins should function exactly as they do in the 2007 release. — Enki 2009/02/06 15:50

Headings in columns would be really useful, please fix it. — Kolan 2009/02/27 15:14

my 2 cents: also thinking headings are needed within columns — Vipo 2009/03/12 21:44

Okay, I got the message :-)

In principle, the headings should not be supported within any syntax mode except of the baseonly, namely within plugin modes. So what I do here is against the rules, and you can expect some glitches here and there. For instance, I can imagine some compatibility problems with plugins that manipulate the instruction list around section_open and section_close instructions (e.g. Uparrow, Edit Section Reorganizer). Yet, it should behave better than Micheal's original plugin. One manifestation of such “better behavior” is that headings from the columns now show up in the TOC, which you probably will have to disable on default template as it overlaps with the columns. I would appreciate if somebody would suggest better HTML to fix this, but for now this is the best I could do.

Anyway, you got the point: UAYOR. — Mykola Ostrovskyy 2009/03/15 12:17

Nice plugin but could be awesome if you could use it in nested blocks. Thanks for your work :D.

Angelo Anfossi 2008/10/04 23:18

If you mean “columns within columns”, it's implemented in release of 2008-10-08. — Mykola Ostrovskyy 2008/10/08 17:22

Having poked at this for a few minutes, I don't believe what you're doing is ever going to produce the alignments you appear to be attempting to achieve. The default settings you add to the Config (local.php) have no alignment styling, at all, and the outputted HTML reflects this. The 0.5em padding assigned to CSS1, CSS2, and CSS3 are not going to produce actual alignments.

It is certainly possible to achieve real alignments by editing the config and adding either a “textAlign:center”, for instance, or a “text-Align:right”. But then those alignments apply to all tables, throughout the entire wiki site, which is not the implied intent. I think that, to allow alignment to be applied to specific tables and columns, you need another layer of manipulation, which would append the appropriate textAlign property to the default style for the given “CSS” column type.

The basic functionality works nicely (in the latest version, at least), though, so thank you for that — DGM2 2008/09/16 01:32

I believe there is a bit of confusion here. The alignment feature has been added to the branched version (release 2008-09-14). The text-align is added to the table cell style attribute at the rendering time. Though, you seems to be talking about the original version of the plugin (the “current release” link up there). Unfortunately Michael doesn't have time at the moment to support the plugin (hence the branch) and the “current release” link is out of date. — Mykola Ostrovskyy 2008/09/28 23:20

Is it possible to vertically-align content in the columns? Any tips please email me :) laurence dot diver at gmail dot com — Laurence 2008/10/30 14:49

Please dont just mail him, document it here, I need it too – Jan 2009/02/03

Any suggestions for the syntax? The only thing I could come up with so far is to assume that default is top alignment and then use '-' for middle and '_' for bottom.

<columns 100% - -*-* _*->

But this looks too cryptic to me. — Mykola Ostrovskyy 2009/02/06 15:26

Hello all, I just wanted to let people know that some plugins seems to conflict with the default vertical alignment (top) and cause middle vertical alignment. Just modify the plugin's CSS (xxxx/lib/plugins/columns/style.css) by doing something like:

div.dokuwiki table.columns-plugin {
    border: 0;
    border-spacing: 0;
    border-collapse: collapse;
    margin: 0;
    vertical-align: top; /*this is the addition*/

This also appears to affecting printing, so add this line to print.css in your template's directory:

div.dokuwiki table.columns-plugin td { vertical-align: top;}

- TMedWeb 2009/06/29

Thanks for the suggestion but it would be great if you could elaborate a bit more. The very next CSS rule forces the alignment:

div.dokuwiki table.columns-plugin td {
    vertical-align: top;
    padding: 0 0.5em 0 0.5em;

Furthermore, I'm not sure that applying the vertical-align property to the table rather then to the cells makes much sense. But I'm not that great at CSS, so I could be wrong. Is it some kind of compatibility hack? — Mykola Ostrovskyy 2009/07/26 19:38

Style sheet for printing is added in version 2009-08-30. — Mykola Ostrovskyy 2009/08/30 18:26

It works if I put NEWCOL rather than ~~NEWCOL~~ (I got ~~ appearing as text). The default language is pt-br.

Please give me all information from both (the correct and incorrect) variants: What did you put in the configuration dialog? What do you put in the text? Please type the complete line with “$conf['plugin']['columns']['kwnewcol'] = …” from your conf/local.php;

In the text

<columns 100% 50% 15% - >
information in column 1 (50% width)
information in column 2 (15% width)
information in column 3

In the configuration settings, I am going with the default (that is left blank). Check it at Playground.

The same here - NEWCOL works better - ~~ are not displayed. Language is: pl. The settings are default.

There is a small bug in …/columns/lang/en/lang.php - change line 10 from 'NEWCOL' to '~~NEWCOL~~'
Please tell me if the problem is fixed then. You can change it in the preferences too. If you enter ~~NEWCOL~~ it should work, too.
After this you must adjust your pages to the new pattern.

backlinks simply do not work with those links that occur inside a column. The metadata is not updated, the references aren't detected during the rendering, I can't find the way to deal with the problem, did anyone experience this? I am running the latest version of DokuWiki.
Found a bug: when putting links to non-existing pages in one of the columns, the link is red … no problem. But when you now click on it + create the page + go back to the page with the columns … the link remains red. It only turns into the color of a valid pages after editing the page with the columns. I've just tested this on the playground-link provided in the first discussion comment in this page and it's the same there. In other words, not just because of my installation. Is it possible to give this some attention … I plan on using this plugin heavily.

I don't have any idea to fix this. This maybe a problem because I do not understand all of DokuWiki which I use. Any help is welcome. Michael

this is just a caching issue and has nothing to do with the column plugin. Of course, the cache of the column page is not changed if a different (the target) page is edited or created
You'll notice that links on wiki pages are “updated” once a new page was created. To omit that in the column plugin you could use the following in your handler function:
 $renderer->info['cache'] = false; 

Michael Klier 2008/03/13 11:58

Michael, I tried to solve this caching-issue using the way described by you above. Sadly it doesn't work. I tried to add the line in several different ways at several places in the code (although I assume it should be added to the method: <php> function render($mode, &$renderer, $data) </php> before the existing code), but nothing works. Can you maybe explain it a bit more or take a look at the code yourself? — Mischa The Evil 2008/04/16 23:30
Same problem here. In addition, ~~NOCACHE~~ at top of the page doesn't help either.StinkyWinky 2008/05/20 14:26
Please publish your code here (or on your own site), that makes it easier and quicker to review your code without having to go to the trouble of installing the plugin. — Christopher Smith 2008/05/21 11:15
Here is the code … If possible leave a hint using email… this will improve response time… Michael Arlt 2008/06/10 23:39
I would really like to use this plugin more but the cache issue and it having problems outputting properly formatted XHTML is worrisome - Vince 2008/08/21
  • The columns plugin is working unstable with indexmenu. Apache error_log message is shown as following.
[client] PHP Fatal error:  Allowed memory size of 16777216 bytes exhausted (tried to allocate 35 bytes) in /var/www/html/dev/inc/parser/parser.php on line 98, referrer:

After tracing the source code, I guess the error could be from that parser cannot found end tag. Does anyone have workaround solution or patch code?

Jonathan Tsai 2008/07/11 09:26

This is not an error of DokuWiki or the Columns plugin. It is an error caused by the PHP-configuration. Your PHP-setup is limited to use not more then 16MB of memory. This error shows you that the limit has been reached.
See the PHP manual for more info about the related configuration-directive (memory_limit).
Mischa The Evil 2008/07/12 05:21
Actually, the problem is no more appearing after using columns-2008-09-14 branch version. Thanks a lot!
Jonathan Tsai 2008/09/14 22:18

In release 2008-09-14 the backlinks works and the caching issue has gone! Many thanks to Mykola Ostrovskyy! StinkyWinky 2008/09/19 07:59

When using the columns plugin on a page and then exporting the page to pdf, the columns part gets a black line around it. Like a table.

I tried to prevent this by adding the css lines to the dw2pdf\user\user.css but it still renders with a black line..

Does anyone know how to solve this?

Theo-K 2010/09/24 10:36


 * spanish language file
 * @license    GPL 2 (
 * @author     Digna Gonzalez Otero <digna.gonzalezotero [at] gmail [dot] com>
$lang['kwcolumns'] = 'columnas'; // define the wiki syntax keywords
$lang['kwnewcol'] =  'NUEVACOLUMNA';  // define the wiki syntax keywords
//Setup VIM: ex: et ts=4 enc=utf-8 :


 * Spanish language file
 * @license    GPL 2 (
 * @author     Digna Gonzalez Otero <digna.gonzalezotero [at] gmail [dot] com>
$lang['css1'] = 'Atributos CSS de la primera columna';
$lang['css2'] = 'Atributos CSS del resto de las columnas';
$lang['css3'] = 'Atributos CSS de la ultima columna';
$lang['kwcolumns'] = 'Patron de reconocimiento de DokuWiki (por defecto: columnas) - Se debe especificar en la pagina wiki con  &lt;palabra&gt;...&lt;/palabra&gt;';
$lang['kwnewcol']  = 'Patron de nueva columna de DokuWiki (por defecto: ~~NUEVACOLUMNA~~)';
//Setup VIM: ex: et ts=2 enc=utf-8 :

1) The syntax can be made fully compatible with the original version of plugin by un-checking “Wrap the new column tag” check box in the Configuration Settings.
  • wiki/plugins/columns.txt
  • Last modified: 2012/03/29 09:10
  • by