Skip to main content

How to Add SVG Illustrations to Confluence Pages

· 17 min read
NGPilot
NGPilot
NGPilot

Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style.

SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow.

This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute.

What is Content Craft for Confluence?​

Content Craft for Confluence is an Atlassian Marketplace app that provides an in-editor SVG illustration gallery for Confluence. Instead of hunting through stock illustration sites, downloading files, and manually uploading them as attachments, Content Craft gives you a searchable library of ready-to-use SVG illustrations right inside the Confluence editor.

The app is designed for teams that want to improve the visual quality of their Confluence content without hiring a designer or licensing expensive illustration packs. Every illustration in the gallery is optimized for web display, scales to any size without losing quality, and renders crisply on both standard and high-resolution displays.

Key features​

  • Curated SVG gallery with hundreds of professional illustrations covering common business and technology themes
  • Keyword search that lets you filter illustrations by descriptive terms such as "team," "meeting," "security," "cloud," "analytics," and dozens more
  • Category filters organized on the right side of the gallery panel so you can browse by theme or topic
  • One-click insertion that places the selected SVG directly onto your Confluence page with no file upload required
  • Confluence-native experience that works inside the standard page editor, with no external tools or browser tabs needed

The result is a workflow that looks like this: open a page, type a slash command, find an illustration, click to insert, publish. Under thirty seconds from start to finish.

Step-by-step: Add SVG illustrations to Confluence​

Step 1: Install Content Craft for Confluence​

Before you can insert SVG illustrations, you need to install the app from the Atlassian Marketplace.

  1. Open Confluence Settings by clicking the gear icon in the top-right corner of Confluence.
  2. Navigate to Find new apps under the "Apps" section in the left sidebar.
  3. In the search bar, type "Content Craft for Confluence".
  4. Click Get App on the search result.
  5. Follow the installation prompts to approve the app for your Confluence instance.

The installation typically completes in under a minute. Once installed, the Content Craft macro is available on every page in every space across your Confluence instance. There is no per-space configuration or additional setup required.

If your organization requires admin approval for new apps, submit a request to your Confluence administrator with a link to the app on the Atlassian Marketplace.

After installation, verify the app is working by opening any page in edit mode and typing /Content Craft in the editor. If you see the macro appear in the dropdown, the installation was successful.

Step 2: Insert the Content Craft macro​

Once the app is installed, inserting an SVG illustration is as simple as adding any other macro in Confluence.

  1. Open the Confluence page where you want to add an illustration, or create a new page.
  2. Click Edit to open the page in the Confluence editor.
  3. Place your cursor at the location on the page where you want the illustration to appear.
  4. Type /Content Craft for Confluence in the editor. The macro appears in the dropdown list.
  5. Click to select the macro. The SVG gallery panel opens.

The gallery panel opens directly within the editor. You do not need to navigate to a separate tab, open a popup window, or leave the editing context. This keeps your workflow uninterrupted.

The Content Craft gallery gives you two ways to find the right illustration: browsing by category and searching by keyword.

Searching by keyword

At the top of the gallery panel, you will find a search box. Type any keyword to filter the illustrations. The search supports a wide range of descriptive terms. For example:

  • People and roles: "team," "woman," "man," "child," "developer," "manager"
  • Activities: "meeting," "presentation," "collaboration," "brainstorming"
  • Technology: "cloud," "server," "security," "database," "analytics," "code"
  • Business concepts: "growth," "strategy," "innovation," "process," "workflow"

The search results update in real time as you type. There is no need to press Enter or click a search button. This instant feedback makes it fast to experiment with different keywords until you find the illustration that fits your content.

Filtering by category

On the right side of the gallery panel, you will see category filters. These organize the SVG illustrations into themed groups so you can browse visually without needing a specific keyword in mind. Categories typically include groupings such as:

  • People and teams -- illustrations of individuals and groups collaborating, working, and communicating
  • Technology and infrastructure -- servers, cloud computing, networks, data centers, and security concepts
  • Business and strategy -- growth charts, planning sessions, goal setting, and process flows
  • Education and learning -- onboarding, training, documentation, and knowledge-sharing scenes
  • Communication -- presentations, meetings, email, chat, and feedback loops

