Often it is handy to include the contents of external files directly in an article instead simply linking to the file. This describes "include" -- a MediaWiki extension that lets you include external static content from the local file system; a remote URL; or a Subversion repository. You can also optionally embed included content as an iframe. This is useful for including the output of a CGI or external web site.
If the external text is source code then it can be optionally colorized with syntax highlighting. By default the text is automatically wrapped in a <pre></pre> tag and all HTML entities are escaped. This can be turned off if you want to include raw text or HTML.
Note that syntax coloring requires the Pear Text_Highlighter module. The <include> extension will run without Text_Highlighter, but the 'highlight' attribute will be disabled. If you try to use it without installing Text_Highlighter the include script will silently ignore the 'highlight' attribute.
You can optionally add the svncat attribute which tells the extension to use "svn cat" to include the file from an SVN repository. In this case the "src" argument will be passed directly to SVN, so src="URL" may be any URL that SVN understand (file:, svn+ssh:, webdav:, http:). This is very handy for documenting source code.
The Include script is also described in the [MediaWiki Extension section].
The administrator can restrict local paths that may be included by modifying one of two variables in LocalSettings.php.
By default, only local files under DOCUMENT_ROOT are allowed. You can expand that list by editing $wg_include_allowed_parent_paths in LocalSettings.php:
$wg_include_allowed_parent_paths = $_SERVER['DOCUMENT_ROOT'];
This will allow documents under /home/noah/pub/ to also be included:
$wg_include_allowed_parent_paths = array($_SERVER['DOCUMENT_ROOT'], '/home/noah/pub');
<include src="/home/noah/pub/README" /> <include src="/home/noahspurrier/pub/README" />
For example, this will product the error seen below:
<include src="LocalSettings.php" /> <include src="LocalSettings.php" />
Including the LocalSettings.php file is disallowed by the regex in the list below:
$wg_include_disallowed_regex = array('/.*LocalSettings\.php/', '/.*\.conf/', '/~.*/');
Download the include script
Click to download: include.php
For example, the include script below is itself included in this article with the following include line:
<include svncat src="/home/noah/engineering/src/mediawiki/extensions/include.php" highlight="php" />
This includes the given source and highlights it with PHP syntax (if supported on this web server):
<include src="/home/noahspurrier/noah.org/engineering/src/mediawiki/extensions/include.php" highlight="php" />
Thanks to Uli Knieper for the "wikitext" code.