Compatible with DokuWiki
Similar to wrap
This is a reworked and extension version of the original plugin developed by Michael Arlt.
The plugin allows to organize Wiki page contents into multiple columns using manually inserted column breaks. Width of the columns and text alignment within them are fully configurable. For creation of complex layouts, sections of columns can be nested one into another.
The minimal syntax is simply add two lines around your information and enter your column breaks.
<columns 100% 50% - -> First column text (50% width). <newcolumn> Second column text. <newcolumn> Third column text. </columns>
The first attribute of the
<columns> tag is the width of the column set. The following attributes are for the columns. If you do not want to specify a value for the table- or column-width use “
The column breaks are specified with
<newcolumn> tag, which may also take optional attributes described below. In the original plugin the breaks were specified with
~~NEWCOL~~ and for compatibility reasons it is still possible to configure the plugin to use this tag, but some of the newer features will be disabled.
Apart from the width, each column may have a number of additional attributes that specify formatting of the column contents. These attributes should be specified in front of the column width:
<columns 100% first column attributes 50% second column attributes -> First column text. <newcolumn> Second column text. </columns>
With these 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%> First column text. <newcolumn second column 25% attributes> Second column text. <newcolumn> Third column text. </columns>
By default the text in the columns is justified but alignment for each column can be specified explicitly. There are few ways to so. The most simple one is 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%* *-* *-> First column with justified text. <newcolumn> Second column is aligned on the left side. <newcolumn> Third column is center-aligned. <newcolumn> Fourth column is aligned on the right side. </columns>
Alternatively the alignment can be specified with separate attributes. This approach allows to define both horizontal and vertical alignment. There are four attributes for horizontal alignment (
justify) and three for the vertical (
bottom). There may be multiple alignment attributes per column:
<columns 100% left 50% right bottom -> First column is aligned on the left side. <newcolumn> Second column is aligned to the right-bottom corner. </columns>
All attributes can be abbreviated to the first letter, the single letter attributes may be merged together:
<columns 100% l 50%> First column is aligned on the left side. <newcolumn rb> Second column is aligned to the right-bottom corner. <newcolumn m *-*> Simple alignment syntax is still supported. Contents of the third column is centered both ways. </columns>
The headings within column sets are specified the using the standard DokuWiki syntax:
<columns 100% 50% -> ===== Heading ===== Content of the first column. <newcolumn> Content of the second column. </columns>
By default plugin puts the content within a column without explicitly specifying the section level. This works fine when the entire column set belongs to a single section but can produce unexpected results when the headings are used within the set:
====== Level 1 Heading ====== <columns 100% 50% -> Implicit level 1 content. ===== Level 2 Headline 1 ===== Level 2 content. <newcolumn> Implicit level 1 content that should be in level 2 section. ===== Level 2 Headline 2 ===== Level 2 content. </columns>
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. </columns>
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:
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.
The plugin adds a section to DokuWiki configuration page. There are three settings that can be configured:
plugin.columns.kwcolumns— Name of the columns section tag. Default value depends on the Wiki language.
plugin.columns.kwnewcol— Name of the new column tag. Default value depends on the Wiki language.
plugin.columns.wrapnewcol— A flag indicating if the new column tag is wrapped into angle brackets. The flag is checked by default. By un-checking it you can make the plugin syntax fully compatible with the original version of plugin but you will loose number of advanced features.
The plugin wraps contents of the columns set into an HTML table. This results in a number of limitations:
In principle, the headings should not be supported within any syntax mode except of the
baseonly, namely within plugin modes. So what the plugin does 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_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 column sets show up in the TOC.
The following work in combination with editsections2:
===== HeadlineP ===== text corresponding to the previous part of the page (not displayed as columns) <columns> random character (not space) ===== Headline1 ===== text corresponding to headline 1 <new column> random character (not space) ===== Headline2 ===== text corresponding to headline 2 <new column> random character (not space) ===== Headline3 ===== text corresponding to headline 3 </columns> random character (not space) ===== HeadlineR ===== text corresponding to the remaining of the page (not displayed as columns)
The EDIT buttons are then displayed correctly at the beginning of each column and corresponding sections. (using
. as random character) may minimize the “scar” left using this workaround
<columns> … <newcolumn> … </columns>)
Please report bugs or feature requests at the https://github.com/dwp-forge/columns/issues.