Markdown to Image for Social Media: Sizes, Themes, and a Repeatable Workflow
A long technical post often fails because the reader has to scroll a wall of text. Turning a focused part of it into an image gives that idea a second chance: it becomes a single card people can read, save, and reshare. The question is how to do this consistently without opening a design tool every time.
The workflow in this guide starts from one Markdown source and produces a ready-to-post image. You will choose a canvas, pick a readable theme, write alt text, and reuse the same process for the next post. The examples use MarkdownToImage and were checked against its API documentation on August 3, 2026.
An image pays off when the message fits on one screen, benefits from formatting that a text post flattens, or needs to be shared as a standalone file. Code, tables, and checklists are the clearest cases: they stay readable in an image and lose that readability in a plain-text post.
Plain text is usually the better choice when the content is long, requires editing, or must be searchable and copyable. Do not convert a whole article into one image. Convert the part that deserves a second look, and link back to the full post.
Keep the source message in Markdown and render variants for different channels instead of drawing each image by hand. One source can become a wide LinkedIn card, a square post, and a narrow update with different canvases and themes.
This matters because the alternative scales badly. Editing three separate image files means three chances to introduce a typo, and a copy change six weeks later means finding and redoing all three. When the source is Markdown, you fix one line and re-export.
Store that source next to your other content, not in a design tool. A short .md file in the same repository as your docs is enough, and it gives you version history for free: when someone asks why last month's card said something different, the answer is in the commit log.
This is why the workflow starts with a small Markdown block. Keep the message short, use one heading, and let the renderer handle the typography.
This Markdown is small enough to verify the typography before you use real content:
# Deployment complete
Environment: **production**
- [x] Database migrated
- [x] Health checks passing
- [ ] Post-deploy review
`status: healthy`
Paste it into MarkdownToImage, pick a 1200-pixel-wide canvas, and export. The rendered card is the baseline for every other variant.
Use a deliberately small fixture like this one for your first render rather than your real content. It exercises the elements that break most often — bold text, task lists, inline code — while staying short enough that you can spot a spacing or contrast problem at a glance. Once the fixture renders the way you want, swap in the real message and keep the same settings.
The generator exposes three controls that shape the output: width, quality, and the output format.
width sets the render width in pixels, from 200 to 2560, with a default of 800. quality is the device scale factor from 1.0 to 3.0, with a default of 2.0. The effective pixel height follows the aspect ratio of your content, so a 1200-pixel-wide card gives sharp text on most social feeds.
A 1200-pixel canvas is a safe starting point: it is wide enough to stay sharp on high-density displays and narrow enough to keep line lengths readable. For a LinkedIn post with a link, the platform recommends a 1.91:1 ratio, around 1200 x 627 pixels, and images wider than 200 pixels. Keep the source Markdown narrow so the renderer does not create an over-wide table.
The format parameter supports PNG, JPEG, WebP, or PDF. PNG keeps code and diagrams crisp; use it for social cards.
Choose a theme with enough contrast for the feed, not just for a bright editor. Light themes read well on white apps; dark themes stand out on dark-mode feeds. The theme affects the whole card, while the code style affects only fenced code blocks.
The two settings are independent, which is easy to get wrong: a dark theme paired with a light code style produces a card with a bright rectangle punched out of the middle. Pick the code style after you pick the theme, and check that fenced blocks sit inside the card rather than fighting it.
Pin the theme by name in your notes or your script rather than relying on whatever the editor last used. A card set loses its visual coherence the moment one image renders with a different palette, and that is exactly the kind of drift that goes unnoticed until the images are side by side in a feed.
Preview the rendered image at its actual display width before posting. A card that looks fine in a preview pane can become hard to read when scaled down in the feed.
Break a long post into a thread of cards, one idea per card. Each card should work on its own, because people will see cards out of order.
A practical split is one heading, one key point, and a short checklist per card. Keep the same theme and width across the thread so the cards feel like one set.
Resist the urge to continue a sentence across two cards. Threads get reshared one image at a time, and a card that starts mid-thought reads as broken when it appears alone. If an idea genuinely needs more room than one card allows, that is a signal it belongs in the linked article instead.
Three to five cards is a workable range for most threads. Beyond that, the reader is doing the work of reading an article without the benefit of being able to scan it, and the images stop earning their place.
Alt text matters for both accessibility and search. Describe what the image shows, including the text it contains, without repeating the whole caption.
Write alt text as if the image were not there. If the card says "Deployment complete — all checks passing," the alt text for a general audience might be "A dark-themed Markdown card showing a deployment checklist with two completed steps and one pending." That is more useful than "image of checklist" and less redundant than copying the entire Markdown verbatim.
Platforms limit how much alt text you can add. On X (Twitter), the image description box accepts up to 1,000 characters per image. This figure is based on X's public help documentation; the help pages were not machine-readable on August 3, 2026, so verify the current limit before you rely on it in a template. LinkedIn's help does not state a separate alt text limit for standard image posts.
Keep alt text shorter than the platform limit allows. A description that fills the entire character budget is not more useful — it is harder to process and risks truncation in some assistive technology pipelines. Aim for one or two sentences that tell the reader what they would learn from the image, then stop.
When you render many images, the same parameters become a script. The Markdown to Image API accepts a POST request with a Bearer token and returns a temporary URL that is retained for 24 hours in URL mode, or raw image data in binary mode. Download the result promptly; the temporary URL is not permanent storage.
A minimal request sets the same width, quality, and theme you picked in the editor:
{
"markdown": "# Weekly update\n\n- Faster exports\n- Clearer reports\n- One repeatable workflow",
"format": "png",
"width": 1200,
"quality": 2,
"theme": "github-dark",
"mode": "url"
}
The full integration guide covers cURL, Node.js, Python, and n8n: Markdown to Image API: Generate PNGs with cURL, Node.js, Python, and n8n.
- Preview the image at its actual display width.
- Confirm the message fits on one screen with no clipped lines.
- Check contrast in both light and dark themes.
- Add alt text that describes the image, not just the caption.
- Confirm the theme and width match the rest of the set.
- Check that the longest line and any table fit without horizontal crowding.
- Keep the Markdown source in version control.
- Re-export when the content changes; do not edit text inside a bitmap.
The last point is worth stating plainly: once you patch text directly inside a PNG, the image and its Markdown source have diverged, and every future edit compounds the problem. Re-exporting takes seconds and keeps the source authoritative.
What is the best image size for social media? There is no single best size, but a 1200-pixel-wide canvas is a practical default: it stays sharp on high-density displays and keeps line lengths readable. For a LinkedIn post with a link, the platform recommends a 1.91:1 ratio around 1200 x 627 pixels.
Can I turn a long article into one image? You can, but you usually should not. Split it into a thread of cards with one idea per card instead.
How much alt text can I add? On X (Twitter), the image description box accepts up to 1,000 characters per image, based on X's public help documentation. Verify the current limit before relying on it.
Does MarkdownToImage have an API? Yes. The API accepts a POST request with a Bearer token and supports PNG, JPEG, WebP, or PDF output. See the API documentation and the integration guide.
How do I keep cards consistent? Use the same theme, code style, and width across the set, and keep the source Markdown in version control.
Platform guidance checked on August 3, 2026: X image descriptions and LinkedIn custom image specs. The MarkdownToImage parameters match the API documentation.
Platform image specifications and alt text limits change without notice. Re-check the two platform links above before you bake any specific number into a template or an automated pipeline.
Turn one Markdown source into a ready-to-post image now: open MarkdownToImage, paste your next update, and export it as a 1200-pixel-wide card.