Summary: How to include an external file (from the same file system)
Version: 0.2 (2007-12-07)
Status: Stable, Maintained
Maintainer: ThomasP
Categories: Includes
Discussion: IncludeFile-Talk


How do I include an external file (from the same file system)?


There are two simple and quick solutions, and one more elaborate and flexible one that should be the safest choice.

Solution 1a: unfiltered unsanitised inclusion of any file

Use only if you can trust all wiki editors. Do not use on a public wiki!

The following markup lets you include any file, relativ to the path you set in the markup definition. Any file on the system can be included, if you give the right relativ path in the markup. Note that files are not filtered or sanitised for output. Code may be interpreted. This can be potentially disastrous.

  Markup_e('includefile', 'directives', '/\\(:includefile\\s+([-\\/.\\w]+)\\s*:\\)/',
    "Keep(implode('', file('/home/yourlocalfilesystempath/public_html/inc/'.\$m[1])))");

With this in place, the markup (:includefile something.html:) would include the contents of /home/yourlocalfilesystempath/public_html/inc/something.html in the output.

For a sanitised and preformatted output for showing code file content see next solution, although it is still allowing any file on the system to be shown. For a safe solution restricting files to be in a uploads direcory and checking read permission see solution 3 below.

  • This recipe was last tested on PmWiki version: 2.1beta9
  • This recipe requires at least PmWiki version: any version 2

Solution 1b: sanitised and filtered for showing any file content

Use only if you can trust all wiki editors. Do not use on a public wiki!

No attempt is made to ask for any read authorisation or restrict the file path to uploads/ or other defined directories. You could show content of any file on your system. This could be a god solution for someone wanting to show contents of php files from the cookbook directory for instance.

Place in config.php:

Markup_e('showsource', 'directives', "/\\(:showsource\\s+(.*?)\\s*?:\\)/",

function ShowSource($filename) {
        $text = htmlspecialchars(file_get_contents($filename));
        return "<pre class='escaped'>".Keep($text)."</pre>";

Use markup (:showsource pathtofile/filename.ext:) i.e. like (:showsource cookbook/newpagebox.php:)
The filepath is relativ to the location of your pmwiki script.

HansB December 07, 2007, at 07:00 AM

Solution 2: hardcoded skin template inclusion

In a skin template file, you can use <!--file:path/to/template.html-->.
Code will be interpreted.
This solution is not for showing file content only.

Solution 3: sanitised and filtered and access restricted for showing file content

This recipe includes the content of a given file (or set of files) in the output of the wiki page. "In the output" means that the inclusion is dynamic (like a link) - the markup in the wiki page itself remains unchanged. It is assumed that you have the SecureAttachments recipe in place, so uploaded files are gathered in a non-webserver-accessible space (usually below upload/) and grouped according to wiki page.

The basic syntax is

 (:includefile filename.txt options:)

The file is taken from the upload directory corresponding to the wiki page where the markup is placed in. You can also specify a set of files, using the ext=txt option (then omit the filename argument), any other file extension is of course also possible. The full set of options is:

  • ext=... - specify a comma separated list of file extensions
  • up to version 0.1, header=... - print file name in front of every file (on), or print it even in bold (bold)
  • and from version 0.2 upward, header=...:
    • filename - formerly on
    • filenamebold - formerly bold
    • filenamesmall
    • hr - horizontal rule preceding the header
  • fontsize=... - use given font size (8pt or similar) to display file contents
  • order=... - when displaying a set of files, use the given ordering, where name, size, time, atime, mtime, ctime are allowed (prepended with minus for descending order as usual). (Means time of last access or modification, or create time.)

Security issues: On inclusion it is checked whether the current user has permission to access the file, using the includefile action. This action is by default mapped to the read level, so the user needs read permission on the wiki page the file is belonging to. When including the contents all tags are effectively escaped by applying the htmlspecialchars function. The result is packed into a <code> environment.

ThomasP March 19, 2007, at 12:04 AM


  • ver 0.2 (2007-12-07) IncludeFile_v0.2.phpΔ (rename to IncludeFile.php after download)
    • added version information
    • corrected sorting feature (previously sorting by filename only)
    • extended header option, voiding former header options on and bold
  • ver 0.1 (2006-08-01) IncludeFile_v0.1.phpΔ


  • This recipe was last tested on PmWiki version: 2.1.11
  • This recipe requires at least PmWiki version: any version 2

See Also

  • Include Upload
  • WikiSh provides a secure way of allowing access to text files. Valid textfiles (or patterns) are specified in the $WikiShTextReadList[] array. You "include" a file in the current page with this markup: {(cat TEXTFILE--path/to/filename.ext)}. Other options are also available.


  • Maintained by ThomasP (I'm not reading this page very often, and have no notification set; please write email if there is an urgent need - see my profile.)


See discussion at IncludeFile-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.