I’ve put together a possible replacement for the existing docs.hacman.org.uk site.
I’ve put the demo up here
- GitHub - HACManchester/dokuwiki-demo-setup: dokuwiki demo for documentation
For the testwiki site I’ve kept the admin login a secret, but you can register an email account just to test out the editor.
For the github content if you clone that the login for the admin account on that one is hacmanadmin / test
A Few notes
- This is a proof of concept, don’t put anything there you want to keep, this is really just for testing.
- This is a dokuwiki setup but with the CommonMark plugin enabled by default for every page.
This means the wiki syntax is markdown instead of dokuwiki, which makes it the same as what we use on github (the existing docs pages) and the same markup used on discourse (mailing list gui).
- If we decide to use it I might not be able to maintain it long term (in terms of getting rid of spam etc)
So ideally we’d need several users to be admins
- Before using it properly we’d need to host it on the main hacman domain / site.
Details of which plugins and the setup used are here:
Just to give a bit of a backstory
A long time ago we used to have the wiki hosted on a mediawiki instance, however it was kind of painful to edit and lacked any form of directory structure (imagine all the pages and attachments were in a single global directory / namespace).
After a while certain members moved on and Rossy replaced the wiki with a mkdocs setup on github with a material theme.
This was good as it meant we could now place pages within directories.
But it meant users had to use github pull requests which made it a tad bit difficult to edit for some users.
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.
Personally I moved away from dokuwiki a while back and towards wikijs since I wanted to use markdown.
However wikijs is still kind of unpolished (only about a third of the page is visible with the content with the other two thirds taken up by menu’s). There is a re-write to version 3, but it doesn’t seem to be getting much activity at the moment.
So as a result I’ve recently switched back to dokuwiki but with a more modern markdown plugin (which wasn’t around before).
Functionally this seems to be the best option I can find so far even though it’s not using the most modern web technologies.
One of the things that’s put me off a bit in so far as replacing what we have now is who will look after it.
Since I might not have time to maintain the site myself long term in terms of spam content etc.
That being said I don’t mind doing a demo that others can use or setup if they want to.
- There’s no database involved all the storage is done as files
- There’s a plugin called gitbacked which should allow us to backup the content to 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 also plugins for captcha’s and email registration
The theme is currently set to bootswatch spacelab, 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:
I was initially going to go with slate, but I figured it might be a bit too dark for some folks.
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
```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.
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.