Combining Twig and DokuWiki

DokuWiki comes with a simple but functional template (aka design, theme, skin) that can easily be customized to some minor degree using the pre-installed style manager plugin. If you want things to look a bit more fancy you can install one of the many third-party templates. The bootstrap3 template by Giuseppe Di Terlizzi seems to be especially popular recently. 

However for maximum customization you will want to create your own template (or hire someone to do it for you). 

The recommended way to create a new template is using the starter template by Anika Henke. It served as the basis for the default dokuwiki template and is meant to be used as the basis for other templates as well. It basically is a very bare bones template with a simple layout and basic styling that is ready to be customized:

However as an experienced DokuWiki developer, I always felt it was doing too much already. So for the templates I made over the years (either for personal or commercial endeavors at my day job) I usually opted for simply referencing the base styles from the default template directly and do the rest from scratch.

Another thing that started to bother me was DokuWiki's very simplistic approach of "PHP already is a templating language". While that of course is true, I grew quite fond of the Twig templating engine over the last years and started to miss it when working with DokuWiki.

So when the urge to redesign my personal homepage finally overcame me a few days ago, I decided to see if I could combine DokuWiki, Twig and a style inheritance based approach. The result is the TwigStarter template.

TwigStarter provides the Twig language to templates and an easy way to access DokuWiki functions, classes and mechanisms from within Twig.

To be honest, the Twig integration doesn't really give huge advantages over the traditional plain PHP approach. It is mostly a matter of personal preference - the code looks just a little nicer without the constant HTML/PHP context switches.

One advantage though is the mechanism of extending base templates. TwigStarter uses a single layout.twig file that gets extended for the main and detail views.

The way that TwigStarter looks for twig templates makes it easy to create "child" themes of it. Twig templates not found in the current theme will be looked up directly in TwigStarter, so you could get away with only overwriting the layout.twig and not redefine the rest of the templates. In practice you probably want to tweak at least the main view as well.

When you create a new child theme, you should copy over the TwigStarter style.ini, it includes all the basic styles from the dokuwiki template, so you don't need to bother styling all the wiki specific things. Instead you only add your own style files afterwards. 

The above diagram (full size) gives a you an approximate overview on how template and style loading works when you use a child theme of TwigStarter:

  • Style loading is pretty much standard and controlled by your own style.ini - however the base styles are references from the default dokuwiki template and customized by your own. TwigStarter itself defines absolutely no styles on it's own.
  • The three template PHP files that DokuWiki expects, simply instantiate the TwigStarter TemplateController which then loads the appropriate Twig templates
  • Twig templates not found directly in your own template are looked up and loaded from the TwigStarter Template
  • Of course this is still an oversimplified view, a real template would have additional twig includes, image resources and other files...

TwigStarter is a very opinionated approach on creating a DokuWiki template. Inexperienced template developers will probably still be better of with the starter template (it contains a lot of comments explaining how things work). With TwigStarter you're more on your own.