Jarkko's guides
You are here: Home » Web design » DokuWiki for this website

DokuWiki for this website

This page explains why and how this website was based on DokuWiki.

Comparing options

I wanted to make a website with a lot of information and guides including code, commands to execute and tables and liked the look of websites made with Read the Docs, MkDocs and Jekyll. DokuWiki (which I had used before) was not the most obvious choice for this type of website, so I started looking at the mentioned options and similar ones first and found out the following:

Option Type Requires Notes
DokuWiki wiki PHP
Sphinx SSG, code documentation Python Primarily used for Python projects. Has a Read the Docs theme.
MkDocs SSG, Markdown syntax Python Has a Read the Docs theme.
Material SSG Python Sponsorware. A theme for MkDocs that also adds features.
Read the Docs SSG, code documentation Their website & Sphinx or MkDocs It is a commercial hosting platform for software documentation. Your content will be on their domain name. Free version means your website will contain ads. The input can be in Sphinx or MkDocs format.
GitBook CMS, wiki-like syntax Their website It is a commercial hosting platform with their own CMS. Free version means your website will be on domain name gitbook.io. Paid version allows mapping your own domain name to their server.
BookStack WYSIWYG or Markdown PHP, database Pages with information are grouped in books.
Jekyll SSG, Markdown Ruby Powers the GitHub pages.
Docusaurus SSG node.js
VitePress SSG, Markdown node.js
Wiki.js wiki, Markdown node.js, database
Docsify Renders Markdown live node.js

All options use a wiki-like syntax for the content, which means that writing the content is quick and easy and exactly what I was looking for. Many of the options are Static Site Generators (SSG), which means that you run a tool to generate the website from source documents. What made me hesitant about most options is what they need to run. The web hosting package I've been using for many years only supports Apache as web server, PHP and MySQL as database. I would need to upgrade my subscription (and pay more) to get node.js as web server and support for Python. It would be possible to run Python (to regenerate the website) on my local computer and then upload it to my web host, but that's at least somewhat inconvenient.

This made me take a second look at DokuWiki and I found out there is a Read the Docs theme/template for DokuWiki as well (see below). After finding that out, I was surprised how quickly I could find a suitable set of plugins to extend the rather limiting base functionality of DokuWiki to get all the features I was looking for. In the end I was very happy with the result and it can run on a tradition Apache web server with only PHP support.

How to use DokuWiki

Of course you need to read the documentation to learn how to use it. The following points still took a little while to figure out though.

  1. After logging out for first time, I wasn't sure how I could log back in. There is no login button on the website. You can log back in by adding ?do=login to the URL where your DokuWiki is available: https://www.your_domain_name.com/dokuwiki/?do=login
  2. The second point was how to create content for the sidebar. To create a sidebar for the home page you simply need to create a page called sidebar. The documentation for the readthedokus template explains what content in the sidebar is supported by that theme.
  3. I've split up my website in multiple sections, which is possible with the namespace feature of DokuWiki. You can have a separate sidebar per namespace by creating pages called name_of_the_namespace:sidebar.

Template

I installed the readthedokus template to replicate the style of Read the Docs.

Nice URLs

It is possible to change this default URL style of DokuWiki:

https://www.jarkko.nl/dokuwiki/doku.php?id=linux:history

into this much nicer style, which is also better for search engines:

https://www.jarkko.nl/dokuwiki/linux/history

A slash is put in between the namespace and page names. This method is specific for Apache, so will only work if you're using Apache as web server. Go to where DokuWiki is installed. Copy or rename .htaccess.dist to .htaccess and uncomment the following lines.

Options -Indexes -MultiViews +FollowSymLinks

RewriteEngine on

RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1  [QSA,L]
RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]
RewriteRule ^$                        doku.php  [L]
RewriteCond %{REQUEST_FILENAME}       !-f
RewriteCond %{REQUEST_FILENAME}       !-d
RewriteRule (.*)                      doku.php?id=$1  [QSA,L]
RewriteRule ^index.php$               doku.php

After this you need to change two configuration settings (userewrite=.htaccess and useslash=enabled) as listed below.

Disabling anonymous editing

