I Built a VS Code Extension to End "README Friction" (And then I broke my own README) 🤦‍♂️

#vscode #opensource #productivity #markdown

Building open-source projects is 90% coding and 10% trying to figure out why your README images look broken on the VS Code Marketplace.

After getting frustrated with the "Push and Pray" workflow—where you push to GitHub just to see if your Markdown rendered correctly—I decided to build DotReadme.

The Problem: The "Carpenter's Door" Irony 🚪
Yesterday, while preparing for the v1.0.0 launch, I fell into the very trap my extension was designed to fix. I used relative paths for my images (media/logo.png). They looked great in my local preview, but once published to Open VSX, everything was broken.

It was a classic "Carpenter's door is always broken" moment. I ended up using my own tool to fix my own documentation.

What is DotReadme? 🛠️
DotReadme is a specialized environment for crafting documentation. It lives inside VS Code and provides:

🎭 Multi-Platform Simulator: See exactly how your README will look on GitHub, VS Code Marketplace, or Open VSX without leaving your editor.

📊 Live Quality Audit: An automated scoring system (A+ to F) that checks for essential sections like Installation, Usage, and License.

🔗 Smart Path Fixer: The feature I should have used—it converts relative image paths to absolute GitHub raw URLs in one click.

🛡️ Badge Inserter: Instantly add shields.io badges with automatic repository detection.

How I Built It 💻
I built this using TypeScript and esbuild, leveraging the VS Code Webview API. One of the biggest challenges was creating a high-performance live preview. I implemented a Debounce logic (500ms) to ensure that the simulator doesn't lag while the user is typing fast.

Open Source & DotSuite
This is the first stable release of the DotSuite ecosystem. I’m a 28-year-old developer (working from Kali Linux 🐉) and I believe documentation shouldn't be a chore.

I’d love to hear your thoughts! What’s your biggest "README fail" story? Let’s talk in the comments!