Click any category to see all illustrations in that group. You can combine category filtering with keyword search to narrow down results even further.

Step 4: Select your SVG illustration​

Once you have found an illustration that fits your content, click on it to select it. The gallery shows a preview of the illustration, confirming your choice before it is inserted onto the page.

Take a moment to consider how the illustration will look in context. A few things to keep in mind:

  • Placement. Illustrations work well above a section heading to set the visual tone, beside a paragraph to break up text, or at the top of a page as a hero image.
  • Relevance. The illustration should directly relate to the content it accompanies. A "team collaboration" illustration above a section about cross-functional workflows makes sense. The same illustration above a section about database configuration does not.
  • Consistency. If you are adding multiple illustrations to a single page or across a set of related pages, try to use illustrations from the same visual style. Content Craft's gallery is curated for visual consistency, but mixing very different illustration styles on one page can feel disjointed.

When you are satisfied with your selection, click the Save button to insert the SVG onto your Confluence page.

Step 5: Save and publish the page​

After clicking Save in the gallery panel, the SVG illustration appears on your page in the editor. You can now:

  • Resize the illustration by clicking it and dragging the corner handles to adjust its dimensions
  • Reposition the illustration by clicking and dragging it to a different location on the page
  • Add alignment using Confluence's text alignment options to center, left-align, or right-align the illustration
  • Add more illustrations by repeating the process if your page needs additional visuals

When you are happy with the page layout, click Publish to make the page visible to your team. The SVG illustration renders at full quality on the published page, scaling cleanly to any screen size, from desktop monitors to mobile devices.

If you need to change the illustration later, simply edit the page, select the existing SVG, delete it, and insert a new one from the Content Craft gallery. The process is the same as replacing any other content element on a Confluence page.

Content Craft for Confluence organizes its illustration library into intuitive categories that map to common content types you find in Confluence spaces. Understanding these categories helps you find the right illustration quickly.

People and collaboration​

Illustrations in this category depict individuals and teams in professional settings. You will find scenes of people working together at whiteboards, having conversations in meeting rooms, collaborating on documents, and celebrating achievements. These illustrations are ideal for:

  • Team onboarding pages
  • Company culture documentation
  • HR and people-ops content
  • Project kickoff pages
  • Retrospective summaries

Technology and infrastructure​

This category covers technical concepts rendered as clean, modern illustrations. Cloud computing, server racks, network diagrams, security shields, and code editors are all represented. Use these for:

  • Technical documentation
  • Architecture decision records
  • Infrastructure runbooks
  • Security policy pages
  • DevOps and deployment guides

Business and growth​

Illustrations in the business category cover strategic concepts: charts going up, target icons, roadmap visuals, handshake scenes, and process diagrams. These work well on:

  • Quarterly planning pages
  • OKR and goal-tracking documents
  • Strategy and vision pages
  • Sales enablement content
  • Executive summary sections

Education and documentation​

This group features illustrations related to learning, reading, writing, and knowledge sharing. Books, notebooks, graduation caps, and teaching scenes appear here. Perfect for:

  • Training materials
  • How-to guides and tutorials
  • Knowledge base articles
  • Learning and development content
  • Documentation home pages

Communication and workflows​

Scenes of presentations, email, messaging, feedback loops, and process flows live in this category. They are a good fit for:

  • Communication guidelines
  • Process documentation
  • SOP pages
  • Meeting templates
  • Feedback and review workflows

Use cases: When to use SVG illustrations in Confluence​

Knowing how to insert an illustration is only half the skill. Knowing when and where to use them is what separates visually effective Confluence pages from cluttered ones. Here are the most impactful use cases.

Technical documentation​

Technical documentation pages in Confluence -- API references, architecture guides, deployment runbooks -- tend to be dense with text and code. Adding a single relevant illustration at the top of a documentation page or above a major section heading creates a visual anchor that helps readers orient themselves.

