DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Include Plugin ======

---- plugin ----
description: Include another wiki page into the current one
author     : Dokufreaks (previous authors: Michael Hamann, Gina Häußge, Michael Klier, Esther Brunner)
email      : freaks@dokuwiki.org
type       : syntax, helper
lastupdate : 2022-01-23
compatible : Greebo, Frusterick Manners, Hogfather, Igor
depends    : tag
conflicts  : mediasyntax, PhotoGallery
similar    : wst
tags       : include, embed

downloadurl: https://github.com/dokufreaks/plugin-include/tarball/master
bugtracker : https://github.com/dokufreaks/plugin-include/issues
sourcerepo : https://github.com/dokufreaks/plugin-include/
donationurl: 
----

:!: The 2018-11-29 release fixes a security issue where ACLs were ignored for pages in namespace includes with DokuWiki version Greebo. If you rely on ACL checks in namespace includes or allow edits from users who must not see all pages, please upgrade ASAP! :!:

This is a handy plugin with which you can include another wiki page into the current one. Just including certain sections of a page or even whole namespaces is supported, too.

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

If you need support for older version of DokuWiki you can try the [[https://github.com/downloads/dokufreaks/plugin-include/plugin-include-2009-11-27.tgz|2009-11-27]] version of the include plugin, but please note that this old version has known bugs. If you need support for older versions of DokuWiki in the current include plugin version please open a feature request in the [[https://github.com/dokufreaks/plugin-include/issues|issue tracker]].

===== Examples =====

''%%{{page>wiki:syntax#Tables}}%%'' will include the section about tables of the syntax page.

''%%{{namespace>project_foo}}%%'' will include all pages in the ''project_foo'' namespace.

''%%{{page>blog:mypage&tags&comments}}%%'' will include the page ''blog:mypage'' and show the tags from the [[tag]] plugin and the number of comments from the [[discussion]] plugin. Both plugins need to be installed for this example.

''%%{{tagtopic>testtag}}%%'' will include all pages with the tag ''testtag'', the [[tag]] plugin needs to be installed for this example.

===== Syntax =====

Simply enclose the ID of the page to be included in double curly brackets:

{{page>[id]&[flags]}}
  {{section>[id]#[section]&[flags]}}
  {{namespace>[namespace]#[section]&[flags]}}
  {{tagtopic>[tag]&[flags]}}

The plugin offers four syntaxes, ''%%{{page>...}}%%'' , ''%%{{section>...}}%%'' , ''%%{{namespace>...}}%%'' and ''%%{{tagtopic>...}}%%''.

Section is aimed more at including sections, page at including whole pages and namespace at including whole namespaces. Tagtopic includes all pages with a ''tagtopic'' ''tag''.

===== Configuration and Flags =====

The plugin can be configured in the DokuWiki configuration manager available in the admin menu. These settings also affect the [[plugin:blog]] plugin which uses the include plugin to generate the blog page. For most settings there are flags that allow to override the setting. Some features are only available as flag.

^ Configuration option  ^ Flags                                                            ^ Description                                                                                                                                                                                                                                                                                                                                                                      ^
^ ''noheader''          | ''noheader''/ (''show'')''header''                               | Don't display the header of the inserted section                                                                                                                                                                                                                                                                                                                                 |
^ ''firstseconly''      | ''firstsec''(''tion'')''only''/ ''fullpage''                     | Display only the first section of the included page                                                                                                                                                                                                                                                                                                                              |
^ ''readmore''          | ''readmore''/''noreadmore''                                      | Show "read more" link in case of firstsection only                                                                                                                                                                                                                                                                                                                               |
^ ''showtaglogos''      | -                                                                | Show/hide an image for the first tag (if the page has tags)                                                                                                                                                                                                                                                                                                                      |
^ ''showfooter''        | ''footer''/''nofooter''                                          | Show/hide page footer below the included page                                                                                                                                                                                                                                                                                                                                    |
^ ''showlink''          | ''link''/''nolink''                                              | Makes the first headline of a included page/section a link to the included page/section                                                                                                                                                                                                                                                                                          |
^ ''showpermalink''     | ''permalink''/ ''nopermalink''                                   | Show/hide a permalink to the included page in the page footer                                                                                                                                                                                                                                                                                                                    |
^ ''showdate''          | ''date''/''nodate''                                              | Show/hide creation date of the page in the page footer                                                                                                                                                                                                                                                                                                                           |
^ ''showmdate''         | ''mdate''/''nomdate''                                            | Show/hide modification date of the page in the page footer                                                                                                                                                                                                                                                                                                                       |
^ ''showuser''          | ''user''/''nouser''                                              | Show/hide user name of the page creator in the page footer                                                                                                                                                                                                                                                                                                                       |
^ ''showcomments''      | ''comments''/''nocomments''                                      | Show/hide number of comments in the page footer (requires the [[plugin:discussion]] plugin)                                                                                                                                                                                                                                                                                      |
^ ''showlinkbacks''     | ''linkbacks''/''nolinkbacks''                                    | Show/hide number of linkbacks in the page footer (requires the [[plugin:linkback|linkback]] or [[plugin:backlinks2]] plugin)                                                                                                                                                                                                                                                     |
^ ''showtags''          | ''tags''/''notags''                                              | Show/hide tags in the page footer (requires the [[plugin:tag]] plugin)                                                                                                                                                                                                                                                                                                           |
^ ''showeditbtn''       | ''editbtn'' or ''editbutton''/''noeditbtn'' or ''noeditbutton''  | Show/hide edit button below the included page                                                                                                                                                                                                                                                                                                                                    |
^ ''doredirect''        | ''redirect''/''noredirect''                                      | Redirect back to original page after an edit                                                                                                                                                                                                                                                                                                                                     |
^ ''usernamespace''     | -                                                                | Namespace for user pages (see ''showuser'' configuration) (default ''user'')                                                                                                                                                                                                                                                                                                     |
^ ''doindent''          | ''indent''/''noindent''                                          | Indent included pages relative to the section of the page they get included in                                                                                                                                                                                                                                                                                                   |
^ ''linkonly''          | ''linkonly''/''nolinkonly'' or ''include_content''               | Display only a link instead of the whole page content                                                                                                                                                                                                                                                                                                                            |
^ '' title''            | ''title''/''notitle''                                            | Show the title instead of the page id                                                                                                                                                                                                                                                                                                                                            |
^ ''pageexists''        | ''pageexists''/ ''nopageexists''                                 | Only list page ids of existing pages (see ''existlink'')                                                                                                                                                                                                                                                                                                                         |
^ -                     | ''existlink''                                                    | Display a link and do so only if page page-id exists (combination of ''linkonly'' and ''pageexists'')                                                                                                                                                                                                                                                                            |
^ ''parlink''           | ''parlink''/''noparlink''                                        | (Don't) put the link into a paragraph environment (for inline lists)                                                                                                                                                                                                                                                                                                             |
^ ''order''             | ''order=OPTION''                                                 | Ordering criteria for namespace includes, possible options: page ID (''id''), title (''title''), date created (''created''), date modified (''modified''), [[plugin:indexmenu#metadata_tag_syntax|indexmenu sort order]] (''indexmenu''), custom sort order using the ''%%{{include_n>[number]}}%%'' on the pages that are included similar to the indexmenu tags (''custom'').  |
^ ''rsort''             | ''rsort''/''sort''                                               | Reverse the sort order in namespace includes.                                                                                                                                                                                                                                                                                                                                    |
^ ''depth''             | ''depth=DEPTH''                                                  | The maximum depth of subnamespaces of which pages are included in namespace includes, default is ''1'' for only the specified namespace, ''0'' is for unlimited depth.                                                                                                                                                                                                           |
^ -                     | ''inline''                                                       | Don't close/open sections when including a page. This flag should be used when the include syntax is used inside other syntax elements like lists or tables or inside other plugin syntax.                                                                                                                                                                                       |
^ -                     | ''beforeeach=ENTITY''/ ''aftereach=ENTITY''                      | Display an [[:entities|entity]] before/after each included page. The entity is printed outside the section/include environment, this is mainly for adding custom HTML code (when the text isn't recognized as entity it is directly displayed but escaped so you can't directly use HTML code here).                                                                             |
^ ''safeindex''         | -                                                                | Don't index metadata of included pages that are non-public. This can cause problems with other plugins that use the metadata index and can be safely disabled in wikis where the permissions of the included pages match the permissions of the parent pages.                                                                                                                    |
^ -                     | ''exclude=/REGEX/''                                                | Regular expression to exclude certain pages, will match on full page ID. E.g. to exclude ''ns:page_name'' use ''/ns:page_name/'' as value. Use a [[https://regex101.com/|regex tester]] to debug complicated patterns.                                                                                                                                                           |

Examples:

{{page>concept&firstseconly&footer}}
  {{page>mypage&noindent}}
  {{namespace>myns&order=modified}}
  {{namespace>myns&exclude=/myns:subns:.+|myns:page/}}

===== Macros =====

Simple macros are possible to serve a page on a per user or per date base. These are:

<expr> in **''@DATE<expr>@''** can be one of:

Examples:

{{page>@MONTH@:@DAY@:birthdays}}
includes the page ''birthdays'' in namespace <month>:<day>: eg. ''10:15: birthdays'' for the 15th of october.

{{page>@USER@:message}}
includes the page ''message'' from the namespace <user> of the logged in user

{{page>foo@DATENWEEK@@YEAR@:@WEEK@}}
includes the page <weekno> from the namespace ''foo<year>'' with next week's date  e.g.  foo2012:01 for the 27th of december 2011

===== Demo =====

FIXME There is currently no demo site available.

Use of the plugin is shown in this video here: https://www.youtube.com/watch?v=6RO8TSZBedU&t=8m47s
FIXME Video not available (2021-03-20)
===== Development =====

=== Change Log ===

{{rss>https://github.com/dokufreaks/plugin-include/commits/master.atom date}}

=== Bugs / Feature Requests =====

Please report bugs or feature requests at the [[https://github.com/dokufreaks/plugin-include/issues|Bug tracker]].

=== Known Bugs and Issues ===

There are currently no known bugs and issues for which no workarounds exist (see [[#FAQ]]).

===== FAQ =====

==== The include plugin breaks the wrap and folded (and similar) plugins when used inside them ====

This can be solved by using the ''inline'' flag of the include plugin. This mode strips all section from the included page and should solve issues with invalid HTML and thus no longer working wrap and folded plugins. This also solves problems with invalid HTML code when the include plugin is used inside tables or other syntax environments. When the page contains headers this might look strange depending on the template.

=== Addendum  ===

If you are using the [[plugin:wrap|Wrap Plugin]] on both the page you are using the ''%%{{section>target&inline}}%%'' from and the page //target//, you need to make sure any pair of WRAP tags on //target// are either entirely within the included section or entirely outside of the section.  For instance, including the FOO section into another page might break the other page:
<code>
<WRAP right 35%>
==== FOO ====

Content goes here

</WRAP>

==== BAR ====
</code>

FOO contains the ''%%</WRAP>%%'' end-tag, but not a corresponding start-tag.  Thus, if the use of [[plugin:include]] is within a WRAPed block, that WRAP block will be ended early.

The simplest solution is to never use WRAP on both pages, only on included pages or only on pages that include others -- however, that's not very realistic or useful.  The other (somewhat brittle) solution is to make the section on //target// end before the WRAP close tag.  You can do this by inserting a dokuwiki section header (at the same level) before the close tag, but after the section's content.  However, I've not been able to determine if this is an intended behavior of dokuwiki, or if this is undocumented behavior and therefore subject to change at any time.

So, to make the above example work correctly, it should look like this:
<code>
<WRAP right 35%>
==== BAZ ====

Content goes here

==== ====
</WRAP>

==== QUX ====
</code>

Now ''%%{{section>whatever#BAZ}}%%'' will work fine.

==== Is it possible to include the same page twice? ====

Yes, this is possible since the 2011-01-01 version and hasn't been possible before. But you can't include the same page again inside a page in order to avoid endless recursion (and things like page1 > page2 > page1 doesn't work, too).

==== Does the include plugin respect ACLs of the included pages? ====

The include plugin tries its best to respect ACLs and it should work under normal circumstances. Whenever the view permissions of included pages change the cache is purged and the included pages are adapted according to the current permissions. Due to limitations in the caching system this might fail if a page is accessed very frequently with changing permissions. If this is an issue for you you can disable caching of the affected pages using the ''%%~~NOCACHE~~%%'' syntax. As always there is no guarantee that everything works as expected, please test if everything works and report a bug if you should notice anything unexpected.

As of version 2012-11-24, there is a new security feature called ''safeindex'' that is turned on by default, it's purpose is to prevent the indexer from indexing metadata of included pages that aren't public. That way links that are in protected pages won't be visible as link of a public page in the backlinks list.

==== Why does the include plugin first close the previous section and opens it again afterwards? ====

This is done because if there are headers in the included page they will close the current section. As the include plugin has its own container div this would produce strange results and possibly invalid HTML. You can use the ''inline'' flag in order to avoid this (but then also all sections of the included page are removed).

==== Has the include plugin feature XYZ/when will you implement XYZ? ====

The include plugin has many feature and is very flexible and I'm willing to add more features if they fit in the general purpose of the include plugin. However there is no guarantee that I will implement a certain feature at a certain time, this depends completely on my available time and my mood. You can add your wishes to the issue tracker.

==== How to avoid including of whole page content if section does not exist? ====

If using the flag ''firstsectiononly'' in addition, could be one solve. At least in regard of avoiding very large content to be displayed. If adding a header at the source page and using tools like the [[plugin:hiddenheader]] it might solve things at the source page, but in it's case seems to conflict and break certain include flag-tasks.
===== Discussion =====

:!: Please don't report any bugs or feature requests here but instead use the [[https://github.com/dokufreaks/plugin-include/issues|bug tracker]]!  :!:

If you miss a comment you've created please have a look at the [[#FAQ]] section and the [[https://github.com/dokufreaks/plugin-include/issues|issue tracker]], I might have moved them there, if you can't find a bug report anymore that bug should be solved, please try the current version and report it again if it still doesn't work.

==== Discussions in DW-forum ====

* [[https://forum.dokuwiki.org/thread/16154|plugin:include / Hide current page contents once user logs in]]
  * [[https://forum.dokuwiki.org/thread/16235|include plugin: development in direction to use it as a kind database tool]], feature inspirations.

==== User comments =====

**footer.php**:
<code php>
// author
if ($flags['user']) {
    $author   = $meta['creator'];
    if ($author) {
        $userpage = cleanID($this->getConf('usernamespace').':'.$author);
</code>

replaced to include the real user name in the link:

<code php>
// author
if ($flags['user']) {
    $author   = $meta['creator'];
    $login = $meta["last_change"]['user'];
    if ($author) {
        $userpage = cleanID($this->getConf('usernamespace').':'.$login);
</code>
=== User Namespace ===
Hi, I'm using [[plugin:userpagecreate|userpagecreate]] plugin's to create user's namespace instead of user's page. Then, to link correctly the include's page with his last member who edit it, i rewrite the previous lines like this :
<code php>
        if ($flags['user']) {
            $login = $meta['last_change']['user'];
            $author = $auth->getUserData($login);
            $author = $author['name'];
            if ($author && $login) {
                if (strstr($this->getConf('usernamespace'), '@USER@')) {
                    $userpage = cleanID(str_replace('@USER@', $login, $this->getConf('usernamespace')));
                } else {
                    $userpage = cleanID($this->getConf('usernamespace').':'.$login);
                }
                resolve_pageid(getNS($ID), $userpage, $exists);
                $class = ($exists ? 'wikilink1' : 'wikilink2');
                $link = array(
                        'url'    => wl($userpage),
                        'title'  => $userpage,
                        'name'   => hsc($author),
                        'target' => $conf['target']['wiki'],
                        'class'  => $class.' url fn',
                        'pre'    => '<span class="vcard author">',
                        'suf'    => '</span>',
                        );
                $xhtml[]    = $renderer->_formatLink($link);
            }
       }
</code>
and change my conf into :
  $conf['plugin']['include']['usernamespace'] = 'user:@USER@:start';

standard configuration still works.
  $conf['plugin']['include']['usernamespace'] = 'user:';
  
If the **@USER@** wildcard is using, replace it by the login name, otherwise, use the standard include's plugin rule.

--- [[user>garlik|garlik]] //2011/10/24 14:10//

--- [[user>garlik|garlik]] //2011/11/07 11:32// - Summmary : Update the code. will display the right modif author.

==== showlink vs link flag ====
When including a page, the flag to make the first heading a link is ''link'', not ''showlink''. This confused me at first because I assumed the flags would have the same names as the configuration options. Example (displays the first section of a product page, with the page heading as a link):
<code>
{{page>products:sample&firstseconly&link}}
</code>

==== Controlling header size in included pages ====
By default, the headers in included pages start one level lower than the last header in the current page. For example, if the section before the include is a level-three header, then a level-6 header in the included page will become a wimply little level-2.

If you want higher-level headers, you can trick the plugin by putting an empty header above the include. In the following example, a level-6 header in the included page will show up as level-5:

<code>
=== Some Section ===
Stuff

====== ======
{{page>somepage}}
</code>
- [[user>Zioth|Zioth]]

==== Including a paragraph or excerpt from a page ====

See the [[plugin:hiddenheader|Hidden Header plugin]]. -[[user>Zioth|Zioth]]

==== 2012-01-25 "Angua" ====
Just tested with the current version and it works for me.
 --- [[user>renux|renux]] //2012/02/10 12:44//

==== Include from same page? ====
Using it on my knowledge wiki and it works well. However, I'd like to be able to include a section from the current page - for use with the [[plugin:itemtable|ItemTable Plugin]] (along with something to hide the inline text of course.
 --- [[user>TotallyInformation|Julian Knight]] //2012-03-23//

Does it still work? Can't make it on my wiki page.

--- //Piotr// //2017-10-04//
==== Align Feature ====
It'll be great to be able to align included pages. Because a lot of people are using this feature for infobox purposes and some would love to be able to control the alignment of the <code>{{page>people:obama}}</code> using the core syntax by adding spaces before of after the syntax.

--- James // 2014-05-13 20:38//

==== Exclude Feature ====

It would be nice, if there would be an "exclude" option. When we use the ''namespace'' feature, we don't want certain pages in the included in the resulting page: for example exclude "sidebar" or "start".

--- Manuel // 2014-10-30 02:42//

I would appreciate that feature too.

--- Florian // 2015-07-18 18:43//

Same here, the possibility of the exclusion of listed namespaces would be much appreciated.

--- Tommy // 2016-2-19 21:18//

I totally agree.

---- Chris // 2016-2-21 09:12//

[[plugin:blog|blog plugin]] supports **Exclude Feature **

--- HsinTang // 2016-07-26 //

I created [[https://github.com/dokufreaks/plugin-include/pull/243|a PR]] for an exclude option! Testing or adding tests would be appreciated.

--- [[user>sleeping|sleeping]] //2020-04-11 07:57//

The ''exclude'' flag has been merged! :-)

--- [[user>sleeping|sleeping]] //2020-04-16 19:28//

==== Empty Section ====

We are using the plugin a lot for technical documentation. If we include a named section (#title), and that section doesn't exist, the plugin includes the whole page. This really annoying. Would it be possible to change the behavior so that if a section doesn't exist it doesn't include anything (the same as when a page doesn't exist), please?

--- Simon // 2015-02-02 14:50 //

>Just thought of asking about this issue. Is there any possibility to avoid that?  --- [[user>Samana Johann|Samana Johann]] //2018-08-20 19:45//

==== No Other data ====

I love this plugin but I have a question. How do I completely remove all other data included, such as user, mdate, etc.? If I do them as individual flags I still see the grey bar under the included content. There must be a flag that just excludes all the content, right? Am I just missing it somehow?

Thanks!

--- Max //2017.03.21//

Hi there, I think you are looking for <code>{{page>ID&nouser&nodate&nofooter}}</code>

==== Namespace lists using &linkonly and &beforeeach/&aftereach ====

I've been trying to format a list of pages generated using namespace> with &linkonly - ideally as a simple unordered list. I'm adding this paragraph to help others searching for help because it took me several hours to find out that it is not possible and this is a known issue logged as a [[https://github.com/dokufreaks/plugin-include/issues/130|feature request]].

--- vt306 //2017.03.29//

Thanks to Michael Hamann for the advice. The [[doku>plugin:pagequery|pagequery]] plugin is the solution for this.

--- vt306 //2017.04.06//

==== Option to pass revision of main page to includes pages ====

We are currently using DokuWiki for technical documentation. Within DokuWiki we use the 'date_at' function (https://www.dokuwiki.org/date_at) to go back to an old revision to see which version of the page a customer recieved. It would be very usefull if the included pages would honour the revision of the main page. To clarify: if the main page is shown at a specific revision, the included pages should also be shown at the last revision before the date of the main page. Would something like that be possible to incorporate?

Thanks in advance!
Ruud

==== Translations ====

>If it is of use, a paticular Translation of the Plugin's info page into German can be taken from [[http://accesstoinsight.eu/doku.php?id=external:index#include_plugin|here]]. --- [[user>Samana Johann|Samana Johann]] //2018-08-20 12:11//

==== Display search results on a page? ====
Hi, I was wondering if it is possible to display the search result of a term or phrase on a page?

- OYMYO

==== Options/arguments ====

I think it would be cool if this plugin supported [[https://www.mediawiki.org/wiki/Help:Templates#Parameters|options/arguments like in MediaWiki]].

Something like this:

And ''page2'' would be parsed into:

Test by Me

--- [[user>hasha2982|hasha2982]] //2020-08-19 17:12//

> Sorry, didn't know about the [[plugin:templater|Templater Plugin]] --- [[user>hasha2982|hasha2982]] //2020-08-19 17:25//

Please fill all the letters into the box to prove you're human. Q X᠎ R F X Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International