226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
---
|
|
title: "Documenting With MediaWiki"
|
|
description: "Setting up MediaWiki to efficiently write quality documentation"
|
|
cover: /assets/pngs/mediawiki.png
|
|
date: 2020-06-04T12:23:34-04:00
|
|
categories:
|
|
- Technology
|
|
tags:
|
|
- MediaWiki
|
|
- Documentation
|
|
- Writing
|
|
- Efficiency
|
|
- 100 Days To Offload
|
|
toc: true
|
|
---
|
|
|
|
Much to my chagrin, I've hardly posted anything at all the past couple
|
|
of weeks. This is partly due to university summer classes starting and
|
|
partly due to me putting some work into [NixNet's
|
|
documentation.](https://docs.nixnet.services) After listening to
|
|
[Episode 4 of 2.5 Admins,](https://2.5admins.com/2-5-admins-04/) I
|
|
decided to change some things up with my infrastructure planning and,
|
|
instead of automating all the things, document it first. Only after
|
|
writing extensive documentation will I look into automating *portions*
|
|
my setup, like hardening a server directly following installation. To
|
|
that end, I've decided to use
|
|
[MediaWiki.](https://www.mediawiki.org/wiki/MediaWiki)
|
|
|
|
After [downloading](https://www.mediawiki.org/wiki/Download) and
|
|
[installing](https://www.mediawiki.org/wiki/Manual:Installation_guide)
|
|
MediaWiki, a very straightforward process,[^1] the next step is
|
|
configuring it. There is of course [a
|
|
guide](https://www.mediawiki.org/wiki/Manual:System_administration) but
|
|
I think it can be useful to see someone else's configuration to get
|
|
ideas from as well, especially considering how many extensions there
|
|
are. I won't go through *all* of the settings, just the maybe less
|
|
obvious ones.
|
|
|
|
## URLs
|
|
The 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).
|
|
```text
|
|
location / {
|
|
try_files $uri $uri/ @rewrite;
|
|
}
|
|
location @rewrite {
|
|
rewrite ^/(.*)$ /index.php?title=$1&$args;
|
|
}
|
|
```
|
|
|
|
The snippet above tells NGINX to rewrite all of your site's base URLs
|
|
and remove `index.php?title=` from them. This is a similar approach to
|
|
what [Mozilla](https://wiki.mozilla.org/Main_Page) has done. The result
|
|
is cleaner URLs that comply with SEO best practises and a setup that
|
|
avoids [moving MediaWiki to the site's
|
|
root.](https://www.mediawiki.org/wiki/Manual:Wiki_in_site_root_directory)
|
|
|
|
## Mobile view
|
|
I see a *lot* of MediaWiki instances without a good mobile version and,
|
|
other than keeping the number of extensions down, I don't really
|
|
understand why. Setting it up is incredibly easy and gives everyone a
|
|
*much* better experience. The [Minerva
|
|
Neue](https://www.mediawiki.org/wiki/Special:MyLanguage/Skin:Minerva_Neue)
|
|
skin is designed specifically for use on mobile devices and is also much
|
|
more aggressive about optimisation. Though editing is a terrible
|
|
experience, it also looks great on desktop. The
|
|
[MobileFrontend](https://www.mediawiki.org/wiki/Extension:MobileFrontend)
|
|
extension is used to detect the reader's device and serve them either
|
|
the configured desktop skin or Minerva Neue. You *could* serve a
|
|
different skin on mobile but I've found that Minerva Neue looks the best
|
|
by far.
|
|
|
|
To set them up, you'll need to download [the
|
|
skin](https://www.mediawiki.org/wiki/Special:SkinDistributor/MinervaNeue)
|
|
and [the
|
|
extension.](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/MobileFrontend)
|
|
From there, you'll need to add a few lines to your config file. On a
|
|
side note, I love how dynamic MediaWiki can be, especially with
|
|
downloads; providing a copy/paste extraction command that doesn't use
|
|
wildcards and puts it in the correct directory is *awesome*.
|
|
|
|
``` php
|
|
# I recommend putting this with the rest of your extensions
|
|
wfLoadExtension( 'MobileFrontend' );
|
|
|
|
# These can go wherever you want but together is better
|
|
$wgMFDefaultSkinClass = 'SkinMinerva';
|
|
$wgMFAutodetectMobileView = true;
|
|
```
|
|
|
|
With the skin and extension in place and those lines in your config,
|
|
save and reload and there should be a link at the bottom of your wiki
|
|
called `Mobile view`. Click it and you'll see Minerva! On a phone,
|
|
MobileFrontend will automatically serve it but you can force your
|
|
default theme by clicking `Desktop view` in the same location.
|
|
|
|
|
|
|
|
## Discussion pages
|
|
The default discussion page for MediaWiki works but, unless you're
|
|
already used to it, it can be quite odd for new people. That's where the
|
|
[StructuredDiscussions](https://www.mediawiki.org/wiki/Structured_Discussions)
|
|
extension comes in. Here's a comparison of before and after enabling it.
|
|
|
|
|
|
|
|
As I said, the left works but most people wouldn't know what to do when
|
|
given the default MediaWiki editor and it raises the barrier for entry.
|
|
The right is *much* more user-friendly and works exactly how one would
|
|
expect. StructuredDiscussions does have a few dependencies but they're
|
|
easy to add. [Echo](https://www.mediawiki.org/wiki/Extension:Echo) is
|
|
for notifications and the others are included by default. After
|
|
[installing
|
|
it,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/Echo)
|
|
and
|
|
[StructuredDiscussions,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/Flow)
|
|
add the following lines to your `LocalSettings.php`.
|
|
|
|
``` php
|
|
# With the rest of your extensions
|
|
wfLoadExtension( 'Echo' );
|
|
wfLoadExtension( 'Flow' );
|
|
```
|
|
|
|
Running the following commands is necessary because MediaWiki's database
|
|
needs modification to support the extension. General talk pages are
|
|
`--ns=1` and `User:Talk` pages are `--ns=3`. If you only want Structured
|
|
Discussions enabled for one of them, only run that one. I personally
|
|
recommend doing it for all.
|
|
|
|
``` text
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=revision
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=archive
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=1 --table=page
|
|
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=revision
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=archive
|
|
php maintenance/populateContentModel.php --wiki=somewiki --ns=3 --table=page
|
|
```
|
|
|
|
After that, add these to actually enable the extension. To temporarily
|
|
disable it, you can comment them out but I don't know how that will
|
|
affect talk pages that already exist.
|
|
|
|
``` php
|
|
# Flow (discussions) configuration
|
|
$wgNamespaceContentModels[NS_TALK] = 'flow-board';
|
|
$wgNamespaceContentModels[NS_USER_TALK] = 'flow-board';
|
|
```
|
|
|
|
## Subpages
|
|
|
|
One of the features I'll be making heavy use of for my [Privacy
|
|
Policies](https://docs.nixnet.services/Category:Privacy_policies) and
|
|
[Terms of
|
|
Service](https://docs.nixnet.services/Category:Terms_of_Service) pages
|
|
is [Subpages.](https://www.mediawiki.org/wiki/Help:Subpages) This allows
|
|
you to create pages entitled `Parent/Child` and the child automatically
|
|
links back to the parent at the top. This can be seen in
|
|
[Mozilla](https://wiki.mozilla.org/Apps/Security/Other) and [Arch
|
|
Linux's](https://wiki.archlinux.org/index.php/Firefox/Privacy) wikis
|
|
right under the header and [in mine as
|
|
well.](https://docs.nixnet.services/DNS/Privacy) Enabling it is quite
|
|
simple; just add the following line to your config.
|
|
|
|
``` php
|
|
## Enable subpages for all namespaces
|
|
$wgNamespacesWithSubpages[NS_MAIN] = true;
|
|
```
|
|
|
|
## Syntax highlighting
|
|
The final configuration change I've made (so far) has been to enable
|
|
syntax highlighting in the default editor with
|
|
[CodeMirror.](https://www.mediawiki.org/wiki/Extension:CodeMirror) After
|
|
[installing
|
|
it,](https://www.mediawiki.org/wiki/Special:ExtensionDistributor/CodeMirror)
|
|
add these lines to your config and you're done!
|
|
|
|
``` php
|
|
# Place with the other extensions as always
|
|
wfLoadExtension( 'CodeMirror' );
|
|
# Enables it by default but allows users to disable it
|
|
$wgDefaultUserOptions['usecodemirror'] = 1;
|
|
```
|
|
|
|
|
|
|
|
## Editing in Vim
|
|
The final tip I have is that you can edit pretty much *any* MediaWiki
|
|
instance in Vim, including Wikipedia itself, with [a simple
|
|
plugin.](https://github.com/aquach/vim-mediawiki-editor) The only
|
|
drawback I've found is that, unless you store your password in your
|
|
config, you'll have to enter it every time you close and reopen Vim. You
|
|
can also give Vim [Wikitext syntax
|
|
highlighting](https://en.wikipedia.org/wiki/Help:Text_editor_support#Vim)
|
|
for creating MediaWiki pages when offline. A few days ago, my wiki was
|
|
completely offline while taking a disk image backup but I still wrote
|
|
the majority of the [libvirt](https://docs.nixnet.services/Libvirt) and
|
|
[Debian](https://docs.nixnet.services/Debian) pages while I waited and
|
|
the highlighting was really nice.
|
|
|
|
---
|
|
|
|
This was posted as part of
|
|
[#100DaysToOffload,](https://100daystooffload.com/) an [awesome
|
|
idea](https://fosstodon.org/@kev/104053977554016690) from [Kev
|
|
Quirk.](https://kevq.uk/) If you want to participate, just write
|
|
something every day for 100 days and post a link on social media with
|
|
the hashtag!
|
|
|
|
[^1]: If you're having issues, feel free to contact me and I'll help
|
|
where I can.
|