How to create a DokuWiki based blog (BlogTNG plugin)

Using DokuWiki is fun. It gives you all you need to manage different types of content like common text, quotes, files, data tables and source code. It displays your content in a proper way, including typography replacements and many other features (see Syntax for some examples). It is especially perfect to write about IT where console output or code snippets matter. You can even include RSS feeds and create galleries with a single line of text. Additionally, DokuWiki is very easy to administrate and maintain (this is my personal killer feature). Installing updates is damn simple (in principle, you just have to copy the new files over the old ones). And you can do backups by downloading everything from your webserver. No database dumps and stuff needed. Because plain text files are used as storage, you can even access the raw data offline with a simple text editor.¹⁾ So why not using DokuWiki as easy maintainable blog? Exactly!

There are two common ways to create a DokuWiki based weblog. The traditional one, using the Blog plugin in combination with a bunch of others.²⁾ And the new BlogTNG plugin which is meant as successor of the Blog plugin and already contains components like comments and tags. The following text is about creating a cool WikiBlog with BlogTNG.

You need an up to date DokuWiki with BlogTNG plugin (surprise). If you stuck on an older DokuWiki version, upgrade to the latest stable release or use a fresh installation. Optional but recommended plugins are Captcha (BlogTNG automatically detects and protects the comments with it), Video Share and Gallery.

Because DokuWiki's installation procedure is pretty straightforward (upload, fill out one form, done) and each plugin can be installed with an URL and single click at the plugin manager, I recommend to try everything out on a separate test installation before using it in a productive environment.

BlogTNG is organising all blog postings in “blog” data groups. Expressed in simplified terms, these blogs are just categories to control which of your DokuWiki pages are postings of a blog and which are just normal wiki pages. After one or more wiki pages are assigned to a blog, you can get the typical blog post listing wherever you want by using a special <blog list> syntax. It tells DokuWiki “please show the newest x pages which are belonging to the blog foobar here”. This sounds complicated but it is easier than you might think.

I'll give you an example you may follow on your own installation. Imagine a fully working DokuWiki with BlogTNG plugin at http://example.com/. We are going to create three new blog postings now:

1. Hello world
2. Second try
3. Third time is a charm

You can create them like every other wiki page. Just call http://example.com/doku.php?id=hello_world³⁾ and click on the “Create this page” button to open the page creation menu for the first post. Fill it with content and then have a look at the additional control elements below the textarea before you save the page.

You can choose if the Wiki page shall belong to a blog by using the “Blog” selection box. Choose default⁴⁾ and store the page. Do the same with http://example.com/doku.php?id=second_try and http://example.com/doku.php?id=third_time_is_a_charm.

Now you have three blog postings for the default blog. But how to get them listed on the http://example.com/ homepage? This is where the <blog list> and <blog pagination> syntax comes into play. Edit the start page and insert the following:

<blog list>
  blog   default
  tpl    default
  limit  2
  sortby created
  cache  0
</blog>

<blog pagination>
  blog   default
  limit  2
</blog>

The <blog list> options are telling DokuWiki to list the two⁵⁾ newest⁶⁾ wiki pages which are assigned to the default blog.⁷⁾ <blog pagination> inserts a default blog page navigation if there are more postings for the blog than defined by the limit option (therefore you should use the same limit values for both <blog list> and <blog pagination>). Has the penny dropped? I hope so . Just experiment by adding more postings to your blog (or remove them by adjusting the “Blog” selection box to the empty value).

Now a few words about the so called BlogTNG templates. The name might be a little bit confusing because these BlogTNG templates have nothing to do with common DokuWiki templates. A BlogTNG template is a set of files in /lib/plugins/blogtng/tpl/<template-name>/. These files provide some markup for the different BlogTNG functions (just like DokuWiki templates provide the markup frame for the general wiki layout). But a new /lib/plugins/blogtng/tpl/<template-name>/entry.php file also triggers the creation of a new <template-name> blog. I'll give you an example: If you copy the existing /lib/plugins/blogtng/tpl/default/ directory to /lib/plugins/blogtng/tpl/foobar/ you can choose between the blogs default and foobar at the blog selection box when creating or editing a wiki page. By using this feature, you can even create multiple blogs on the same DokuWiki installation. For example, just use <blog list|pagination> to list all default postings on http://example.com/default and all foobar postings on http://example.com/foobar. All you have to do is to control which postings are shown on the pages by adjusting the blog and tpl options.

Please note that there are also other <blog *> syntax commands (to create tag clouds, a recent comments listing etc.). So read the plugin documentation to learn more about.

• You may find the following resources useful if you want to customize your blog:
  • My mnml-blog template (even if you are not going to use it, it may help you to create your own).
  • The text “How to create an easily maintainable DokuWiki template”
• Use the ~~READMORE~~ makro if you want to prevent displaying the whole content of long postings via <blog list>. Just insert it where a “Read more…” link shall appear. I note this because the current BlogTNG documentation is relatively spare.
• DokuWiki creates a blog RSS feed for you. You can find it at feed.php?mode=blogtng&blog=<blogname> (just replace <blogname> with your blog, e.g. default). I recommend to use the URL with Feedburner to relieve your webserver from load and to prevent loosing readers if your DokuWiki feed URL changes some day.
• You may use the Include plugin to show the content of pages with <blog *> syntax commands at other places.
• Unlike DokuWiki itself, BlogTNG is using a SQLite database for its metadata and comments. But don't worry, this makes the DokuWiki administration and backup not complicated. SQLite is bundled with PHP 5 and enabled by default. The database itself is just a blogtng.sqlite file at DokuWikis meta data directory and therefore you can still backup everything by simply downloading it.
• The blogtng.sqlite file is currently a SQLite 2 database. Many recent SQLite GUI tools do not support SQLite version below 3.x. If you have to edit the database by hand (for whatever reason), you can use the older SQLite Database Browser 1.1.
• Watch out for BlogTNG plugin updates at regular intervals because it is still declared as “in development”. And please open an issue and/or send patches to the developers if you find a bug.