For example, a page about your CI/CD pipeline could feature a technology-themed illustration of a deployment workflow at the top. The illustration does not replace the technical content; it gives readers an immediate visual cue about what the page covers before they start reading the details.

Illustrations are especially useful on documentation home pages and index pages, where they help differentiate sections and make long lists of links more scannable.

Employee onboarding​

Onboarding is one of the most content-heavy processes in any organization. New hires encounter dozens of Confluence pages in their first week: company values, team introductions, tool setups, process walkthroughs, and policy documents. SVG illustrations make these pages feel welcoming instead of overwhelming.

Use people and collaboration illustrations on team introduction pages, education-themed illustrations on training materials, and workflow illustrations on process guides. The visual variety helps new hires distinguish between different types of content and makes the onboarding experience feel more polished.

Presentations and reports​

Many teams use Confluence as a presentation platform, sharing pages in meetings instead of slide decks. SVG illustrations elevate these pages from plain documents to presentation-ready content. A well-placed illustration on a quarterly review page, a project status update, or a strategy proposal adds professionalism without requiring design skills.

Because SVG files are resolution-independent, the illustrations look crisp when displayed on a projector, a large monitor, or shared over a video call. There are no pixelation or blurriness issues that you sometimes get with low-resolution image uploads.

Knowledge base articles​

Self-service knowledge bases live or die by their usability. When employees or customers come to a knowledge base, they are usually looking for a quick answer. Illustrations help in two ways:

  1. They break up long articles into visually distinct sections, making the content feel less intimidating.
  2. They provide visual cues about the topic of each article when browsing an index page with thumbnails.

A knowledge base article about "how to reset your password" with a relevant illustration at the top is more approachable than the same article with nothing but text. Readers are more likely to start reading, and they perceive the content as more trustworthy and up to date.

Project and sprint pages​

Agile teams often maintain Confluence pages for sprint planning, retrospectives, and project overviews. Adding illustrations to these pages makes them more engaging during sprint ceremonies when the page is shared on screen. A retrospective page with a relevant illustration feels more intentional and less like an afterthought.

For project overview pages, an illustration at the top sets the tone for the entire project. It gives the page a visual identity that team members recognize at a glance when scanning their Confluence dashboard or space overview.

Why SVG instead of PNG or JPEG?​

You might wonder why Content Craft uses SVG specifically rather than raster formats like PNG or JPEG. There are several practical advantages.

Resolution independence. SVG files render perfectly at any size. The same illustration looks crisp on a phone screen, a laptop display, a 4K monitor, and a projector. Raster images become blurry when scaled up or waste bandwidth when saved at unnecessarily high resolutions.

Small file size. SVG illustrations are typically much smaller than equivalent-quality PNG or JPEG files. This means faster page loads in Confluence, which is especially noticeable on pages with multiple illustrations.

Style consistency. Because SVGs are vector-based, their visual style remains consistent regardless of how Confluence renders them. Colors do not shift, edges stay clean, and the illustrations integrate naturally with Confluence's own UI elements.

Accessibility. SVG content can be read by screen readers when properly tagged, making illustrations more accessible to users with visual impairments compared to raster images that require separate alt text.

No versioning issues. SVG illustrations inserted through Content Craft are not file attachments that clutter your page's attachment list. They render inline as part of the macro, keeping your attachment manager clean and focused on actual uploaded files.

Tips for effective illustration usage​

Adding illustrations is easy. Adding them effectively takes a bit of thought. These tips will help you get the most out of Content Craft's SVG gallery.

Match the illustration to the content​

Every illustration should serve the content it accompanies. Before inserting an SVG, ask yourself: does this visual reinforce the message of the section it sits in? If the answer is not a clear yes, consider a different illustration or no illustration at all. A well-placed illustration on a page with three illustrations is more effective than seven illustrations that do not relate to the surrounding text.

Use illustrations as section dividers​

