Docs & Code Guide

Embed a diagram in Linear: the copy Linear makes, and the link that stays live

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Linear has an unusual property among work trackers: it is documented that referencing an image URL in markdown content is a way to upload that file into Linear. The platform fetches your image and keeps its own copy. For a screenshot of a broken screen that is a feature, because the picture survives whatever happens to the original. For an architecture diagram it is the whole problem, and it is invisible until the diagram changes and the issue does not.

Try it free
6 min readFor product and platform teams running their work in Linear

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

138/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What Linear does with an image address

The Linear developer guide on uploading files describes putting a URL inside markdown content as the easiest way to upload a file when creating an issue, a comment or a document: Linear fetches the file and stores it in its own private cloud storage. The same guide accepts a base64 data URI as an alternative, and routes everything that is not an image through a fileUpload mutation that returns a pre-signed URL, with the warning that the PUT has to run server side because Linear's own Content Security Policy blocks it from the browser. Three inputs, one outcome: an asset Linear owns.

So the markdown image line does render. It just stops being your URL the moment it is saved. Nothing in the issue points at the origin any more, no request goes back out, and no cache header applies. The picture in the issue is a photograph of the diagram taken the day it was pasted.

The editor is also a rich-text editor, not a markdown renderer. Markdown you paste is converted once into the Linear document model rather than re-parsed each view, which is another reason nothing about that image is going to change later.

Copies are right for evidence and wrong for architecture

The rehosting behaviour is a deliberate, sensible design. Issue attachments must not break when someone deletes a Slack file or rotates a bucket, and a permanent copy is the only way to guarantee that. Every screenshot, log excerpt and design comp in Linear benefits from it.

An architecture diagram is the one class of image that wants the opposite guarantee. Its value is that it matches the system today, and a copy cannot promise that. So do not fight the platform: let Linear copy the things that should be frozen, and keep the reference view as a link.

Architecture (live, opens without an account):
https://datadef.io/embed/my-platform-a1b2c3d4

Pasted below: the topology as of this milestone, for the record.

The Linear document is the right container

Linear documents are where a project keeps prose that outlives individual issues, and an architecture reference belongs there rather than in a comment thread. One line with the live link at the top of the project document gives every issue in that project a single place to check.

When you do want a frozen picture, attach an export at a milestone boundary and label it with the date. PNG and JPEG exports come from the same endpoint the live view uses, so the copy you attach is exactly the drawing that was live at that moment.

One habit that prevents the drift

Write the date next to any pasted image and nothing next to a live link. Readers then know which one to trust when the two disagree, and the disagreement itself becomes a signal that the diagram needs a look. More on this pattern in documentation drift.

FAQ

Does markdown image syntax work in a Linear issue?

It renders, but not the way you expect. Linear treats an image URL in markdown content as an upload instruction: it fetches the file and stores a copy in its own file storage. The issue then displays the Linear copy, which never changes again, no matter what happens to the original.

Can I show a diagram inside Linear that updates by itself?

No. Every image in Linear is a stored copy, and Linear only builds rich previews for applications it integrates with. The reliable pattern is a plain link to a page that renders the current diagram, placed in the project document or issue description, plus exported images when a frozen record is wanted.

Does the person clicking the diagram link need an account?

No, when the project is shared publicly. The shared view opens for anyone with the link and shows the current diagram with pan and zoom, without a sign-in. That keeps it usable for contractors, agencies and anyone else outside the Linear workspace. The same public sharing means anyone holding the address can view it, so use the link for diagrams you would be comfortable showing outside the company.

Should I attach an exported diagram to a Linear issue at all?

Yes, when the point is to record a moment: the topology at the start of an incident, or the architecture a milestone shipped with. Label it with a date so nobody mistakes it for current, and keep a live link nearby for anyone asking what the system looks like now.

What export formats are available for the attached copy?

PNG and JPEG, with an optional width from 600 to 4000, a height from 400 to 4000, and a scale from 1 to 3. The default is 1600 by 1000 at 2x, which is sharp enough for a Linear issue on a high-density display.