Referencing Content – Best Practices
Referencing content is valuable for many different reasons. As a content author, you avoid duplicating content if useful information is available elsewhere and you help your users discover other relevant or related content. Plus, it’s good for SEO.
On this page you will learn how to reference other articles in your help center using Confluence editor features and macros.
Display a List of Children on Topic Pages
Add the child pages macro to parent pages to help your users overview the content of a specific topic. Scroll Viewport overrides the Confluence view of the macro to generate a nice, themed ‘accordion’ output.
→ See a live example.
Display a List of Related Articles
Add the Confluence Filter by label macro (formally content by label macro) to your pages to show and reference a list of related articles from your Scroll Viewport site. Add it to the end of your articles to point your site visitors to the next most interesting or helpful pieces of content in the site.
The macro will only display pages that are part of your Scroll Viewport site. Pages that aren’t included in your site’s content sources won’t show up. You’ll be notified in the preview report if there are any empty macros on a page.
→ See a live example (end of the page).
Link to Other Articles
Insert links to other articles
Select Link from the editor toolbar and use the search bar to find the right page in your space or document.
Inserting links via page search will ensure that they remain stable even if you rename or move pages around (as long as they remain in the same Confluence space or document).
Confluence will automatically transform your page link into its Smartlink inline view format and use the page title as the default link text. It’s a good idea to keep this default link text (or modify it slightly), so that it remains descriptive.
Insert links to article sections
Add links to article sections to help users skip to the relevant or related content right away.
To be able to link to specific sections, on the same or on another article of your help center, you will need to place an anchor macro in your target section in Confluence first. Then, opt for one of the following options:
If the section is on the same page: Place anchor links (via the editor’s link option) in your Confluence page to link to the corresponding section of the page.
If the section is on another page: Manually build an anchor link to link to the section of the other page and place this link in your Confluence page. Links need to have the format
https://yourname.atlassian.net/wiki/spaces/space-name/pages/7453179996/Topic+Article#task1
If you’re looking to share a link (not embed a link on an article), we recommend to generate your Viewport site and copy the (section) link directly from your live help center. Learn more on Share Links.
Link to Jira Issues
To provide more detailed information, especially in your release notes, you can insert Jira issue macros into your page content. Compared to a plain link, the macro will be more descriptive and stand out more in your content.
Learn How To Insert a Jira Issue Macro.