echo get_bloginfo('name', 'display')
Seen a nice WordPress theme you wish was available as a DokuWiki template? Need a wiki alongside your company's blog in the same style? This tutorial will walk you through all the necessary steps to convert a WordPress (WP) theme to a DokuWiki (DW) template.
Follow the first 3 steps on the general template tutorial: Getting started (i.e. copy the Starter template). The rest of this tutorial will explain how to do the 4th step.
Commit already to be able to see differences later.
Copy any relevant meta elements (anything between <head></head>
) from WP's header.php
which DokuWiki doesn't already provide into DW's main.php
.
Check if the WP theme adds anything to the body classes via add_filter( 'body_class', [...] );
. If yes, add them to the element which includes the tpl_classes()
. In case that element is not the body
and the CSS contains any body selectors with such classes (body.
), you would either need to move the tpl_classes()
into the body
or change the CSS accordingly (e.g. by just removing the body.
in such cases).
Copy anything between WP's <body>
and its header in header.php
to DW's main.php
between the <body>
and the start of the HEADER section. Don't overwrite DW's functions there but merge them into the code from WP.
Make sure every element is closed properly at the bottom (or removed at the bottom if you removed any element).
Copy the code for the header from WP's header.php
into DW's HEADER section in main.php
. Substitute WP functions with DW functions and delete the code for the DW header (except for the breadcrumbs, copy that code somewhere else to re-use later).
You can also extract that code into its own file and include it there instead.
Copy the start of the content main area from the end of WP's header.php
, the beginning and end of index.php
into the CONTENT aread in main.php
and close everything like in the beginning of footer.php
.
The only thing essential to keep is <?php tpl_content() ?>
for the actual content.
Copy most of WP's footer.php
into DW's FOOTER section. Keep at least DW's tpl_pageinfo()
and tpl_license()
. Adding a link back to dokuwiki.org would be nice.
Templates usually have 0, 1 or 2 sidebars. When a template has a sidebar, it can be optional or permanent. Even if the original WP theme doesn't have a sidebar, you should consider adding one anyway. And if the original WP theme has a permanent sidebar, you should consider making it optional.
DW has a core setting ($conf['sidebar']
) which every template with a sidebar should use to determine a) if to show a sidebar and b) which page should be included for the sidebar content.
The way sidebars are usually done in DW are not exactly equivalent with how they are done and how they behave in WP. You could implement your own way of dealing with sidebars but the DW way should be fine for most circumstances. With tpl_include_page() you can include the content of the “nearest” page with the name you pass through to it:
<?php tpl_include_page($conf['sidebar'], 1, 1) ?>
Because the functionality is different from WP's usual sidebar, most “widgets” will be implemented with plugins rather than in the template. Therefore, most of the widget CSS can be safely deleted.
Most of the above will require you to change WP-specific functions to DW-specific functions. These are usually within <?php ?>
blocks.
What | WordPress | DokuWiki | Notes |
---|---|---|---|
wiki/blog title | bloginfo('name') | echo $conf['title'] | |
tagline | bloginfo('description') | echo $conf['tagline'] | |
link to home page | echo home_url('/') | echo wl() | |
body classes | body_class() | echo tpl_classes() | but the DW version doesn't need to be on the body |
language strings | _e('Skip to content', '<tpl>') | echo $lang['skip_to_content'] | DW: core string; WP: template string |
_e('Sidebar', '<tpl>') | echo $lang['sidebar'] | DW: core string; WP: template string | |
_e('Menu', '<tpl>') | echo tpl_getLang('menu') | DW: template string; WP: template string | |
sidebar | get_sidebar() | tpl_include_page($conf['sidebar'], 1, 1) | not exact equivalent |
navigation | if(has_nav_menu('primary')){ wp_nav_menu([...]); } | if (page_findnearest('nav')){ tpl_include_page('nav', 1, 1); } | not exact equivalent |
Logo in WP:
<?php $header_image = get_header_image(); ?> <?php if (!empty( $header_image )): ?> <img src="<?php header_image() ?>" width="<?php echo get_custom_header()->width ?>" height="<?php echo get_custom_header()->height ?>" alt="" /> <?php endif; ?>
Logo in DW:
<?php $logoSize = array(); $logo = tpl_getMediaFile(array(':wiki:logo.png', ':logo.png', 'images/logo.png'), false, $logoSize); echo '<img src="'.$logo.'" '.$logoSize[3].' alt="" />'; ?>
Whenever the core $lang
(in inc/lang/en/lang.php) already contains a language string you need, you can simply use $lang['foo']
. But if you need any other language string, you need to add your lang/en/lang.php
file to your template. Then you can use any string in there with tpl_getLang('bar')
.
Copy WP's style.css
to DW's css/style.less
(use the .less
extension to take advantage of LESS, a CSS pre-processor) and add it to the style.ini
.
css/style.less = screen
If style.less
contains any @media queries, you need to either change the screen
media type to all
.
css/style.less = all
Or you can extract the @media queries into separate CSS files and add them to the style.ini
with the all
media type.
It is advisable but not necessary to split the original CSS file into separate files to ease maintenance. Each of those will need to be added to the style.ini
.
Check what you might need from the previously existing CSS files and copy what you need into your own files and delete the original ones, including removing their lines in style.ini
.
Copy WP's rtl.css
over as rtl.less
and add it to the style.ini
. DW implements styles for RTL scripts differently than WP, that's why you need to adjust rtl.less
to be surrounded by
[dir=rtl] { /* here is the content */ } /* /rtl */
If the rtl.less
includes @media
queries, the file needs to be added with the all
media type and the [dir=rtl] {}
needs to be added around each block inside the @media query, e.g.
@media only screen and (max-width: 767px) { [dir=rtl] { /* the CSS */ } }
You will potentially need to add to this file later…
Move the print section from the original style.css
into print.less
. Remove the @media print {}
around the styles and add it to style.ini
as well:
css/print.less = print
Adjust all paths (to images, fonts, etc) to be relative to the template's root. E.g. if you have images in an “images” folder, your paths should be like url(images/foo.png)
.
Copy all relevant JS (not including JS meant for the admin screens) to a DW subfolder. Add a script.js
in the template's root folder and add all the copied JS files with the include syntax, e.g.
/* DOKUWIKI:include js/foo.js */ /* DOKUWIKI:include js/bar.js */
If the theme's JS is only based on jQuery (and/or jQuery-UI), you don't need to do anything more. But some themes use other libraries which would need to be copied over from WP's wp-includes/js/
folder as well. Check your theme's functions.php
for any wp_enqueue_script()
s which have a third parameter ($deps
= dependencies) with anything else but an empty array()
or array('jquery')
in it.
DW has two more layout files. While main.php
is, well, the main layout file, there is also mediamanager.php
for the popup media manager and detail.php
for the image detail page.
The media manager popup layout is pretty well defined and cannot change much. So you would only need to potentially change some meta elements and some site containers. This might require a bit more work, manually fixing potential issues.
You have more freedom with the image detail page. You can either move your whole layout into that file (including header and sidebar, etc) or create a different, minimal layout.
DokuWiki has certain things WordPress doesn't have. You need to decide on a template by template basis where to put those, how to style them and what to do with them:
Following all the tool links will also make possible to check all the other modes and fix potential issues. This needs to be done on a template by template basis as the issues are difficult to predict.
Concentrate first on the modes most users are likely to see most, i.e. edit, search, login,… Something like the admin section on the other hand doesn't need to be pretty but it should at least be workable.
Get all the different colour values of the theme (there are some browser plugins which can do that for you, so you don't need to peruse the code yourself) and change the “guaranteed dokuwiki color placeholders” in the style.ini
to them. If you have less colours available, either leave the existing ones (they are usually universal enough) or try to make up some sensible colour alternatives. All the “guaranteed” values need to exist.
If you have more than those colours, you should make up your own entries (with __variable_name_color__
) below the guaranteed ones for the rest of them.
When you have all your colours defined, you need to substitute them in all your CSS files. Just search and replace each colour value with @ini_variable_name_color
.
Example:
If you have this in your style.ini
__theme_color__ = "#123456"
You need to substitute each #123456
with @ini_theme_color
.
If the WP theme comes with several CSS files for various colour schemes, you can delete them completely as you don't need them anymore. Any important colour changes can be done with simple changes in the style.ini.
You can have other values than colours as a style.ini placeholder. Anything you'd like to be configurable which has to do with CSS can be driven by this. E.g. set the template width or responsive breakpoints or fonts or font sizes or a background image or drive various sub themes with a variable…
There are certain functionalities which both DW and WP have but which are expressed in different class names.
What | WordPress | DokuWiki |
---|---|---|
hide something accessibly | screen-reader-text | a11y |
clearing floats | clear | group |
align media left | alignleft | medialeft |
align media right | alignright | mediaright |
align media centred | aligncenter | mediacenter |
menu item with children | li.menu-item-has-children | li.node |
selected menu item | li.current_page_item|current-menu-item | li .curid |
parent(s) of selected menu item | li.current_page_ancestor + li.current_page_parent | (n/a) |
There are several ways to fix this.
If you need or want to keep your styles closer to the WP (e.g. so that it's easier to update upstream changes), you should use “the lazy way”. If you need or want to keep the CSS smaller and make maintainability easier, you should use “the clean way”.
When you cannot change the class DW gives you (media alignment and menu classes), let the class from DW inherit the one from WP. This is possible with the power of LESS.
.class-from-dw { .class-from-wp; }
This might not always work 100% as sometimes you have to cater for different child elements/classes.
When you don't need to use the DW classes (a11y
and group
), you can ignore them and keep the WP styles. But if the WP styles are adding anything which the DW styles don't have, you can let the class from WP inherit the one from DW (so, the other way around as the example above).
.class-from-wp { .class-from-dw; }
You can also just search for all WP classes and replace them with the DW classes in both HTML/PHP and CSS/LESS. That might also not work 100% as you might need to fix other selectors (especially in menus). But the amount of possibly necessary fixes will be the same in both ways.
To avoid conflicts with automatically created IDs you should rename all IDs. Best just include <template-name>__
in front of every ID (inside HTML, CSS and JS).
Due to the power of the style.ini you don't need to do anything to support custom colours, they are already supported!
You can prepare a custom background image in the CSS but without adding the actual image. Then add this to your template's main.php:
... style="background-image: url(<?php echo tpl_getMediaFile(array(':wiki:background.png', ':background.png', 'images/background.png') ?>); );" ...
This way users can (similarly to the logo) upload their own background images via the wiki's media manager, as long as they are called background.png
.
Add more…
echo get_bloginfo('name', 'display')