Enhancing MediaWiki with the Cite Extension: Best Practices for Referencing

When you first stumble onto the <ref>…</ref> tag in a wiki article, it can feel a bit like discovering a secret handshake. Suddenly you have a way to footnote, to shout “source!” without breaking the flow of the prose. The Cite extension makes that possible, but like any handy tool it works best when you know a few tricks, avoid common snags, and give it a little TLC.

Quick‑and‑dirty install (for the impatient)

If you’re running MediaWiki 1.34 or newer, the extension is already bundled – skip the download step. Otherwise, grab the latest tarball from the Gerrit repo or pull straight from Git:

cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Cite

Then drop this line at the very bottom of LocalSettings.php (yes, right after your wfLoadSkin() calls, if you have any).

wfLoadExtension( 'Cite' );

Give the page a quick refresh; you should see “Cite” listed on Special:Version. If it’s missing, double‑check the file permissions – MediaWiki needs read access to extensions/Cite.

Configuration knobs you’ll actually touch

The extension ships with a zoo of $wgCite… variables. Most are safe to ignore, but a handful make a real difference in daily editing.

• $wgCiteResponsiveReferences – set to true (the default) and long reference lists automatically split into columns on wider screens. If you prefer the classic single‑column look, flip it to false.
• $wgCiteVisualEditorOtherGroup – on wikis that love a tidy toolbar you can move the Cite button under “Insert” instead of its own top‑level slot. Handy for VisualEditor‑centric sites.
• $wgCiteBookReferencing – experimental sub‑reference feature. Turn it on only if you need to cite individual pages within a book and you’re comfortable chasing bugs.
• $wgCiteReferencePreviews – toggles the Popups‑style hover preview for <ref> tags. If your community finds pop‑ups distracting, switch it off.

All of these go into LocalSettings.php, e.g.:

$wgCiteResponsiveReferences = true;
$wgCiteVisualEditorOtherGroup = false;
$wgCiteReferencePreviews = true;

Crafting clean, reusable citations

One of the biggest annoyances on a wiki is the “copy‑paste‑the‑same‑URL‑over‑and‑over” syndrome. Cite lets you define reusable citation templates, but you have to give them a sensible name and maybe a decent icon if you’re using VisualEditor.

Put a JSON blob on MediaWiki:Cite-tool-definition.json like this:

[
  {
    "name": "web",
    "icon": "browser",
    "template": "Cite web"
  },
  {
    "name": "book",
    "icon": "book",
    "template": "Cite book"
  },
  {
    "name": "news",
    "icon": "newspaper",
    "template": "Cite news"
  }
]

Now the VisualEditor toolbar will show three neat buttons – click one, fill in the fields, and you get a consistent citation every time. If you need a custom field (say, “access‑date”), just add it to the underlying template; the JSON definition stays the same.

Styling references for readability

By default MediaWiki spits out a plain list of numbered footnotes. That works fine for short articles, but on a long‑form page you might want a bit of flair:

• Backlink alphabet – if you dislike the “a‑b‑c” style, switch to the CLDR‑based alphabet by setting $wgCiteUseLegacyBacklinkLabels = false;. This respects language‑specific ordering (e.g., “å” after “z” in Swedish).
• Hidden references – sometimes you want a source that isn’t shown in the footnote list (e.g., a “further reading” citation). Wrap it in a <ref group="hidden" /> and then call <references group="hidden" /> where you want them displayed, or omit the call entirely to keep them invisible.

Columns – the responsive setting mentioned earlier takes care of this on modern browsers. For older browsers you can force a two‑column layout via CSS in MediaWiki:Common.css:

ol.references {
  column-count: 2;
  column-gap: 2em;
}

Common pitfalls (and how to dodge them)

Even seasoned editors trip over a few quirks. Below is a cheat‑sheet of the most frequent gotchas.

