The {incoming-links} macro displays a customisable list of incoming links for the current page...
There are many occasions when it's useful to know what other pages link to the current page as they will almost always be related to the current page and therefore be of some use to the person viewing the page.
This macro allows you to add a customisable list of incoming pages that can also be filtered to specific Spaces and content types, etc.
Usage
The macro has the following parameters:
{incoming-links:mode=[list,flat]|separator=[brackets,braces,parens,pipe]|parent=[Parent Page]
|ancestor=[Ancestor Page]} No links available {incoming-links}
Parameters
Parameter
Required
Default
Notes
mode
list
The type of output, either:
list (default) - a bullet list of incoming links
flat - a flattened (single line) list of incoming links
style
icons
The style of bullet point to use for each item when using the list type:
none – no marker
icons – the default style showing icons to depict content type
Any valid CSS style (see the Styles tab above)
separator
brackets
When using the flat mode, this parameter defines how individual items will be separated from one another:
brackets (default) – items will be enclosed in \square \brackets
braces – items will be enclosed in {curly} {braces}
parens – items will be enclosed in (normal) (brackets)
pipe – items will be separated | by | pipes
Anything else – a custom separator
spaces
By default, incoming links from any space that the user has access to will be listed. You can use this parameter to filter the links to one or more spaces (if using more than one space, separate the space keys with commas).
types
All Types
By default, all content types that link to the current page will be listed. You can however specify a comma separated list of specific comment types to include. The available content types are:
page – pages
blogpost – news articles (blog posts)
comment – comments (does not appear to work due to a bug in Confluence)
spacedescription – the description for a space
userinfo – user profile
mail – mail archive message
parent
Any
If you want to restrict the list of incoming links to a page with a specific parent page, use this parameter.
ancestor
Any
If you want to restrict the list of incoming links to a page with a specific ancestor page (ie. a page further up the site hierarchy), use this parameter to specify the ancestor page.
excerpt
false
Set to true to display excerpts for the incoming link (create excerpts using the excerpt macro).
sort
natural
Specify the sort order of the displayed links:
natural (default) – A natural sort on the title (eg. 1, 2, 3, .. 10, etc)
bitwise – A bitwise sort on the title (eg. 1, 10, 2, 3, ... etc)
creation – Sorted by creation date of the content
modified – Sorted by the date the content was last modified
first
Limit the list of incoming links to the first x links, eg. first=5 will only show a maximum of 5 links
reverse
false
If set to true, the sort order of the incoming links will be reversed.
Styles
Depending on your web browser and installed unicode sypport, you may get varying results with the style parameter. Click the following links for more information:
Styles in your browser
The following chart shows examples of the CSS styles that can be used and how they look in your own web browser:
disc:
Item 1
Item 2
Item 3
Item 4
circle:
Item 1
Item 2
Item 3
Item 4
square:
Item 1
Item 2
Item 3
Item 4
decimal:
Item 1
Item 2
Item 3
Item 4
decimal-leading-zero:
Item 1
Item 2
Item 3
Item 4
lower-roman:
Item 1
Item 2
Item 3
Item 4
upper-roman:
Item 1
Item 2
Item 3
Item 4
lower-alpha:
Item 1
Item 2
Item 3
Item 4
upper-alpha:
Item 1
Item 2
Item 3
Item 4
lower-greek:
Item 1
Item 2
Item 3
Item 4
lower-latin:
Item 1
Item 2
Item 3
Item 4
upper-latin:
Item 1
Item 2
Item 3
Item 4
hebrew:
Item 1
Item 2
Item 3
Item 4
armenian:
Item 1
Item 2
Item 3
Item 4
georgian:
Item 1
Item 2
Item 3
Item 4
cjk-ideographic:
Item 1
Item 2
Item 3
Item 4
hiragana:
Item 1
Item 2
Item 3
Item 4
katakana:
Item 1
Item 2
Item 3
Item 4
hiragana-iroha:
Item 1
Item 2
Item 3
Item 4
katakana-iroha:
Item 1
Item 2
Item 3
Item 4
The first two columns above are the most widely supported styles. The other styles generally require an operating system and web browser both capable of rendering Unicode characters.
Correct styles
The following chart shows what the styles should look like if everything is configured properly:
Examples of style faults
The following chart shows what the styles often look like on systems that don't have full unicode support:
Examples
Basic Use - List all Incoming Links
When used without any parameters, the macro will display a list of all incoming links:
{incoming-links}* No Incoming Links{incoming-links}
By default, the list mode output will show icons to depict different types of content as shown in Example #1. However, you can choose a different item marker using the style parameter:
{incoming-links:style=disc}* No incoming links{incoming-links}
As you can see, we didn't include the usual "No incoming links" message between the macro tags - there's no point (usually) in displaying a message in this case. Because the macro will create a blank line (which would look odd), we simply put a few hyphens in instead.
You can make the output look nicer by centering it with the center macro as follows:
As you can see above, the flat style defaults to putting square brackets around each item. However, there are times that you might want other styles in which case you should use the "separator" parameter:
By default the macro will list incoming links from all types of content, but you might prefer to limit the list to specific types of content. For example, we've got a news item linking to this page (only as an example) that's not much use:
The bitwise sort mode is almost the same as the default natural sort mode – it's faster, but not as good at sorting titles with numbers in them. You should only ever need the bitwise sort if you've got really massive lists of incoming links.
Reverse Sort Order
To reverse the sort order, simply add the reverse parameter:
Filtering Links based on Parent, Ancestor and Space
There will be times when you want to limit links based on where tehy are coming from - especially if you have lots of incoming links!
The first method is based on the parent page - only links attached directly to the page specified will be listed:
{incoming-links:mode=flat|parent=Navigation and Lists}---{incoming-links}
In the example above, only incoming links from pages attached to the Navigation and Lists page will be displayed:
—
Similarly, you can filter the list to pages that share a common ancestor. For example, to show all incoming links from pages within our Macros section, use the following:
This will filter the links to our ADAPTAVIST space (our corporate website) where there aren't currently any links directly to this page (but should any appear in the future, you'll see them below):
None Yet
To filter by more than one space, simply separate the space keys by commas:
This will now include incoming links from the Builder User Guide and our Corporate Website:
None Yet
Excerpts
No self-respecting linking macro would be complete without the ability to display excerpts, and the {incoming-links} macro is no exception!
Excerpts are short summaries added to content (pages, news, etc.) using the excerpt macro and are useful for giving the user more information before they click a link.
To include excerpts, which are displayed in list mode, use the following:
children macro — The {children} macro displays lists of child pages attached to the current page or orphan pages that are not attached to any page...
excerpt macro — The {excerpt} macro defines a block of text as being the excerpt (or summary) for a page...
excerpt-include macro — The {excerpt-include} macro displays the an excerpt from another locaiton in your content...
page-info macro — The {page-info} macro allows you to display several useful pieces of information about the page in a simple format
Hints and Tips
This macro is useful in navigation panels as it can show a list of highly relevant related content to the page being viewed, filtered if necessary to a specific part of your site.
Frequently Asked Questions
Q
How do you get those four dots as the custom separator?
A
It's just two sets of colons ":" next to each other to give ::
Is there an equivalent macro to display the outgoing links associated with a giv...
Is there an equivalent macro to display the outgoing links associated with a given page? I am thinking something similar to the Outgoing Links in the right panel of this page but, I have been unable to find the macro.
The "excerpt" parameter does not seem to work (see example 7 above). It shows th...
The "excerpt" parameter does not seem to work (see example 7 above). It shows the entire content of the page, instead of the information marked in excerpt tags.
Is it possible to filter the incoming links using a label on the linking page; e...
Is it possible to filter the incoming links using a label on the linking page; e.g. only show incoming links where the page containing the link has the label "report"?
Not currently - the macro basically asks Confluence API for a list of links whic...
Not currently - the macro basically asks Confluence API for a list of links which may also include external referrers. As such I doubt it would be possible to use this macro in that scenario.
Hi Guys,
Currently, I can click on page info, and see the outgoing links from th...
Hi Guys,
Currently, I can click on page info, and see the outgoing links from that page.
Is there a way to use this Macro so that i can go to the homepage of the Space, and obtain a list of all external links being used within that space? (and for me to also know which page has that link?)
It can only see wiki pages that link to the page using normal wiki notation link...
It can only see wiki pages that link to the page using normal wiki notation links (ie. those in square brackets) and any trackback links. It won't be able to see links output by other macros.
Hi,
I am trying to use this macro to display the list of trackbacks which can be...
Hi,
I am trying to use this macro to display the list of trackbacks which can be seen on the Info section of a page.
The page I am using it on says that there are no links to display even though I can see in the info section a trackback link from our JIRA system.
Any ideas what might be causing the problem here? Here's what I have coded:
[incoming-links] No links available [incoming-links]
I have substitued
Unknown macro: { and }
for [ and ] so the page code could be viewed for the purposes of this comment.
I'm having problems getting incoming links to show up across spaces. A page in o...
I'm having problems getting incoming links to show up across spaces. A page in one space links (using normal square bracket markup) to a page in another space. The link appears as a trackback on the target page info but the page doesn't come up on the incoming links macro result. Links which occur within the space are working correctly. Confluence v3.4.9.
.png)
If you don't add a message to display when there are no links, the macro will not display anything!
Comments (11)
Oct 27, 2006
Anonymous says:
Is there an equivalent macro to display the outgoing links associated with a giv...Is there an equivalent macro to display the outgoing links associated with a given page? I am thinking something similar to the Outgoing Links in the right panel of this page but, I have been unable to find the macro.
Jan 19, 2007
Anonymous says:
The "excerpt" parameter does not seem to work (see example 7 above). It shows th...The "excerpt" parameter does not seem to work (see example 7 above). It shows the entire content of the page, instead of the information marked in excerpt tags.
Jan 17, 2008
Simon Wheatley says:
Is it possible to filter the incoming links using a label on the linking page; e...Is it possible to filter the incoming links using a label on the linking page; e.g. only show incoming links where the page containing the link has the label "report"?
Jan 17, 2008
Guy Fraser says:
Not currently - the macro basically asks Confluence API for a list of links whic...Not currently - the macro basically asks Confluence API for a list of links which may also include external referrers. As such I doubt it would be possible to use this macro in that scenario.
Jan 17, 2008
Simon Wheatley says:
Thanks.Thanks.
Nov 25, 2008
Paul Csapo says:
Hi Guys, Currently, I can click on page info, and see the outgoing links from th...Hi Guys,
Currently, I can click on page info, and see the outgoing links from that page.
Is there a way to use this Macro so that i can go to the homepage of the Space, and obtain a list of all external links being used within that space? (and for me to also know which page has that link?)
regards,
Paul
Dec 12, 2008
Paul Weir says:
What a helpful macro! There is one problem, though, as I desire to use it: I u...What a helpful macro!
There is one problem, though, as I desire to use it:
I use the {metadata-from} macro on the "Groups" page to get a lot of information that is already contained on the "Persons" page.
When I try to use the {incoming-links} macro on the "Groups" page, I don't get any links from the content of the "Persons" page.
Dec 13, 2008
Guy Fraser says:
It can only see wiki pages that link to the page using normal wiki notation link...It can only see wiki pages that link to the page using normal wiki notation links (ie. those in square brackets) and any trackback links. It won't be able to see links output by other macros.
Dec 15, 2008
Paul Weir says:
That makes sense; thanks for the explanation. Would you happen to have a sugges...That makes sense; thanks for the explanation.
Would you happen to have a suggestion as to how I could get the results I want, as described in my original post?
Oct 02, 2009
Michael Roff says:
Hi, I am trying to use this macro to display the list of trackbacks which can be...Hi,
I am trying to use this macro to display the list of trackbacks which can be seen on the Info section of a page.
The page I am using it on says that there are no links to display even though I can see in the info section a trackback link from our JIRA system.
Any ideas what might be causing the problem here? Here's what I have coded:
[incoming-links] No links available [incoming-links]
I have substitued
for [ and ] so the page code could be viewed for the purposes of this comment.
Jul 29, 2011
John Forrest says:
I'm having problems getting incoming links to show up across spaces. A page in o...I'm having problems getting incoming links to show up across spaces. A page in one space links (using normal square bracket markup) to a page in another space. The link appears as a trackback on the target page info but the page doesn't come up on the incoming links macro result. Links which occur within the space are working correctly. Confluence v3.4.9.
Thanks for any help.