I don't mean to make this website publicly modifiable like Wikipedia, so I wanted to disable editing by others and only allow editing by myself (after having logged in).

  • Log in on your DokuWiki site as admin.
  • Go to the Admin page, then to Access Control List Management.
  • Select [root] in the menu on the left.
  • To the right of “Permissions for” select “@ALL” from the drop-down menu.
  • Then under “Modify Entry” select “Read” and click the Update button.
  • To the right of “Permissions for” select “@user” from the drop-down menu.
  • Then under “Modify Entry” select “Delete” (meaning permission to do anything) and click the Update button.

Installed plugins

I installed the following plugins (under Admin ⇒ Extension manager on the DokuWiki site) to give me all the functionality I wanted.

  • CodePrism Plugin: To show code and commands in a nicely formatted way.
  • DataTables Plugin: To create tables that are sortable (by clicking on a column's header).
  • fontawesome plugin: To insert icons from Font Awesome.
  • Move plugin: Adds the option to rename a page at the bottom (while editing pages). All links to the page will then be updated automatically.
  • PopUpViewer: Lightbox for images. When the image is clicked a full-scale / zoomed-in version is shown in the center of the browser and the rest of the browser window is darkened. By clicking anywhere beside the image it is closed again to return to the website.
  • Wrap Plugin: To create tips, notes and other boxes. The readthedokus template in combination with this plugin allows making them in the same style as on Read the Docs.
  • Columns: To create multiple columns.
  • BlockQuote: For boxes with quotes.
  • keyboard: To show keyboard keys in boxes.
  • Mermaid: To draw diagrams with a Wiki-like syntax
  • wavedrom: To draw waveforms in a Wiki-like syntax
  • MathJax: For formulas in LaTeX syntax
  • Description: To put the first paragraph in the header tag “description” (for search engines)

Changed configuration

I changed the following under Admin ⇒ Configuration Settings:

  • Basic, template: readthedokus
  • Display, breadcrumbs: 0 (disable showing history of visited pages)
  • Display, youarehere: enabled (instead show hierarchy of current page)
  • Display, useheading: Always (use first header as page title)
  • Display, hidepages: filled in a regular expression to hide certain pages from the search function (in the sidebar) and sitemap (for search engines)
  • Advanced, userewrite: .htaccess (for the Apache web server)
  • Advanced, useslash: enabled
  • Authentication, disable actions: Register. That prevents spam bots from creating user accounts and pages on the wiki.
  • Links, target»extern: _blank (open links to other websites in a new tab)
  • Codeprism, theme: tomorrow
  • Codeprism, show-invis: disabled
  • Codeprism, hl-brace: disabled
  • Wrap, noPrefix: tabs, group, admonition, danger, caution, note, tip
  • Readthedokus, dokuwikibreadcrumbs_enable = enabled (show path of current page at the top)
  • Readthedokus, fontawesome_enable: enabled
  • Readthedokus, fontawesome_tag:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css">

  • Readthedokus, googlefont_enable: enabled
  • Readthedokus, googlefont_tag1):

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,100;0,300;0,400;0,700;0,900;1,100;1,300;1,400;1,700;1,900&family=Roboto+Slab:wght@100..900&display=swap" rel="stylesheet">

A few options (such as userewrite) can cause the website to not load anymore. That means you won't be able to access your website anymore to go to Admin ⇒ Configuration Settings to fix it. You can fix that situation by editing file conf/local.php where you installed DokuWiki. That file contains all configuration settings you've changed.

Added fixed elements

The readthedokus template allows for several locations on the website to contain a fixed HTML file. See the template's documentation.

I've created file lib/tpl/readthedokus/sidebarheader.html to show a logo at the top of the sidebar and lib/tpl/readthedokus/pagefooter.html to show an overview of all topics on this website at the bottom of each page.

Include namespace in title

With the configuration settings above, the HTML title will be the first header of the page. What I like to also include in the title is the name of the namespace (if any). I've added the following PHP code to the HTML “title” tag in dokuwiki/lib/tpl/readthedokus/main.php (before the existing code to generate the title). It uses the first header of the first page in the namespace as the name for the namespace.

<?php
$namespace_title = p_get_first_heading(tpl_getparent($ID), METADATA_DONT_RENDER);
if ($namespace_title && $namespace_title!="Home") echo $namespace_title.": ";
?>

Added favicon

I added these files, which are used as favicon by template readthedokus:

  • /dokuwiki/lib/tpl/readthedokus/images/favicon.ico
  • /dokuwiki/lib/tpl/readthedokus/images/apple-touch-icon.png

