Confluence Smart Links
A raw web address looks cold and tells readers nothing. Smart links convert an address into a readable title with a live preview. Paste a link to a Jira work item, a shared document, or a design file, and Confluence shows the real name and status instead of a long string of characters.
What Smart Links Do
When you paste a supported link into the editor, Confluence fetches details from the destination. The link then displays the page title, the owner, and sometimes a status or thumbnail. Hover over the link to see a preview card without leaving the page.
RAW LINK https://example.atlassian.net/browse/PRJ-142 SMART LINK [ PRJ-142 Fix login timeout | In Progress ]
Three Display Styles
| Style | Look | Best Use |
|---|---|---|
| Inline | A short title inside a sentence | References in running text |
| Card | A compact box with title and details | Lists of resources |
| Embed | The full content displayed on the page | Videos, documents, and designs |
Click a pasted link and choose a style from the small toolbar that appears. Switch back at any time.
Pasting a Link Step by Step
- Copy the address from your browser.
- Paste it into the editor on a blank line or inside a sentence.
- Wait a moment while Confluence reads the destination.
- Pick inline, card, or embed from the toolbar.
- Publish the page and test the link.
Supported Destinations
Confluence supports many Atlassian products and a growing list of outside services, including file storage, design, video, and project tools. Support depends on your site settings and the way your administrator connected each service. A link from an unsupported service stays a plain link.
Permissions Still Apply
A smart link respects the permissions of the destination. A reader who cannot open a private document sees a short message that asks them to request access, instead of the preview. The link never leaks hidden content.
Reader with access --> sees title, owner, preview Reader without access --> sees "Request access" prompt
Embedding Media
The embed style turns a page into a rich hub. A training page can show a recorded video, a design file, and a slide deck in one place. Readers consume everything without opening extra tabs. Keep embeds focused, since too many large embeds slow page loading.
A Project Hub Example
PAGE: Website Redesign Hub Overview text Design file [ embed : live design preview ] Kickoff video [ embed : recorded call ] Open bugs [ card : PRJ-142, PRJ-150 ] Launch plan [ inline : link to Launch Plan page ]
One page now gathers materials that previously lived in five separate tools.
Link Hygiene
- Use descriptive names in the destination, since the smart link shows that title.
- Check links after a destination document moves or gets renamed.
- Replace shared links that expire with permanent ones.
- Avoid linking to personal files that colleagues cannot open.
Accessibility and Clarity
Descriptive link text helps screen reader users. A phrase such as "Q3 budget sheet" tells readers more than "click here". When you write a link into a sentence by hand, name the destination in the visible text.
Troubleshooting
- A link that stays plain may come from an unsupported service.
- A preview that shows "no access" means the destination blocks you.
- A slow embed may signal a very large file.
- An outdated title appears when the destination changed recently, so refresh the page.
Smart Links vs Plain Links
Plain links still have a place. A link inside a sentence, such as a reference to a policy page, reads naturally as inline text. Smart links shine when readers need context: status, owner, or a visual preview. Choose the style based on the reader's need, and avoid filling a page with cards that crowd the real content.
Key Takeaways
- Smart links replace raw addresses with titles and previews.
- Inline, card, and embed styles suit different needs.
- Destination permissions control what readers see.
- Embeds turn a page into a single hub for scattered resources.