1---
  2title: "Documenting With MediaWiki"
  3description: "Setting up MediaWiki to efficiently write quality documentation"
  4author: Amolith
  5cover: /assets/pngs/mediawiki.png
  6date: 2020-06-04T12:23:34-04:00
  7draft: false
  8categories:
  9  - Technology
 10tags:
 11  - MediaWiki
 12  - Documentation
 13  - Writing
 14  - Efficiency
 15  - 100 Days To Offload
 16toc: true
 17---
 18
 19Much to my chagrin, I've hardly posted anything at all the past couple
 20of weeks. This is partly due to university summer classes starting and
 21partly due to me putting some work into [NixNet's
 22documentation.](https://docs.nixnet.services) After listening to
 23[Episode 4 of 2.5 Admins,](https://2.5admins.com/2-5-admins-04/) I
 24decided to change some things up with my infrastructure planning and,
 25instead of automating all the things, document it first. Only after
 26writing extensive documentation will I look into automating *portions*
 27my setup, like hardening a server directly following installation. To
 28that end, I've decided to use
 29[MediaWiki.](https://www.mediawiki.org/wiki/MediaWiki)
 30
 31After [downloading](https://www.mediawiki.org/wiki/Download) and
 32[installing](https://www.mediawiki.org/wiki/Manual:Installation_guide)
 33MediaWiki, a very straightforward process,[^1] the next step is
 34configuring it. There is of course [a
 35guide](https://www.mediawiki.org/wiki/Manual:System_administration) but
 36I think it can be useful to see someone else's configuration to get
 37ideas from as well, especially considering how many extensions there
 38are. I won't go through *all* of the settings, just the maybe less
 39obvious ones.
 40
 41## URLs
 42The first thing in `LocalSettings.php` is `$wgScriptPath`. Different wikis take vastly different approaches for this. Some fill that variable with `"/w"` (default), some with `"/view"`, and some with something entirely different. [Wikipedia](https://wikipedia.org/wiki/MediaWiki) and all of its children use `"/wiki"`. While well and good, the default configuration will have your URLs appearing as `example.com/wiki/index.php?title=<page>` and this is bad practise for SEO; if you want your pages easily discoverable, the URLs need to be a bit shorter. The easiest way I've found to do this is add all of six lines to my NGINX config and set `$wgScriptPath` to `""` (an empty string).
 43```text
 44location / {
 45    try_files $uri $uri/ @rewrite;
 46}
 47location @rewrite {
 48    rewrite ^/(.*)$ /index.php?title=$1&$args;
 49}
 50```
 51
 52The snippet above tells NGINX to rewrite all of your site's base URLs
 53and remove `index.php?title=` from them. This is a similar approach to
 54what [Mozilla](https://wiki.mozilla.org/Main_Page) has done. The result
 55is cleaner URLs that comply with SEO best practises and a setup that
 56avoids [moving MediaWiki to the site's
 57root.](https://www.mediawiki.org/wiki/Manual:Wiki_in_site_root_directory)
 58
 59## Mobile view
 60I see a *lot* of MediaWiki instances without a good mobile version and,
 61other than keeping the number of extensions down, I don't really
 62understand why. Setting it up is incredibly easy and gives everyone a
 63*much* better experience. The [Minerva
 64Neue](https://www.mediawiki.org/wiki/Special:MyLanguage/Skin:Minerva_Neue)
 65skin is designed specifically for use on mobile devices and is also much
 66more aggressive about optimisation. Though editing is a terrible
 67experience, it also looks great on desktop. The
 68[MobileFrontend](https://www.mediawiki.org/wiki/Extension:MobileFrontend)
 69extension is used to detect the reader's device and serve them either
 70the configured desktop skin or Minerva Neue. You *could* serve a
 71different skin on mobile but I've found that Minerva Neue looks the best
 72by far.
 73
 74To set them up, you'll need to download [the
 75skin](https://www.mediawiki.org/wiki/Special:SkinDistributor/MinervaNeue)
 76and [the
 77extension.](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/MobileFrontend)
 78From there, you'll need to add a few lines to your config file. On a
 79side note, I love how dynamic MediaWiki can be, especially with
 80downloads; providing a copy/paste extraction command that doesn't use
 81wildcards and puts it in the correct directory is *awesome*.
 82
 83``` php
 84# I recommend putting this with the rest of your extensions
 85wfLoadExtension( 'MobileFrontend' );
 86
 87# These can go wherever you want but together is better
 88$wgMFDefaultSkinClass = 'SkinMinerva';
 89$wgMFAutodetectMobileView = true;
 90```
 91
 92With the skin and extension in place and those lines in your config,
 93save and reload and there should be a link at the bottom of your wiki
 94called `Mobile view`. Click it and you'll see Minerva! On a phone,
 95MobileFrontend will automatically serve it but you can force your
 96default theme by clicking `Desktop view` in the same location.
 97
 98![Screenshot of the mobile versions of my MediaWiki instance. The left
 99uses Minerva Neue and the right uses Vector. The left has buttons and
100icons that are much larger and easier to tap making for better
101accessibility. Though the text is readable, the touch targets are much
102too small navigation is hell](/assets/pngs/mediawiki-skins.png)
103
104## Discussion pages
105The default discussion page for MediaWiki works but, unless you're
106already used to it, it can be quite odd for new people. That's where the
107[StructuredDiscussions](https://www.mediawiki.org/wiki/Structured_Discussions)
108extension comes in. Here's a comparison of before and after enabling it.
109
110![side-by-side screenshot of my wiki before and after enabling the
111extension. the left really is just the default content editor. it's like
112giving someone a text editor on a server and asking them to have a
113conversation with someone else by editing the same file and saving it to
114see replies. the right side is with the extension enabled and gives
115buttons to browse by topic and a field to create a new topic. it's very
116similar to github's issue tracker, for example, but without the ability
117to sort by tags](/assets/pngs/talk-before-after.png)
118
119As I said, the left works but most people wouldn't know what to do when
120given the default MediaWiki editor and it raises the barrier for entry.
121The right is *much* more user-friendly and works exactly how one would
122expect. StructuredDiscussions does have a few dependencies but they're
123easy to add. [Echo](https://www.mediawiki.org/wiki/Extension:Echo) is
124for notifications and the others are included by default. After
125[installing
126it,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/Echo)
127and
128[StructuredDiscussions,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/Flow)
129add the following lines to your `LocalSettings.php`.
130
131``` php
132# With the rest of your extensions
133wfLoadExtension( 'Echo' );
134wfLoadExtension( 'Flow' );
135```
136
137Running the following commands is necessary because MediaWiki's database
138needs modification to support the extension. General talk pages are
139`--ns=1` and `User:Talk` pages are `--ns=3`. If you only want Structured
140Discussions enabled for one of them, only run that one. I personally
141recommend doing it for all.
142
143``` text
144php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=revision
145php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=archive
146php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=page
147
148php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=revision
149php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=archive
150php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=page
151```
152
153After that, add these to actually enable the extension. To temporarily
154disable it, you can comment them out but I don't know how that will
155affect talk pages that already exist.
156
157``` php
158# Flow (discussions) configuration
159$wgNamespaceContentModels[NS_TALK] = 'flow-board';
160$wgNamespaceContentModels[NS_USER_TALK] = 'flow-board';
161```
162
163## Subpages
164
165One of the features I'll be making heavy use of for my [Privacy
166Policies](https://docs.nixnet.services/Category:Privacy_policies) and
167[Terms of
168Service](https://docs.nixnet.services/Category:Terms_of_Service) pages
169is [Subpages.](https://www.mediawiki.org/wiki/Help:Subpages) This allows
170you to create pages entitled `Parent/Child` and the child automatically
171links back to the parent at the top. This can be seen in
172[Mozilla](https://wiki.mozilla.org/Apps/Security/Other) and [Arch
173Linux's](https://wiki.archlinux.org/index.php/Firefox/Privacy) wikis
174right under the header and [in mine as
175well.](https://docs.nixnet.services/DNS/Privacy) Enabling it is quite
176simple; just add the following line to your config.
177
178``` php
179## Enable subpages for all namespaces
180$wgNamespacesWithSubpages[NS_MAIN] = true;
181```
182
183## Syntax highlighting
184The final configuration change I've made (so far) has been to enable
185syntax highlighting in the default editor with
186[CodeMirror.](https://www.mediawiki.org/wiki/Extension:CodeMirror) After
187[installing
188it,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/CodeMirror)
189add these lines to your config and you're done!
190
191``` php
192# Place with the other extensions as always
193wfLoadExtension( 'CodeMirror' );
194# Enables it by default but allows users to disable it
195$wgDefaultUserOptions['usecodemirror'] = 1;
196```
197
198![screenshot of the mediawiki editor. headers are larger, code blocks
199are highlighted, links blue with link text black so it's easy to pick
200out, etc. In all, it's a much nicer
201experience.](/assets/pngs/mediawiki-highlight.png)
202
203## Editing in Vim
204The final tip I have is that you can edit pretty much *any* MediaWiki
205instance in Vim, including Wikipedia itself, with [a simple
206plugin.](https://github.com/aquach/vim-mediawiki-editor) The only
207drawback I've found is that, unless you store your password in your
208config, you'll have to enter it every time you close and reopen Vim. You
209can also give Vim [Wikitext syntax
210highlighting](https://en.wikipedia.org/wiki/Help:Text_editor_support#Vim)
211for creating MediaWiki pages when offline. A few days ago, my wiki was
212completely offline while taking a disk image backup but I still wrote
213the majority of the [libvirt](https://docs.nixnet.services/Libvirt) and
214[Debian](https://docs.nixnet.services/Debian) pages while I waited and
215the highlighting was really nice.
216
217---
218
219This was posted as part of #100DaysToOffload, an awesome idea (dead link to fedi
220post) from [Kev Quirk.](https://kevq.uk/) If you want to participate, just write
221something every day for 100 days and post a link on social media with the
222hashtag!
223
224[^1]: If you're having issues, feel free to contact me and I'll help
225    where I can.