Intro

I've been re-doing my own personal docs recently and figured this might also be useful to be used as a drop in replacement for the existing Hacman docs we're using at the moment. The main motivation is something that's easier to edit rather than github pull requests. If it's ok then we might be able to shift this demo across to being hosted on the main hacman site under a subdomain such as wiki.hacman.org.uk.

The demo is located here with more details about the setup and plugins:

It's basically dokuwiki, but with a commonmark plugin so that the syntax is markdown instead of the native dokuwiki syntax. This means all the existing docs don't need to be re-written just copied / pasted across. Markdown is the same language used on github and our discourse mailing list, it's a more modern easier to remember syntax.

The theme is currently set to bootswatch slate, with some custom CSS tweaks for some of the colors. Admittedly it's a bit old since it's bootstrap 3 compared to bootstrap 5 but it works fairly well. Potentially we could switch it out for one of the other themes here:

• https://bootswatch.com/3/

There's actually two editors that can be used for changing / editing pages. The first is the native dokuwiki editor which you get when clicking the edit button here.

This first editor actually works quite well since markdown and dokuwiki syntax has a lot of commonality. I've tried to hide any buttons along the top that don't work with markdown however. If you click the green buttomn while inside that editor, a different more markdown orientated editor will show up with live preview

The red buttons are plugins that insert syntax such as alert boxes etc. But in order for them to work they need to be code fenced inside a dokuwiki code block

Such as:

```dokuwiki
<WRAP center round alert 60%>
DEMO ONLY please don't put anything here that you want to keep 
</WRAP>
```

The reason for this is because we're replacing the default dokuwiki syntax with markdown as a default and some plugins are not aware of this.

Currently this is setup to use local authentication. It's got a captcha and email verification enabled to try and avoid spam. Integrating with the existing hacman auth may be possible but it might require enabling OAuth on the existing hacman site.

Dokuwiki doesn't require a database, all storage is done via local text files. We can also enable a plugin called gitbacked which will keep the content in sync with a github repo. One thing to be aware of is that the file extension will be .txt and not .md in the github backup however.

There's a bunch of plugins enabled for special formatting. Some of these work just as is, some need to be inside a dokuwiki code fence as mentioned above. There's QRCodes, Bootstrap controls such as jumbotrons a draw.io plugin for creating flow diagrams etc and more besides.