CSS tweaks

I've added the following to conf/userall.css where DokuWiki is installed to tweak the layout. You can find out the class and/or ID of the component you want to change the CSS for by opening the Developer Tools / DevTools in your browser (which is available in Edge, Chrome and Firefox) with ctrl+shift+i.

// By default there is no vertical space between footnotes and the previous/next buttons.
.footnotes {
    margin-bottom: 20px !important;
}

// For CodePrism blocks that show a command: change [user@host]$ into just $.
.command-line-prompt>span[data-user]:before {
    // It was: content: "[" attr(data-user) "@" attr(data-host) "] $";
    content: "$" !important;
}

// For CodePrism blocks: Adjust the position of the copy button.
div.code-toolbar>.toolbar>.toolbar-item {
    padding-right: 20px !important;
}

// I want to put icons in front of some links in the sidebar. That will cause a 
// line break between the icon and text though. This change keeps both on a single line.
#dokuwiki__aside #sidebar ul li a {
    // It was: display: block
    display: inline-block !important;
}

// Adding a new box style: <WRAP admonition my_download>
.admonition.wrap_my_download:before {
    content: '\f063\00a0 Downloads'; // arrow down from font awesome
}
.admonition.wrap_my_download:before {
    background-color: #6ab0de; // blue from "note"
}
.admonition.wrap_my_download {
    background-color: #e7f2fa; // blue from "note"
}

// For <WRAP round box>: boxes with gray background
.wrap_box {
    padding-bottom: 0 !important;
    background: #D9DCDD !important; // was #edf0f2
}

I commented out the following in lib/tpl/dokuwiki/css to disable having bold text for links to the current page:

//.dokuwiki span.curid a {
//    font-weight: bold;
//}

Other tweaks

1) To allow uploading any file type (not just images) to your DokuWiki site: edit inc/media.php and comment out the following code:

if (!preg_match('/\.(' . $regex . ')$/i', $fn)) {
  return [$lang['uploadwrong'], -1];
}

2) Tweak for PopUpViewer: By default it shows a white glow around the image when zoomed in. I removed the white glow with the following change in lib/plugins/popupviewer/style.css:

.popupviewerContentStyle() {
    // I commented out: box-shadow: 0.2em 0.2em 3em rgba(255, 255, 255, 0.4);
    border-radius: 6px;
}

3) Tweak for CodePrism: I don't want a button in the top right showing the programming language. It can be removed by commenting out this line in lib/plugins/codeprism/action.php:

$scripts = array(
  'prism.js',
  'plugins/autoloader/prism-autoloader.min.js',
  'components/prism-core.min.js',
  'plugins/line-numbers/prism-line-numbers.min.js',
  'plugins/line-highlight/prism-line-highlight.min.js',
  'plugins/toolbar/prism-toolbar.min.js',
  'plugins/copy-to-clipboard/prism-copy-to-clipboard.js',
  // I commented out: 'plugins/show-language/prism-show-language.min.js',
  'plugins/command-line/prism-command-line.min.js',
  'plugins/file-highlight/prism-file-highlight.min.js'
);

4) Created file conf/acronyms.local.conf to add my own acronym explanations. They get underlined on the site and an explanation is shown as a tooltip when the mouse is hovering over it. See https://www.dokuwiki.org/abbreviations for more information.

1)
I got this HTML code from https://fonts.google.com by looking up fonts Roboto Slab and Lato and using the “Get embed code” button. Those are the fonts that are used by the readthedokus template.
Previous Next

ALL THE TOPICS ON THIS WEBSITE:

Linux

Raspberry Pi

Digital room correction

Web design

By Jarkko Huijts
Jarkko's guides

Table of Contents

Table of Contents

  • DokuWiki for this website
    • Comparing options
    • How to use DokuWiki
    • Template
    • Nice URLs
    • Disabling anonymous editing
    • Installed plugins
    • Changed configuration
    • Added fixed elements
    • Include namespace in title
    • Added favicon
    • CSS tweaks
    • Other tweaks

WEB DESIGN

  • Topics
  • DokuWiki
  • Useful tools

AVAILABLE TOPICS

  • Linux
  • Raspberry Pi
  • Digital room correction
  • Web design