Markdown screenshots, explained

A markdown screenshot is the simplest possible artifact for showing a visual problem to anyone who can read text. You write one line of markdown, the viewer renders it as an image, and the file works the same way in GitHub, Notion, Linear, Cursor, and Claude Code. No proprietary viewer, no export step, no broken handoff. This is the format the rest of the guides hub keeps coming back to, so it's worth a definitional page.

What you'll learn

• The exact markdown syntax for embedding a screenshot inline
• The role of alt text and when to bother writing it
• What makes an image URL stable enough for AI agents to follow
• Which tools render markdown images correctly and which don't
• How CobaltCapture produces markdown screenshots end to end

The markdown image syntax

The syntax is one line:

![alt text](https://images.example.com/screenshot.png)

That's it. An exclamation mark, square brackets around alt text, parentheses around the image URL. The exclamation mark is what distinguishes an image from a regular link. Drop the exclamation mark and you get [alt text](url), which is a clickable link instead of an embedded image.

Alt text is the human-readable description that appears when the image fails to render or when a screen reader announces it. For screenshots in feedback documents, alt text is doing double duty: it's the accessibility caption, and it's the textual context an AI agent reads when it can't see the image. Write alt text that names what's in the screenshot, not what the screenshot represents. "Checkout form with misaligned submit button" is useful. "Bug" is not.

Absolute vs relative URLs. A relative URL like ./screenshot.png only resolves if the renderer knows the document's base path. Inside a GitHub repo, relative paths work. Pasted into ChatGPT, Cursor, or Notion, they don't. For anything that needs to travel, use an absolute URL with a full https:// prefix. This is the single most common mistake people make when their markdown screenshots stop rendering after a copy-paste.

How this differs from HTML <img>. Both work in most markdown renderers, since markdown allows raw HTML. The HTML version gives you control over width, height, alignment, and lazy loading. The markdown version is half the characters and works in renderers that strip HTML for safety, like many comment systems and chat-based AI agents. Default to markdown syntax. Reach for <img> only when you need explicit sizing.

Why portability matters

A markdown document with embedded screenshots is a single file that displays correctly in roughly a dozen different tools without modification. The same .md file you wrote in your editor renders in:

• GitHub and GitLab issues, PRs, READMEs, and wiki pages
• Linear comments and issue descriptions
• Notion when pasted into a page
• Obsidian and other personal knowledge tools
• VS Code and Cursor preview panes
• ChatGPT, Claude, and Claude Code when pasted into chat
• Slack with limited rendering, mostly as a link preview
• Anywhere with a markdown viewer, including static site generators like Hugo, Jekyll, and Next.js

This portability is the entire point. A Loom recording works in Loom. A Figma comment works in Figma. A Jira screenshot works in Jira. A markdown screenshot works wherever the reader happens to be, including in the prompt of an AI agent that's about to fix the problem.

The mechanism is unglamorous: the markdown file is plain text, the image URL points at a public host, and the viewer makes a GET request for the PNG. There's no API, no integration, no plugin. When the next AI tool launches in 2027, it will read markdown the same way today's tools do, because markdown predates all of them and isn't owned by anyone. The format outlives the tool.

Portability also means the document survives the human handoff. You publish a review, your teammate forwards the link, the developer opens the markdown export, the agent reads the same file. Nobody has to convert anything, install anything, or sign up for anything to consume the content. That's worth more than it sounds like.

Stable image hosting

The markdown is only half the artifact. The other half is wherever the image actually lives. An embedded screenshot is only as durable as its URL, and a surprising number of image URLs are not durable.

What makes an image URL stable for AI agents and external viewers:

• Public. No authentication, no session cookie, no signed URL that expires in 15 minutes. The URL must work for an anonymous GET request from any IP.
• Predictable host. A real CDN or object store with a stable domain. Not a Slack file URL, not a Google Drive preview, not a Dropbox share link, not a temporary share in your screenshot app.
• Direct PNG or JPG. The URL should return image bytes with an image/* content-type. URLs that return HTML wrapper pages with the image embedded inside don't work in markdown renderers.
• Long-lived. The host should still be there in a year. CDN-served PNG on your own domain is the gold standard. CDN-served PNG on a third-party host like R2 or S3 is close behind.

Quality ladder, best to worst:

1. CDN-served PNG on a custom domain. images.yourdomain.com/foo.png. Stable forever, fast, predictable.
2. CDN-served PNG on a managed object store. Cloudflare R2, AWS S3 with CloudFront, Backblaze B2. Stable as long as the bucket lives.
3. GitHub or GitLab raw URLs. Stable per commit, but tied to a repo that may go private or move.
4. Imgur and similar public hosts. Works, but ad-heavy, sometimes rate-limited, occasionally removes content.
5. Slack file URLs. Almost always require auth. Don't use these for anything that needs to leave Slack.
6. Google Drive share links. Return an HTML viewer page, not image bytes. Will not render in markdown.
7. Local file paths. file:///Users/.... Only work on your own machine.

The practical implication: if you're hand-rolling a markdown bug report, host the image somewhere a CDN will serve a direct PNG. If you're using a tool that captures and publishes for you, check what its image URLs look like before you commit to it.

How CobaltCapture fits in

CobaltCapture is built around the markdown screenshot as the output format. The flow is short:

1. Open cobaltcapture.com, hit Capture screen, pick the window you want to review.
2. Drag a box around what matters, then hit Dictate and talk through the problem out loud.
3. Repeat for each finding, then hit Publish.

You get a public review URL and a one-click markdown export. The images are cropped PNGs hosted on Cloudflare R2 behind a custom domain. The URLs are public, direct, and stable. The markdown file you download or paste into Cursor renders correctly in every tool listed above, without modification.

This is the same workflow described in the screen capture to markdown page, which is the canonical pattern behind every CobaltCapture review. The tool exists because rolling your own hosted-PNG plus markdown pipeline is annoying enough that most people just paste screenshots into Slack instead, and that's where the feedback dies.

Frequently asked questions

What is a markdown screenshot?

A markdown screenshot is an image embedded inline in a markdown document using the standard image syntax. The image lives at a public URL and the markdown file references it, so any viewer that renders markdown will pull the image in automatically. The result is a single text file that displays as a fully illustrated document.

How do I embed an image in markdown?

Use the syntax ![alt text](https://example.com/image.png). The exclamation mark distinguishes an image from a regular link. The text in brackets is the alt text. The URL in parentheses points to the hosted image. Most editors will render the image inline as soon as the URL resolves.

Where should the image actually be hosted?

Host the image on a public CDN with a stable URL and no authentication required. Cloudflare R2, S3 with CloudFront, or any public object store works. Avoid Slack attachments, Google Drive share links, or anything that expires or requires a session cookie, because AI agents and external viewers cannot follow them.

Do all markdown viewers render embedded images?

Most do. GitHub, GitLab, Linear, Notion, Obsidian, VS Code preview, Cursor, Claude Code, and ChatGPT all render embedded images from markdown. A few minimal renderers strip images, but the markdown remains readable as plain text with the image URL intact, so the file degrades gracefully.

Can AI coding agents read markdown screenshots?

Yes. Cursor, Claude Code, Windsurf, and similar agents process markdown natively and pull embedded images in as visual context for their vision models. Pasting a markdown URL or dropping a .md file into the project root gives the agent both the written context and the screenshot in one input.

Frequently asked questions

What is a markdown screenshot?

A markdown screenshot is an image embedded inline in a markdown document using the standard image syntax. The image lives at a public URL and the markdown file references it, so any viewer that renders markdown will pull the image in automatically. The result is a single text file that displays as a fully illustrated document.

How do I embed an image in markdown?

Use the syntax . The exclamation mark distinguishes an image from a regular link. The text in brackets is the alt text. The URL in parentheses points to the hosted image. Most editors will render the image inline as soon as the URL resolves.

Where should the image actually be hosted?

Host the image on a public CDN with a stable URL and no authentication required. Cloudflare R2, S3 with CloudFront, or any public object store works. Avoid Slack attachments, Google Drive share links, or anything that expires or requires a session cookie, because AI agents and external viewers cannot follow them.

Do all markdown viewers render embedded images?

Most do. GitHub, GitLab, Linear, Notion, Obsidian, VS Code preview, Cursor, Claude Code, and ChatGPT all render embedded images from markdown. A few minimal renderers strip images, but the markdown remains readable as plain text with the image URL intact, so the file degrades gracefully.

Can AI coding agents read markdown screenshots?

Yes. Cursor, Claude Code, Windsurf, and similar agents process markdown natively and pull embedded images in as visual context for their vision models. Pasting a markdown URL or dropping a .md file into the project root gives the agent both the written context and the screenshot in one input.