On long pages with multiple H2 sections, placing an illustration between sections creates a natural visual break. This technique works especially well on documentation pages and knowledge base articles where readers are likely to skim. The illustration acts as a landmark that helps readers orient themselves on the page.

Maintain a consistent visual style​

If you are building a set of related pages -- for example, an onboarding series or a documentation space -- use illustrations from the same category or with the same visual treatment. Content Craft's gallery is curated for internal consistency, so sticking to illustrations from the same category (or the same handful of categories) ensures your pages feel cohesive.

Do not over-illustrate​

Not every section needs an illustration. As a general rule, a page of 1,000 to 2,000 words benefits from one to three illustrations. Shorter pages might need only one. Over-illustrating a page makes it feel busy and can distract from the content itself. Let the text carry the substance; let the illustrations provide visual relief and context.

Consider mobile rendering​

Many Confluence users read pages on mobile devices. SVG illustrations scale gracefully to smaller screens, but their placement matters. Avoid placing illustrations inside complex table layouts or multi-column layouts that might not render well on mobile. Single-column page layouts with illustrations placed above or between sections work best across all devices.

Common questions about SVG in Confluence​

Can I customize the colors of SVG illustrations from Content Craft?​

The illustrations from Content Craft's gallery come with a fixed visual style. If you need custom-colored illustrations, you can download SVG files from external sources and upload them as Confluence attachments. Content Craft focuses on providing a ready-to-use library so you do not have to spend time on customization.

Do SVG illustrations slow down Confluence pages?​

No. SVG files are typically smaller than equivalent raster images. Content Craft renders them inline through the macro, so they load efficiently. Pages with multiple SVG illustrations generally load faster than pages with the same number of PNG or JPEG attachments.

Can I use Content Craft on Confluence Data Center?​

Content Craft for Confluence is available on the Atlassian Marketplace for Confluence Cloud. Check the marketplace listing for the latest information on platform support.

Do I need design skills to use Content Craft?​

Not at all. The gallery is designed for non-designers. You browse, search, click, and save. The illustrations are professionally designed and ready to use as-is. The entire workflow requires zero design knowledge.

Can I use Content Craft illustrations in exported pages?​

SVG illustrations inserted through Content Craft render as part of the page content. When you export a Confluence page to PDF or Word, the illustrations are included in the export. The quality of the export depends on Confluence's export engine, but SVG-based content generally exports cleanly.

Troubleshooting common issues​

The macro does not appear in the slash command menu​

If typing /Content Craft for Confluence does not show the macro, the app may not be installed correctly. Go to Confluence Settings, then manage apps, and verify that Content Craft for Confluence appears in your installed apps list. If it does not, try reinstalling from the Atlassian Marketplace. If it does appear but the macro is still missing, check that the app is enabled (not disabled) in the app management panel.

This can happen if your Confluence instance has strict network firewall rules that block external asset loading. Content Craft's gallery loads illustration data from its CDN. Ensure your network allows outbound connections to the app's asset domains. If the issue persists, contact NGPILOT support through the Atlassian Marketplace listing.

The illustration looks blurry after publishing​

SVG illustrations should render crisply at any size. If an illustration appears blurry, it may have been inadvertently converted to a raster format by a third-party Confluence theme or customization. Try viewing the page in Confluence's default theme to confirm. If the illustration is crisp in the default theme, the issue is with your custom theme, not with Content Craft.

I cannot resize the illustration after inserting it​

After inserting an SVG through Content Craft, click on the illustration to select it. Resize handles should appear at the corners and edges. If they do not appear, try publishing the page and then editing it again. The Confluence editor sometimes needs a publish cycle to fully render the macro's interactive elements.

Adding SVG illustrations to Confluence pages does not have to mean opening a separate design tool, downloading files, and uploading attachments. Content Craft for Confluence puts a searchable, categorized illustration gallery directly inside the Confluence editor. Install the app, type the slash command, find the right illustration, and publish. Your pages go from text-heavy to visually engaging in under a minute, and your team gets documentation, onboarding materials, and presentations that are actually pleasant to read.