Proof of Concept Wiki

The Hackspace Infastructure
1

Intro

Overview

I’ve put together a possible replacement for the existing docs.hacman.org.uk site.
I’ve put the demo up here

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:

Backstory

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.

Maintenance

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

Theme

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.

Editor

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.

image

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

image

image

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.

Authentication

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.

Plugins

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.

2 Likes
2

I’m a little hesitant to offer support for this, purely because we already have a number of digital sites & systems in various stages of use or neglect. Until we’ve got a better grasp of our digital assets, I’m hesitant toward introducing another.

I do like the idea of replacing or redoing our documentation site though. The current docs do appear to have a lot of stale or older, archived, probably-not-useful (?) content.

Although it would be a larger project, I’d take the opportunity to start from scratch and – using our existing content for reference – begin thinking about a general content strategy:

  • What pages / categories do we want?
  • How often will content be reviewed and updated (different lifecycles for different areas, I imagine)
  • Who will be responsible for different sections (board, subgroups, …)
  • Will any content need syncing or consuming by other systems (the membership system parses our current Markdown-based docs on equipment pages, for example)

Re: the spam risk, I do think that’s an area where a statically managed docs would be preferable. Having to go through GitHub for changes does make it harder to participate but it does lower the opportunity for spam submissions in the first place, and enforces a review step before changes can go live.

It does sounds like that GitHub workflow is the primary problem with our current docs? We could put together a guide and offer training to support folks with this workflow, if that might help?

1 Like
3

Thank you for setting this up - I’ve had a look around and the import from the existing docs to Docuwiki appears to have worked well - images, tables etc all seem to be rendered correctly. There are a few cosmetic issues, for example the directory list taking up all of the browser window with the page text displayed below it, but that is not serious.

My main concern is, as you’ve said, who will look after it. You sound like you’re enthusiastic about DocuWiki and might be willing to maintain it for a while - but if after two years you’re no longer able to maintain or edit it, someone else may come along and make many good arguments in favour of moving to, say, Confluence, and pointing out faults in DocuWiki, and we’ll do the conversion all other again. We need to be careful about what tech we choose for this and make sure it’s likely to be useful for a large number of members who can keep up the critical mass of editors.

A side note about MediaWiki: the lack of directory structure is entirely how MediaWiki is supposed to work. It’s meant to be organised with non-exclusive categories. You can force directory/hierarchy on MediaWiki, but the results are generally poor. I’m not suggesting we go back to MediaWiki, just saying that the choice of underlying wiki software influences how we organise information. Since the space in general seems to like directory structures and that’s what we have on the existing github documents, and DocuWiki likes directories, it would seem to be appropriate.

4

Mkdocs

I do plan on doing a cleanup of the existing docs inside the existing mkdocs site.
There’s some old content that’s fairly useful (other not so) such as supplier lists.
If we stick with mkdocs then I don’t mind so much since I think it’s still better than what we had before.
It just means those of us with git access to the hacman org will need to approve the pull requests is all for any changes.
(not really sure if it’s just me at the moment or if anyone else is doing it)

The reason I did this was just because I was doing it anyway for my own docs at home so it was just a copy / paste.
As far as the spam issue I think we’d first have to look at getting the main site to support OAuth2 so that the existing accounts could be used, instead of allowing anyone to register.

One thing I might try out is a seperate setup using docus for the 3d printer docs if I can get around to writing some (similar to mkdocs but use vue controls and is an spa)

Conversion

For the conversion the main thing I had to change manually was the image and file attachments.
It looks as if some folks were just using full external links instead of internal ones in some cases.

To make life easy I used the dokuwiki media button which auto inserts links to files which means they sort of end up looking like

{{:wiki:editor2.png?400|}}

This isn’t markdown syntax but does work as it’s picked up by the dokuwiki parser and is just generally quicker to do.
For the text it was just a case of renaming the .md files to .txt files then copying into a directory.

MediaWiki

In the case of Mediawiki I’ve always felt it’s more orientated towards dictionary layouts.
So in the case of wikipedia where you’re providing a seperate summary for a given topic then it works well.
However for something where you’re trying to group together multiple pages for a topic it tends to fall down.
What this leads to is trying to bundle everything together on a single page which makes it less readable (this is something that happened in the past)

One example would be information on the laser cutter, you might want seperate pages, one for materials, one for maintenance information, one for inductions, one for details on how to install the tools etc.
Now you could try and write that as seperate pages in mediawiki, but lets say you create a page called “materials”, since it’s in a global namespace you then have to think about prefixes such as “laser_materials”
Also all of the attachements such as images and pdfs exist within a single namespace / directory.

With the above in mind plus the below I was fairly happy when we moved to mkdocs

  • The use of markdown (which is more modern, I’d argue easier to use but personal preference)
  • The use of namespaces / directories
  • The navigation menu (there was limited navigation in mediawiki but not to every page, mostly just via search)
  • The ability to easily rename / move pages around

Another issue we ran into with the mediawiki (although I believe it can be turned off) is the case sensitivity of page names.
I discovered at one point we had hidden pages with the same name but a capital letter at the front at that point I sort of gave up on it.

This is when I decided to do the CNC docs as it’s own thing which can be seen here (also mkdocs although it was setup a long time back)

5

just to add if the menu is on the top instead of the side then that might be a css issue
it’s supposed to look like this

image
image1920×921 99.7 KB