DokuWiki for this website

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

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:

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.

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.

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

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.

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.

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)

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)
• Anti-Spam: indexdelay: 0 (Prevents that the HTML of recently modified pages contains “noindex”, which prevents Google from indexing the page.)
• 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_tag¹⁾:

<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">

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.

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.": ";
?>

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

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;
}

// The left sidebar is composed of 3 divs. I'm not using the last div (id="sidebarfooter"),
// so I reduce the padding at the bottom of the 2nd div (listing all the pages).
#dokuwiki__aside { 
  padding-bottom: 10px !important; // was: 2em
}

// Show a vertical scrollbar for the 2nd div for the sidebar, but only if the contents
// does not fit on the screen. Give the scrollbar custom colors that match the sidebar.
#dokuwiki__aside .aside { 
  scrollbar-width: auto !important;
  display: flex;
  flex-direction: column;
}

#dokuwiki__aside #sidebar {
  overflow-y: auto;
  overflow-x: hidden;
  scrollbar-color:  #2980B9 #343131;
}

// 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;
//}

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.