The Include Page Macro allows you to display the contents of one Confluence page in another.
To display part of a page rather than include the whole page, use the Excerpt Macro and the Excerpt Include Macro.
To display a page's contents, you require 'View' permission for that page. This is assigned by a space administrator from the Space Administration screens. See Space Permissions or contact your Confluence space administrator for more information.
 | If the name of the included page is changed after you have written the macro, the page name does not change automatically in the macro. In the event of that happening, you will need to change the page name manually in the macro parameters. |
On this page:
Usage with the Macro Browser
To insert the include page macro into a page using the Macro Browser,
- Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens.
- Next, click the Macro Browser icon
on the editor toolbar. The Macro Browser will open in the middle of the screen.
- In the Macro Browser, type the name of your desired macro into the search box at the top right of the window. Macros with a matching name will appear in the centre pane. Click on the desired macro to see its options screen. Here, you can set the macro parameters then click 'insert' to put the macro into the page.
Once you've found the include page macro, click '
insert' to add it to your page.
Usage with the Wiki Markup Editor
Where 'Sample Include Page' is the title of the page whose contents you want to display:
| What you need to type |
What you will get |
| {include:Sample Include Page} |
Start of sample page content
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. Donec non ipsum. Mauris condimentum, odio nec porta tristique, ante neque malesuada massa, in dignissim eros velit at tellus. Donec et risus in ligula eleifend consectetuer. Donec volutpat eleifend augue. Integer gravida sodales leo. Nunc vehicula neque ac erat. Vivamus non nisl. Fusce ac magna. Suspendisse euismod libero eget mauris.
End of sample page content |
Parameters
Parameters are settings for Confluence macros that allow the user to control their content or presentation. The table below lists relevant parameters for this macro.
Parameter names are displayed differently in the macro browser interface and in wiki markup. Below, parameter names used in the macro browser are indicated in Bold text, while their equivalents in wiki markup are indicated in (bracketed) text. If the latter is not shown, then in wiki markup, the parameter's name should be omitted and only its value should be added immediately after the colon symbol (:).
| Parameter |
Default |
Description |
| Page to Include |
None |
This is the name of the Confluence page you want to include in the current page. If the page you wish to include is located in another space, precede the name of the page with the space key value and ensure that the two values are separated by a colon. For example, DOC:Include Page Macro.
The space key value is case-sensitive. |
Once the desired page is set, there are no further parameters for this macro.
Example
To display contents of a page located in another space
Use the following code, where 'DS' is the spacekey of the other space and 'Confluence Overview' is the name of the page you want to display.
{include:DS:Confluence Overview}
You can include pages from personal spaces using ~username as the space key.
RELATED TOPICS
Embed only part of an internal page
Embed an external page
Working with Macros
Take me back to the Confluence User Guide.
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.
Comments (40)
Mar 30, 2006
Sriram Narayan says:
Are these includes cached as part of regular page caching?Are these includes cached as part of regular page caching?
May 11, 2006
Alan Meban says:
In order to provide users of my wiki space with something to read and review off...In order to provide users of my wiki space with something to read and review offline on the train (!), I created a page which used the {include} macro to create a page made up of multiple other pages, effectively:
{include:chapter 1}
{include:chapter 2}
{include:chapter 3}
...
The export page to PDF option (icon at top right of screen works well for the text - but it omits any images on the included pages. Is this a bug? or a feature?
The individual pages (chapter 1, chapter 2, etc) export to PDF with images ok on their own.
Jun 23, 2006
Ivan Benko says:
Hi Alan, I have created an issue regarding http://jira.atlassian.com/browse/CON...Hi Alan,
I have created an issue regarding http://jira.atlassian.com/browse/CONF-6436
Please add a watch to it for updates.
Thanks,
Ivan
Nov 13, 2006
Adrian Ellis says:
I'd like to have another optional parameter "labels=true" whereby the labels of ...I'd like to have another optional parameter "labels=true" whereby the labels of the included page will be associated with the including page. This would be very useful to manage labels used on included pages in the same way that the
and
macros work with page templates.
In my case I have labels on various distribution notice pages. I would like the labels to be automatically attached to any page that uses the distribution notice so that I can easily check that all content has the correct distribution notice.
I've created an issue here: CONF-7309
In the meantime I can use the
plugin for the same purpose, but it is more complicated and therefore less approachable for others in my organisation to implement themselves.
Nov 15, 2006
Adrian Ellis says:
sorry forgot to escape the macrossorry forgot to escape the macros
Dec 17, 2006
Ankur Gupta says:
is there a way to include a page and all its child pages..rather than doing it o...is there a way to include a page and all its child pages..rather than doing it one by one?
Mar 13, 2008
James Mortimer says:
The include macro, metadata-from macro, and the zone-template-instance macro all...The include macro, metadata-from macro, and the zone-template-instance macro all very simmilar, but subtly different, task. This is not explained in either of their documentation. Perhaps there should be a 'comparison' page?
CONTENT is the content being included, as named in the 'include' macro
INCLUDER is the page that contains the 'include' macro
Syntax
Jun 28, 2007
Bradley Mock says:
Similar to Alan's error above regarding the PDF export: The images are not expo...Similar to Alan's error above regarding the PDF export:
The images are not exported on the include page during an HTML export. The path is correct in the HTML page exported, but no attachments folder is created and the images are not downloaded.
Jun 28, 2007
Agnes Ro says:
Hi Bradely, What version of Confluence are you using? I'm currently working on ...Hi Bradely,
What version of Confluence are you using? I'm currently working on some fixes for both HTML and PDF exports for 2.6 which would also solve this problem.
Agnes.
Jul 11, 2007
Charlie Perry says:
Can I include the contents of a news item from another space? Can't see to get i...Can I include the contents of a news item from another space? Can't see to get it to work.
Jul 11, 2007
David Peterson [CustomWare] says:
As far as I know, this will only include pages, not news items. I haven't actua...As far as I know, this will only include pages, not news items.
I haven't actually tested it, but theoretically you could use the report-info macro from the Reporting Plugin to import a specific news item from another space. Something like this:
{report-info:content:body|source=OTHERSPACE:/2007/07/12/My News Item|render=wiki}Jul 11, 2007
Charlie Perry says:
Thanks. I might just do a bit of cntrl-C cntrl-VThanks. I might just do a bit of cntrl-C cntrl-V
Aug 07, 2007
John Price says:
I sneaked around this problem by marking my whole news item with {excerpt}{excer...I sneaked around this problem by marking my whole news item with {excerpt}{excerpt} and then using
{excerpt-include:blogPost=/2007/08/06/Shopping Update - August 6, 2007}
Worked like a charm.
Aug 06, 2007
Bert Pluymers says:
It would be useful to include an optional parameter noerror. With the current i...It would be useful to include an optional parameter noerror.
With the current implementation, you get a red error message when the page to be included does not exist (or if the user does not have viewing rights). In some instances you would like this to fail more gracefully, by simply not showing any error message.
This could help in making a welcome page different for users with different permissions. Until now I couldn't find any way in doing this elegantly. The show-to and include-excerpt macros both seem to discard some of the layout or links, so they cannot be used in that context either.
It would be nice to be able to use
{include:page-with-links-that-should-not-appear-for-group-B|noerror=true}to include links from a page to which group B does not have viewing permissions, without showing an error message to group B.
Aug 06, 2007
Sarah Maddox [Atlassian Technical Writer] says:
Hallo Bert Many thanks for your support. There is an existing JIRA issue CONF-5...Hallo Bert
Many thanks for your support. There is an existing JIRA issue CONF-5436 which may suit your needs. You can vote for the issue, to increase its visibility. You can also log your own suggestions and requests on JIRA.
Cheers – Sarah
Aug 08, 2007
Bert Pluymers says:
Done. Thanks for bringing the JIRA issue to my attention. BertDone. Thanks for bringing the JIRA issue to my attention.
Bert
Aug 06, 2007
David Peterson [CustomWare] says:
Hi Bert, I'm curious to know what problems you're having with the {show-to} mac...Hi Bert,
I'm curious to know what problems you're having with the {show-to} macro. The intent is that it basically displays the content or doesn't.
Aside from that, another possibility is to use the {report-info} macro from the Reporting Plugin:
{report-info:content:body|render=wiki|source=page-with-links-that-should-not-appear-for-group-B}Either way, I am interested in any problems with show-to...
Aug 08, 2007
Bert Pluymers says:
Hi David, the problem with show-to is the following: Using only show-to is n...Hi David,
the problem with show-to is the following:
I tried using the report-info macro, but this macro produces some very strange errors when trying to include a page where you don't have permissions to. In some cases I ended up with a blanc page, only containing the global logo and the page title. No breadcrumbs, no navigation pane,... In other cases the header right above the include-report macro is being displayed about 40 times after which a java stack overflow is displayed.
Aug 08, 2007
David Peterson [CustomWare] says:
Ok. Thanks for that. Your first point is a known issue/by design, but fair enoug...Ok. Thanks for that. Your first point is a known issue/by design, but fair enough for your situation. The second point is rather odd. What do you mean by the "higher permission group"? Can you post a fuller example of your markup code? Perhaps as a JIRA issue, so we don't clog the comments?
And with regards to the report-info macro, I'll admit I hadn't actually tried specifying a restricted page directly before...I'll have to investigate that one.
Aug 09, 2007
Bert Pluymers says:
Hi David, as you suggested I created a Jira issue regarding the above mentioned...Hi David,
as you suggested I created a Jira issue regarding the above mentioned problems with the show-to macro in combination with the include macro.
Bert
Aug 08, 2007
James Mortimer says:
Bert, Take a look at the 'edit-include' user macro for a fairly simple way to...Bert,
Aug 09, 2007
Bert Pluymers says:
Thanks for the tip James, I will look into it.Thanks for the tip James, I will look into it.
Sep 06, 2007
Ville Valtasaari says:
Is the source-code for the "include page"-macro available somewhere. I'd like to...Is the source-code for the "include page"-macro available somewhere. I'd like to look into ajaxifying it as we're having major performance issues w. our Confluence after upgrading from 2.2.9 to 2.5.7 (apparently the new permissions checking system is more cumbersome than the old).
Dec 27, 2007
Anonymous says:
I currently have 6 separate templates that collect user input. All 6 of these te...I currently have 6 separate templates that collect user input. All 6 of these templates are under a parent page. I want the information from the child pages (collected via templates) to be displayed on the parent page.
Using the include tag, this works, but I lose all formatting and it includes as blocks of text.
Any way around this?
Jan 01, 2008
Choy Li Tham says:
Hi, Please raise a support ticket at our support system: https://support.atlass...Hi,
Please raise a support ticket at our support system: https://support.atlassian.com. Hence, we can follow up this issue from there. Thanks.
Regards,
Choy Li
Jan 08, 2008
James Mortimer says:
have you tried using the zone-template-instance macro, from the Zones Plugin, wi...have you tried using the zone-template-instance macro, from the Zones Plugin, without any parameters. it works like include, but renders AFTER the inclusion, rather than before.
Not sure what you mean by templates that collect user input, so they might not work with inclusions or zones.
Mar 12, 2008
David Dembo says:
FYI just came up with a hack that you can use to explicitly mark off sections th...FYI just came up with a hack that you can use to explicitly mark off sections that should not be included (full credit goes to David Peterson for the trimp and render macros though!).
#macro(trimp $xhtml) ## remove leading <p> and trailing </p> #if($xhtml.startsWith("<p>",0) && $xhtml.endsWith("</p>")) #set($len=$xhtml.length()-$generalUtil.convertToInteger(4)) #set($xhtml=$xhtml.substring(3,$len)) #end$xhtml#end #macro(render $wiki) #set($globalHelper=$action.getGlobalHelper()) #if($content)## i. e. we render a normal page #set($renderer=$globalHelper.getWikiStyleRenderer()) #set($context=$content.toPageContext()) #set($xhtml=$renderer.convertWikiToXHtml($context, $wiki).replaceAll("\n|\r","")) #else## we are e. g. in Global Template Preview #set($xhtml=$globalHelper.renderConfluenceMacro($wiki).replaceAll("\n|\r","")) #end#trimp(${xhtml})#end #set ($qString = $req.getQueryString()) #set ($titleStart = $qString.indexOf("title=")+6) #set ($nextAmpIndex = $qString.indexOf("&",$titleStart)) #if ($nextAmpIndex == -1) #set ($titleEnd = $qString.length()) #else #set ($titleEnd = $nextAmpIndex) #end #set ($reqTitle = $qString.substring($titleStart, $titleEnd)) #if ($content.title == $reqTitle)#render($body)#endOn a page with "XXX{no-include}YYY{no-include}ZZZ" you will see "XXXYYYZZZ" - but if you then include that page, you will only see "XXXZZZ" on the including page.
The code can probably stand to be neatened somewhat, but it works.
Hope somebody finds this useful!
Mar 13, 2008
David Peterson [CustomWare] says:
Thanks for the credit, but I don't think gave you that tip David. Nice though......Thanks for the credit, but I don't think gave you that tip David. Nice though...
Mar 13, 2008
James Mortimer says:
a) very nice b) I also did not give you that tip, but render and trimp are my c...a) very nice
b) I also did not give you that tip, but render and trimp are my contributions, Render any text from a user macro, based on initial code in comments on sectional editing from Mark Michaelis (edit-include user macro, http://jira.atlassian.com/browse/CONF-2761)
#set ($qString = $req.getQueryString()) #set ($titleStart = $qString.indexOf("title=")+6) #set ($nextAmpIndex = $qString.indexOf("&",$titleStart)) #if ($nextAmpIndex == -1) #set ($titleEnd = $qString.length()) #else #set ($titleEnd = $nextAmpIndex) #end #set ($reqTitle = $qString.substring($titleStart, $titleEnd)) #if ($content.title == $reqTitle)$body#endNote: you may want to use $!body to exclude printing "$body" with an empty body.
Mar 13, 2008
James Mortimer says:
I suspected that this would only work with titles that do not contain spaces or ...I suspected that this would only work with titles that do not contain spaces or special characters. using $generalUtil.urlEncode() fixed this so that it works for spaces and special characters in the title.
## only display the contents of this macro body if the page is being viewed directly. Thus, exclude the content from include, edit-include, metadata-from, reporting plugin, checklist plugin, etc, but not zone-template-instance or excerpt-include ## #set ($qString = $req.getQueryString()) #set ($titleStart = $qString.indexOf("title=")+6) #set ($nextAmpIndex = $qString.indexOf("&",$titleStart)) #if ($nextAmpIndex == -1) #set ($titleEnd = $qString.length()) #else #set ($titleEnd = $nextAmpIndex) #end #set ($reqTitle = $qString.substring($titleStart, $titleEnd)) #if ($generalUtil.urlEncode($content.title) == $reqTitle)$!body#endMar 13, 2008
David Dembo says:
Whoops, I don't know what I was smoking when I said David Peterson... I must've ...Whoops, I don't know what I was smoking when I said David Peterson... I must've looked at the wrong tab. Sorry James!
Thanks for the improvements too - as I said it could've definitely used some improvements. The issue was indeed the <p> tag... I just cut/pasted the code from your page since I didn't have a lot of time to have a think about the mechanics (I needed the no-include functionality for another task that I was working on).
I've also created a page in the extension space as you suggested.
Mar 13, 2008
James Mortimer says:
Please add something to this effect to the yellow warning box on the 'include pa...Please add something to this effect to the yellow warning box on the 'include page' documentation to elaborate on the caveats of using this macro.
Contrary to what one might expect, the 'include' page macro does not:
Apr 07, 2008
Anonymous says:
It's a critical omission that the macro does not update the name of the page if ...It's a critical omission that the macro does not update the name of the page if included page is renamed or moved. It should have behaved exactly like wiki link which never breaks on rename or move, because the included page in fact has to be a valid wiki link.The fact that
Feb 06
Justin Permar says:
I emphatically agree. This is broken in Confluence 2.10. Is there any Jira issue...I emphatically agree. This is broken in Confluence 2.10. Is there any Jira issue for this? I couldn't find one.
Feb 09
Giles Gaskell [Atlassian Technical Writer] says:
Hello Justin, Thanks for flagging up this issue. I've reported this bug as JIRA...Hello Justin,
Thanks for flagging up this issue. I've reported this bug as JIRA issue CONF-14464.
Best regards,
Giles Gaskell
Technical Writer
ggaskell@atlassian.com
ATLASSIAN - http://www.atlassian.com
Apr 08, 2008
Redcosmos King says:
Not ture. Renaming included page should have been updated in the including page....Not ture. Renaming included page should have been updated in the including page. This was a bug that was fixed in 1.3 http://jira.atlassian.com/browse/CONF-1354. Apparently it's broke now again. It needs to be fixed. We rely heavily on include macro.
Apr 23, 2008
Mark says:
Can the macros that are in the INCLUDED page reference the includer page/space r...Can the macros that are in the INCLUDED page reference the includer page/space rather than the included page/space?
I want to build a centrally shared Table of Contents page that has standard info for each space's home page
For ex: if I build a page called SHARED TOC and it has these macros in it:
{children:space=@self} {recently-updated:space=@selfWhen I go to share that to all other spaces, the info shown is from SHARED TOC/space, not the current page/space.
Can this be modified?
Jun 17
Benson Ayabe says:
I have a similar need for on-line documentation. I have a generic set of p...I have a similar need for on-line documentation. I have a generic set of pages, each representing a section of an online document. The intent is to include these generic sections into a project-specific version of the document where the project does not depart from the norm. For sections that do depart from the norm, the generic section of the online document is replaced by a project-specifc section. This is all being done using the {include} macro.
What I'd really like to do to enhance these generic sections is to be able to reference the project name that is defined as custom metadata in a project plan. But the metadata from the includer page does not get used by the included page. On the includer page, I have:
h1. Project Plan - {metadata-from:Product Full Name} {metadata-list:|orientation=horizontal} || Product Full Name | Jumping Jack Flash | {metadata-list} {excerpt-include:CM Plan - Introduction\|nopanel=true}On the included page, I have:
h2. +Introduction+ h3. Purpose This document contains the Project Plan for {metadata-from:Product Full Name}.The referencing of metadata on the includer page works just fine. It doesn't work in the included page.
This all appears to go back to the included page not being rendered in the context of the includer page. Like it was said earlier, having the included page rendered in the context of the includer page would make life easier in terms of supporting many projects with a minimal number of changes for common text. It's an issue of ease of maintenance.
If anyone knows of a work-around, please let me know. Thanks in advance.
Mar 13
Geoffroy Noel says:
Hi, Is there an easy way to include a page from another space while keeping the...Hi,
Is there an easy way to include a page from another space while keeping the context of the calling space while it is processed?
Basically, our global page layout includes a page for the left hand side navigation. This page is contained in a space S1. This page contains a tree macro with a search box. However, practically it doesn't work because, when we display a page in space S2, the scope for the tree and search is still S1.
We could copy the navigation page under each space but that would make our life harder:
-we then need to copy the navigation page manually each time we create a new Space
-we can't modify the navigation page across multiple spaces in one go. We would have to go through each nav page and make the same modification.
Hence the need for a way to write contents and macro in a single location and then share it while preserving the context of the caller. An additional argument to Include Page could be a solution
This feature seems so useful that I'd be surprised there's no way to do that with Confluence.
Any suggestion for workarounds would be greatly appreciated!
Thanks
Mar 29
Azwandi Mohd Aris says:
Hi Geoffroy, You can directly specify the {pagetree} macro in the custom "Page ...Hi Geoffroy,
You can directly specify the {pagetree} macro in the custom "Page Layout". If you follow the instructions on Adding a Navigation Sidebar, replace the line:
#includePage($helper.spaceKey "TreeNavigation")with
$helper.renderConfluenceMacro("{pagetree}")This will not require you to add a "TreeNavigation" page in every space. Hope that helps!"
Cheers,
Azwandi
Add Comment