Markdown to Instagram Story

A Tool for Converting Markdown to Instagram Story Images

Sharing long-form text on visually-driven platforms like Instagram is inefficient. Standard captions have poor formatting for readability, and screenshotting text is an unprofessional workaround.

To address this, I've built md-to-story.solberg.is, a free web tool that converts markdown text into a sequence of PNG images, each sized for Instagram Stories (1080x1920px).

Publishing Writing That Flows Across Multiple Screens

The primary use case is publishing a single piece of writing that flows naturally across multiple, sequential story screens. Instead of manually splitting text and creating separate images, this tool automates the process.

The underlying PDF engine, Weasyprint, intelligently calculates content layout and determines where to create page breaks. This ensures that paragraphs, headings, and list items are not awkwardly cut off between slides, resulting in a clean and professional reading experience from one screen to the next.

Core Functionality and Features

The tool operates through a simple web interface requiring no installation.

• Input: Write or paste markdown into the editor.
• Live Preview: Instantly see how the content will be rendered across the series of story images.
• Output: Download a single ZIP file containing the numbered PNG files.

Key features have been specifically implemented for this format:

• Automatic Page Breaks: The conversion engine handles content splitting, ensuring a logical flow.
• 10% Vertical Safe Zones: The tool automatically adds padding to the top and bottom of each image. This prevents critical text from being obscured by Instagram's native UI elements, such as the profile information at the top and the message bar at the bottom.
• Optimized Typography: The design uses the Inter font with sizes and line spacing chosen for maximum readability on mobile devices.

Practical Applications

This tool allows marketers and writers to repurpose existing content or create new material specifically for story-based platforms.

• Repurpose Articles: Convert blog posts into a series of story slides.
• Detailed Announcements: Publish product updates or announcements that are too long for a standard caption.
• Educational Content: Format short guides or tutorials as a multi-part story.
• Share Testimonials: Present customer quotes or case studies in a clean, visual layout.

The objective is to present long-form text in a more digestible format, using a clean design that is native to the platform.

Technical Details

For those interested in the implementation, the project is self-hosted and built with a focus on modern, efficient tooling.

• Hosting: The application runs in a Docker container on a local Mac Mini.
• Runtime & Server: The backend and development server are powered by Bun, which also handles bundling and task running.
• Frontend: The web UI is built with React 19 and the alpha release of Tailwind CSS 4.0.
• Conversion Pipeline: The core process uses Pandoc to convert markdown to HTML, which is then styled and converted to a multi-page PDF by Weasyprint.
• Image Generation: Poppler's pdftoppm command-line utility is used to convert each page of the PDF into a separate PNG file.
• Development Tools: The codebase is linted with Oxlint and formatted with Prettier.