1. Pipe trick & pre‑save transforms – the classic [[File:…|thumb|Caption]] pipe trick doesn’t work inside <ref> tags. If you need an image in a citation, use a dedicated template that injects the file markup outside the <ref> block.
2. Duplicate <ref> IDs – using the same name for two different sources leads to the second one silently overwriting the first. Always give unique names or use the unnamed syntax (<ref>…</ref>) for one‑offs.
3. Long‑tail URLs – a 100‑character URL looks awful in the footnote. Trim it with a {{url}} template or use a Cite web template that splits the URL into a “link” and “display” part.
4. Performance on massive pages – each <ref> triggers a small parser hook. On a page with thousands of references you might notice a slowdown. The $wgCiteResponsiveReferencesThreshold variable (default 200) can be lowered to force column‑splitting earlier, which eases the rendering load.
5. Internationalisation – the default “accessdate” label appears in English. To localise it, add a message override in MediaWiki:Accessdate for your language.

Testing your changes – a quick sanity checklist

Before you shout “All set!” to the community, run through these items:

• Open a sandbox page, add a few <ref> tags with different templates (web, book, news). Verify they render, the backlink letters line up, and the <references /> block shows the right order.
• Resize the browser window. Do the references re‑flow into columns? If not, double‑check $wgCiteResponsiveReferences and any custom CSS you added.
• Hover over a reference (if $wgCiteReferencePreviews is on). Make sure pop‑ups appear without a flicker.
• Inspect the page source. Are the id attributes of each reference unique? No duplicate cite_note-1 IDs, please.
• Switch the interface language (if you have a multilingual wiki). Does the “accessdate” label translate correctly?

Beyond the basics: extending Cite for your niche

If your wiki covers a specialized domain – say, legal statutes, scientific articles, or a fictional universe – you’ll probably want custom citation templates. The workflow looks like this:

1. Copy Template:Cite web to a new name, e.g. Template:Cite law.
2. Replace the parameters you don’t need (perhaps drop url) and add new ones (like section or jurisdiction).
3. Update MediaWiki:Cite-tool-definition.json with a new entry, giving it a meaningful icon (maybe “gavel”).
4. Ask the community to edit the MediaWiki:...‑messages so the UI reflects the new fields.

Because the extension uses the same underlying parser hooks, the new template will behave exactly like the built‑in ones – you get auto‑numbering, backlink letters, and optional pop‑ups for free.

When things go sideways: troubleshooting tips

Nothing is ever quite as smooth as the documentation promises. Here are a few “first‑aid” steps if you run into trouble.

• Extension not listed on Special:Version? – Double‑check the spelling of the folder name (Cite not cite) and make sure the wfLoadExtension() line is not inside a conditional that never fires.
• Reference numbers jump around after an edit? – This usually means you have duplicate named references. Search the page for name= in the <ref> tags and rename the conflicted ones.
• Pop‑ups never appear? – The Popups extension must be enabled and the user preference “Reference previews” turned on. Also, the JavaScript module ext.cite.referencePreviews must load without errors (check the browser console).
• References don’t show up at all? – Ensure you have a <references /> tag somewhere on the page. If you’re using a custom tag like <references responsive />, verify that $wgCiteResponsiveReferences is true.

Keeping the extension fresh

The Cite codebase lives on Gerrit and is periodically merged into the core MediaWiki release. If you’re running a long‑term support (LTS) version, you’ll get the bundled version automatically; otherwise, consider pulling the REL1_44 branch (or newer) to stay on top of bug fixes and minor feature flags.

When you upgrade MediaWiki, always double‑check the compatibility matrix. Some configuration variables get renamed – for example, $wgCiteUseLegacyBacklinkLabels was introduced in 1.35 to replace the older $wgCiteLegacyBacklinkLabels. A quick glance at the release notes can save you a day of “undefined variable” warnings.

Final thoughts

At the end of the day, the Cite extension is a toolbox, not a magic wand. Install it, tweak a few settings, write a couple of reusable templates, and you’ll see a noticeable boost in citation consistency across your wiki. The real power shows up when you couple those basics with community conventions – a style guide for reference formatting, a shared set of templates, and a habit of checking the footnote list before publishing