DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:include

Include Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" yes
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Include another wiki page into the current one

:!: 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 Extension Manager. Refer to Plugins on how to install plugins manually.

If you need support for older version of DokuWiki you can try the 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 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

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.

{{page>[id]&[flags]}}
{{section>[id]#[section]&[flags]}}
{{namespace>[namespace]#[section]&[flags]}}
{{tagtopic>[tag]&[flags]}}
[id] page ID of the page to include; some macros are possible; shortcuts are resolved (:, ., ..) required
[section] limits the included page to a specific section and its subsections optional; default is the whole page , this can be used with namespace (if matches)
[tag]include pages with tag topic tag, requires tag required
[flags] flags delimited by &, see flags optional

Configuration and Flags

The plugin can be configured in the DokuWiki configuration manager available in the admin menu. These settings also affect the 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 discussion plugin)
showlinkbacks linkbacks/nolinkbacks Show/hide number of linkbacks in the page footer (requires the linkback or backlinks plugin)
showtags tags/notags Show/hide tags in the page footer (requires the tag plugin)
showeditbtn editbtn or editbutton/noeditbtn or noeditbutton Show/hide edit buttons (section edit buttons, 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), 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 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 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:

@USER@ username
@NAME@ full name of user
@GROUP@ first group the user belongs to
@YEAR@ 4-digit year
@MONTH@ 2-digit month
@WEEK@ 2-digit ISO week number
@DAY@ 2-digit day
@DATE<expr>@ use a calculated date instead of today in date macros

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

PYEAR previous year
NYEAR next year
PMONTH previous month
NMONTH next month
PWEEK previous week
NWEEK next week
YESTERDAY yesterday's date
TOMORROW tomorrow's date

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

Bugs / Feature Requests

Please report bugs or feature requests at the 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 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:

<WRAP right 35%>
==== FOO ====

Content goes here

</WRAP>

==== BAR ====

FOO contains the </WRAP> end-tag, but not a corresponding start-tag. Thus, if the use of 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:

<WRAP right 35%>
==== BAZ ====

Content goes here

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

==== QUX ====

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 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 bug tracker! :!:

If you miss a comment you've created please have a look at the FAQ section and the 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

User comments

footer.php:

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

replaced to include the real user name in the link:

// author
if ($flags['user']) {
    $author   = $meta['creator'];
    $login = $meta["last_change"]['user'];
    if ($author) {
        $userpage = cleanID($this->getConf('usernamespace').':'.$login);

User Namespace

Hi, I'm using 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 :

        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);
            }
       }

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.

garlik 2011/10/24 14:10

garlik 2011/11/07 11:32 - Summmary : Update the code. will display the right modif author.

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):

{{page>products:sample&firstseconly&link}}

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:

=== Some Section ===
Stuff

====== ======
{{page>somepage}}

- Zioth

Including a paragraph or excerpt from a page

2012-01-25 "Angua"

Just tested with the current version and it works for me. — 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 ItemTable Plugin (along with something to hide the inline text of course. — 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

{{page>people:obama}}

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

blog plugin supports Exclude Feature

— HsinTang 2016-07-26

I created a PR for an exclude option! Testing or adding tests would be appreciated.

sleeping 2020-04-11 07:57

The exclude flag has been merged! :-)

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? — 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

{{page>ID&nouser&nodate&nofooter}}

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 feature request.

— vt306 2017.03.29

Thanks to Michael Hamann for the advice. The 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 here. — 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 options/arguments like in MediaWiki.

Something like this:

page1.txt
Test by {{{1}}}
page2.txt
{{page>:page1|Me}}

And page2 would be parsed into:

Test by Me

hasha2982 2020-08-19 17:12

Sorry, didn't know about the Templater Pluginhasha2982 2020-08-19 17:25
plugin/include.txt · Last modified: 2024-03-13 18:21 by 91.89.222.218

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki