To enable error checking for every (:include:) do this:

Create a page Site.IncludeError in your wiki (wiki.d), or your in your farm (wikilibs.d) and inside it put something like:

   %red%'''ERROR: An include failed!'''%%

Then add this Markup code the your local/config.php or your local/farmconfig.php

# add error page Site.IncludeError to every include directive
if($action != "imgtpl")
  Markup('IncludeError', '_begin', '/(\\(:include )(.*?)(:\\))/', "$1$2 Site.IncludeError$3");


> Note: Previous versions of PmWiki allowed whitespace between #from and #to anchors even though it was not designed to. Newer versions do not allow whitespace anymore. To re-enable this "exploited misbehavior" put this into your config.php or farmconfig.php

    Markup('includeanchors', '<include', '/(\\(:include.*?#\\w+)\\s+(#\\w+)/', '$1$2'); 

Labeling this as "exploited misbehavior" makes it sound really bad. Why is this discouraged? What could possibly go wrong? --gnuzoo

No idea, I don't see when this was changed, and I don't remember ever changing it, or writing this. I've removed it. This is not an exploit in the sense of vulnerability. I suspect the "exploited misbehavior" part is when people uncover some functionality that is unintended and undocumented, and start using it in their wikis. This makes it more work for the developers when we need to update the code and to support these people. For best results on the pursuit of happiness, don't use undocumented features, and don't document them if you didn't design them and won't support them :-). --Petko

This message from 2007 is probably related to this section. --Petko

