MediaWiki extensions manual
OOjs UI icon advanced.svg
Release status: beta
Implementation Parser function
Description A parser extension that enables "mad libs" style constructions.
Author(s) Clark Verbrugge (clumptalk)
Latest version 1.0.1
MediaWiki ≥ 1.23
Database changes No
License Creative Commons Zero v1.0 Universal
Translate the MadLib extension if it is available at translatewiki.net

Check usage and version matrix.

The MadLib extension allows you to easily generate mad libs-style text, giving you a magic word in which you can use tags to specify replaceable text, with the replacements randomly chosen from separate MediaWiki pages corresponding to the tag each time the page is loaded.


MadLib usage requires you first create a word list for each tag. Then you can construct madlib sentences by referring to your tags within the "#madlib" magic word (template) construction.

Word ListsEdit

Each tag requires a line-separated list of possible replacements stored in a page named to correspond to a specific tag. You have two ways you can format lines in these word list pages:


Each entire line defines a distinct bit of text that might be selected as a tag replacement.

  • The first character should not be a "#" (if you really want a "#" used the escaped form, #).

The line consists of chunks of text separated by hashtags that identify distinct sub-forms of your replacement text. When you want a specific form you can then specify the desired hashtag, and instead of the whole line you get just that portion. For this to work the line should be constructed as a sequence of pairs of hashtags and the corresponding replacement, separated by whitespace. For example, #onehash blah blah blah #anotherhash foo bar is a line defining two hashtags.

  • The first non-whitespace character of each line should be a "#".
  • The empty string is a valid hashtag; this is useful when you want a default, non-hashtagged replacement string as well as specific, hashtagged replacements.


  • In either the Simple or Hashtagged form, your page of replacements can also use the normal <noinclude>, <includeonly>, and <onlyinclude> tags, if you want to hide or augment the way the page is rendered when you look at it outside of editor mode. Text within <noinclude> and </noinclude> is ignored, while <includeonly>, <onlyinclude>, </includeonly>, and </onlyinclude> are discarded.
  • You can also use \n to indicate a line breaks in your replacement text if you want multi-line replacements.
  • You can have empty lines within a word list, but the page of word lists is trimmed of leading and trailing whitespace.

Magic Word UseEdit

The MadLib itself is constructed within a template invocation, as {{#madlib:some string with tags|taglist|optional prefix}}

There are 2 necessary parameters, and one optional. The first parameter specifies the text, including the tags you want to replace, where each tag is contained in angle brackets (like "<animal>"). The second parameter consists of a comma-separated list of the tags your text uses (like "animal"); note that these are the names of the wordlist pages. The third parameter, if present, gives a common prefix to the names of the word list pages. This is useful if you put your word lists into sub-pages or a different namespace, so if your word lists are "Words/Mammals", "Words/Fish", you can specify a third parameter of "Words/" and then just use "<Mammals>", "<Fish>", instead of writing "<Words/Mammals>", "<Words/Fish>".

  • Tag names and the prefixes are case-sensitive and should match the wiki page name.

If you used a hashtagged word list, a tag should have a hashtag to specify which variation it wants. You can also force the randomization of repeated uses of the same tag to be the same or not. Thus there are actually 4 formats to describe how a tag is replaced:

Each use of "<animal>" is (separately) replaced by randomly selected text. If your word list doesn't use hashtags these are full lines, or if you word list does use hashtags these are the parts of the line identified by the empty hashtag ("#").
Each use of "<animal#hash>" is (separately) replaced by randomly selected text, corresponding to that hashtag. If your word list doesn't use hashtags, or the hashtag isn't found, it'll be an empty string.
Each use of "<animal-1>" is replaced by the same randomly selected text.
Each use of "<animal-1#hash>" is replaced by the same randomly selected text, corresponding to that hashtag.
  • You can use different numbers ("<animal-1>", "<animal-2>" etc), defining distinct sets of replacements that use the same random choice. The number sequence you use to indicate such sets must start at 1 and be contiguous. By default you can only use 1 through 9, but that upper limit is configurable.
  • These 4 use-cases are processed separately, so sets do not constrain simple uses with hashtags uses. That is, "<animal-1>" and <animal-1#hash>" may not be selected from the same replacement line. To make them correspond you'd need to explicitly state the default hashtag, "<animal-1#>" and <animal-1#hash>" will correspond.

A Simple ExampleEdit

Suppose the page "animal" contains

wallaby with a limp

and the page "location" contains

closet full of toys

Then {{#madlib:I read a book about a <animal> in a <location>.|animal,location}} will render as one of the 9 possibilities:

  • I read a book about a cat in a hat.
  • I read a book about a wallaby with a limp in a shoe.
  • I read a book about a badger in a closet full of toys.
  • etc.

A Hashtagged ExampleEdit

Suppose the page "animal" instead contains

# cat                  #types felines
# badger               #types mustelids
# wallaby with a limp  #types macropods that limp

and the page "location" is as above. Then {{#madlib:I read a book about a <animal-1#> in a <location>. I like <animal-1#types>.|animal,location}} will render as one of the 9 possibilities:

  • I read a book about a cat in a hat. I like felines.
  • I read a book about a wallaby with a limp in a shoe. I like macropods that limp.
  • I read a book about a badger in a closet full of toys. I like mustelids.
  • etc.


  • Download and place the file(s) in a directory called MadLib in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    require_once "$IP/extensions/MadLib/MadLib.php";
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration parametersEdit

Changes the maximum number of sets of identical random choices. The default is 9.