The Dish
Imagine this: you’ve just finished writing a beautiful markdown document—maybe a README for your open-source project, a blog post about your latest recipe app, or even a YouTube video description. You hit preview, and half your images are broken. The alt text is missing, the URL has a typo, or the syntax is just plain wrong. That sinking feeling? We’ve all been there. It’s like spending hours caramelizing onions only to realize you forgot the salt.
But what if you could fix that mess in seconds with a few lines of code? That’s exactly what the latest trend from Google IO is serving up: using AI and JSON schemas to automatically validate and correct markdown image syntax. It’s not just a developer trick—it’s a game-changer for any content creator who works with text and images. And right now, it’s trending because it solves a pain point that touches everyone from YouTubers to technical writers.
This isn’t about some abstract theoretical concept. It’s about taking a structured data approach—JSON schemas—and pairing it with AI to catch errors, suggest fixes, and even rewrite broken image syntax on the fly. Think of it as a sous-chef for your markdown: precise, fast, and never missing a detail. In this article, I’ll break down the technique, give you the ingredients (tools and concepts), and show you how to create your own viral video around this topic.
The Technique
The core technique here is deceptively simple: define a JSON schema that describes what a valid markdown image should look like, then use an AI model (like the one powering Cursor AI or Google’s own tools) to parse your markdown, validate each image against that schema, and fix any mismatches. Let me walk you through the steps, because the magic is in the execution.
First, you need a JSON schema. A schema is just a set of rules written in JSON. For a markdown image, the schema might specify that each image must have a `src` (URL), an `alt` (alternative text), and optionally a `title`. The schema can also validate that the URL is properly formatted, that the alt text isn’t empty, and that the syntax uses the correct brackets and parentheses. For example: ``. A schema might look like this:
```json
{
"type": "object",
"properties": {
"alt": { "type": "string", "minLength": 1 },
"src": { "type": "string", "format": "uri" },
"title": { "type": "string" }
},
"required": ["alt", "src"]
}
```
Now, you feed your markdown document to an AI tool that understands both markdown and JSON schema. The AI parses the markdown, extracts every image syntax, and runs it against the schema. If an image fails—say the alt text is missing or the URL has a typo—the AI can either flag it or automatically correct it based on context. This is where the “why” gets interesting: most home cooks (or, in this case, developers) try to fix images manually, which is error-prone and slow. The AI does it with the precision of a Michelin-starred chef seasoning a dish.
The technique that makes this work is the combination of structured validation (the schema) and generative AI. The schema gives the AI a clear target, so it doesn’t hallucinate or guess. And the AI brings flexibility—it can infer missing alt text from surrounding content, fix broken URLs by checking against a known base, or even suggest better titles. This isn’t just a regex replacement; it’s intelligent content repair.
Ingredients & Substitutions
To cook up this solution, you need a few key ingredients. First, a markdown document with images—any file will do, but the more complex, the better for a demo. Second, a JSON schema validator library, like Ajv for JavaScript or the built-in `jsonschema` module in Python. Third, an AI model capable of code generation and text understanding. Tools like Cursor AI, GitHub Copilot, or Google’s Gemini are perfect for this. Finally, a little bit of scripting glue to connect everything.
If you don’t have access to a paid AI tool, you can start with free alternatives. For example, use Python with the `mistune` library to parse markdown, `jsonschema` to validate, and a free tier of OpenAI’s API or even a local model like Llama 3. The substitution here is about flexibility: you don’t need the fanciest AI; you need one that can understand markdown syntax and follow a schema. For dietary restrictions (like not wanting to use cloud APIs), run everything locally with Ollama and a small model.
For creators who aren’t developers, don’t worry—you don’t have to write the code from scratch. There are already tools and plugins that do this, like the “Markdown Image Fixer” extension for VS Code or the built-in validation in Obsidian. The key is to understand the concept so you can explain it to your audience. Think of it like learning the difference between baking soda and baking powder: you need to know the science, even if you use a box mix.
Common Mistakes
What most home cooks get wrong here is trying to fix images with brute force—using regular expressions or manual find-and-replace. That’s like trying to slice a tomato with a dull knife: messy and ineffective. Regular expressions can’t handle nested brackets, escaped characters, or the nuanced context of markdown. They’ll miss half the errors and break the other half.
Another common mistake is ignoring the schema entirely. Without a schema, the AI has no guardrails. It might “fix” an image by removing it entirely, or change a valid URL into something nonsensical. You need that structured foundation. I’ve seen creators spend hours debugging why their AI-generated fixes broke all their images, only to realize they skipped the schema step. It’s like trying to bake a soufflé without measuring the egg whites—you’re setting yourself up for a collapse.
Finally, many people forget to handle edge cases. What about images in code blocks? Or images with relative paths? Or images that are actually embedded SVGs? A good schema accounts for these. If you don’t test with a diverse set of markdown files, you’ll miss these gotchas. Always validate with a sample that includes inline images, reference-style images, and images with titles.
Pro Tips
Here’s a restaurant secret: use the schema to not just fix, but also enhance. For example, you can add a rule that requires all images to have descriptive alt text (not just “image.jpg”). The AI can generate alt text by analyzing the surrounding text or even the image content itself if you have a multimodal model. This turns a bug fix into a quality improvement—like adding a finishing salt to a dish that’s already good.
Another pro tip: cache your validations. If you’re processing a large document, don’t re-validate every image every time. Store the results in a JSON file and only re-check changed lines. This speeds up your workflow dramatically. I’ve used this on a documentation site with 500+ images, and it cut processing time from minutes to seconds.
For presentation, show the before-and-after in your video. Use a split screen: on the left, the broken markdown with red highlights; on the right, the fixed version with green. Run the AI fix in real time. This visual proof is what makes a video go viral—it’s satisfying, educational, and immediately useful. And don’t forget to explain the schema visually, maybe as a diagram. Your audience will thank you.
The Verdict
Is this technique worth trying? Absolutely. If you’re a content creator who writes markdown—for blogs, documentation, or even video descriptions—this will save you hours of tedious work. The difficulty level is moderate for beginners (you need to understand basic JSON and markdown), but intermediate for anyone who’s comfortable with code. The time investment to set up the schema and script is about an hour, but the payoff is immediate and ongoing.
The wow factor is high. Watching an AI fix a dozen broken images in seconds is genuinely impressive, and your audience will love it. I recommend this for any tech-focused YouTube channel, especially if you cover developer tools, AI, or productivity. It’s a perfect 15-minute tutorial that’s both informative and visually engaging. Give it a try—you’ll never manually fix markdown images again.