If I include part of a page (section or line/s) where there are anchor-links within the same page (e.g.[[#name|link text]]), obviously they do not work ... is there a possibility to add an option (a sort of basepage extension) in a way that they can be automatically transformed into standard links (e.g. [[{$FullName}#name|link text]])? - Frank February 25, 2019, at 02:47 AM

This can be done with a custom setting of $QualifyPatterns in config.php, for example:

$QualifyPatterns['/(\\[\\[ *)(#[A-Za-z][-.:\\w]* *\\| *.*? *\\]\\])/'] = '$1{$FullName}$2';

Note that if you include several sections, and they contain links from one to another, the included links will point to the original page anchors, even if the anchor is included in the current page. --Petko March 01, 2019, at 10:21 AM

Thanks a lot. A note for those interested, it also works with TextExtract. -- Frank March 01, 2019, at 01:41 PM

Is there any way to include (chapters of) pages which are protected (authuser.php)? Martin

No, there isn't. The easiest and most secure way to achieve this is the other way around: have the public sections in a public page (passwdread=@nopass or @_site_read) and include those into both the protected page, and the public page.

A different approach could be to include a login form if the visitor has no read permissions on the protected page. Here is what I use for a semi-private calendar (Cookbook:Reminder) on a semi-public intranet homepage:

(:if auth read Reminders:)
[[Reminders?action=edit|edit calendar]] | [[{$Name}?action=logout|logout]]
(:reminder Private.Reminders futuredays=14:)
(:input form action={$PageUrl}:)(:input hidden n {$FullName}:)
To see the calendar please log in:\\
(:input text authid size=10 placeholder="Name":) \\
(:input password authpw size=10 placeholder="Password":) (:input submit value="OK":)
(:input end:)

Instead of (:reminder ...:) you could have (:include ...:).

Note that it is strongly recommended to NOT hide sensitive content inside a conditional in an unprotected page. --Petko July 20, 2018, at 12:04 PM

Is I possible to include older versions of a page? For instance, to show only content up to a certain history revision? Michael

No, currently this is not possible. --Petko August 21, 2015, at 12:21 PM

does basepage with with Cookbook:ThumbList?

basepage does not work for images included through the Cookbook:ThumbList recipe, unfortunately. simon July 30, 2015, at 07:13 PM

Is basepage supposed to apply to the source of attachments in the included text as well?

(In my wiki, page links can be adjusted but attachments remain inaccessible from another group even when setting basepage to the original page location.) --Henning October 15, 2010, at 09:45 AM

No, basepage does not appear to work for Attach: simon July 30, 2015, at 07:13 PM

Are there any solutions to specify the amount of words to be included instead of lines?

My favorable solution would be to have something like (:include PageName#anchor words=30:), which would mean: include 30 words after the anchor #anchor. Is there any implementation of this?

Is it possible to include pages, or lines from pages, without turning them into a block?

eg I am looking for something like the PageList wrap parameter

Is it possible to create a default for a variable?

Likewise, it it possible for a parameter reference? The original question was asked in 2009. It's 2022 now and I wonder if something has been added that could answer these needs. --SteP 2022-09-04

Actually, it was possible to create a default for a {$$variable} in config.php like this:

$IncludeOpt = array(
  'var_name'=>'default value',

Then in a wiki page, if the include directive doesn't have a var_name="something", in the text {$$var_name} will become "default value".

Unfortunately, the parameters lines= or paras=, even if set in $IncludeOpt, will be ignored for the directive (but will be expanded as variables if {$$lines} or {$$paras} are in the included page). --Petko

Displaying the link to not existed Page, similar to existing Group, when including.

The question is difficult to explain, please copy this code to WikiSandbox:

Let's make include of page from other Group, with [[PmWiki]] link inside:
(:include PmWikiRu/WikiSandbox:)
Then this in Local link: [[PmWiki]]

The question is about [[PmWiki]] link to the page, witch does not exists in both Groups. As we see, the link is different on the current page, and inside include. Why? Is it correct behavior?

Finar October 25, 2018, at 09:20 AM

A link [[PmWiki]] without a group in the inner included page is a link to a page in that group, ie [[PmWikiRu/PmWiki]]. If you want to link to [[PmWiki/PmWiki]], either type it, or type [[{*$Group}/PmWiki]] (PmWiki = group of outer including page, PmWiki = group of inner included page). Same for Site.SideBar which is like included page in other groups. --Petko

Displaying Error Messages

Include failure by default does not display error messages. You can test for errors because "Multiple pages may be specified, but only the first available is included".

You can create a default error message by using 2 pagenames to be included. The first page is the page to include, and the second page displays if the first include fails. You can specify any page as an error page.

In this example I use PageTextVariables so I only have to define the pagename once for each page to be included, and Parameter References to display the pagename on the error page.

In page Site.IncludeFailed put:

%red%'''ERROR: An include failed!'''%% PageName='{$$IncludePage}'

In the page doing the including define the pagenames to be included:


Then include the pages:

(:include {$:P1} IncludePage={$:P1} Site.IncludeFailed:)
(:include {$:P2} IncludePage={$:P2} Site.IncludeFailed:)

Error output looks like this:

(:include {$:P1} IncludePage={$:P1} Site.IncludeFailed:)

GNUZoo 11/28/2009

I moved this section to the talk page, because it suggests to use very complicated markups for a simple error message. I'm not sure if anyone will type all this just to display a missing pagename from the template, when it is so easy to re-edit your page and to fix the include link, when it is needed. Now, while I'm sure it is not required to be in the core documentation, I see no problem for it to be here on the talk page. On every wiki installation there is a direct link to this page. --Petko November 29, 2009, at 05:28 PM

Please note also that the core feature is outlined in the main page, so users will find it. (They will, if they read the documentation.) --Petko November 29, 2009, at 05:31 PM

Petko, I cannot believe you or anyone who is using wiki includes would consider this complicated. Do you ever write programs that read a file and not check to see if the file exists? This will make sure that if someone does an include it will work. Someone's include might fail and all they get is missing content that they would not notice in the output. This makes it much more robust. If you really don't care that content you write is accurate, don't use this. I have a higher standard.

Sometimes people don't notice some details. In an ideal world everyone would read everything and follow it exactly. And then we would not need bold text, or color. A detail like this needs more emphasis to be noticed by the average user.

It can be simplified even further:

(:include badpagename IncludePage=badpagename Site.IncludeFailed:)

GNUZoo 11/29/2009

It scales bad, if you have more pages: (:include somegroup.badpagename1 somegroup3.badpagename2 somegroup4.badpagename3 IncludePage="somegroup.badpagename1 somegroup3.badpagename2 somegroup4.badpagename3" Site.IncludeFailed:)

It's also funny that you suggest authors to create and use PageTextVariables, or even write the pagenames twice (a second time in the IncludePage= parameter), when it would be enough to write them once, but correctly. If you type your pagename correctly, your page will be included, if it is not included, check your text, period. An average user wanting to include a page, will notice if the page is not included -- you obviously have lower standards about your average users if you underestimate them like that.

If you really believe it is highly valuable and useful, please feel free to create and support a cookbook recipe. --Petko December 01, 2009, at 12:31 AM

Is there a way to say e.g. the included page should have only 50% width, in order to place a picture next to it? (Was trying to do something with tables, but didnt work - included page and figure are shown on top of each other and not next to each other...)

Like with other text and pictures, you can use the lfloat or rfloat WikiStyles to place elements one next to another.

%lfloat% %%
(:include PmWiki para=3..3:)

Key PmWiki Features

>>rfloat frame width=50pct<<
(:include PmWiki para=3..3:)

Key PmWiki Features

See also Images.

Or use advanced tables, if the included text doesn't contain such tables.

(:table border=0:)
(:cellnr width=50%:)
(:include PmWiki para=3..3:)
(:cell width=50%:)

Key PmWiki Features

This is a talk page for improving PmWiki.IncludeOtherPages.