⚡️ Major Refactor: Say Goodbye to Async in block and inline Parsers

[mayank1513]

Hey folks! 👋

I'm excited to share a major refactor that’s underway for mdast2docx and the surrounding plugin ecosystem. This change simplifies the core plugin structure and makes the system much more deterministic and easier to use. I'm rolling out a major optimization to the mdast2docx plugin system — and it's a big one for both performance and developer experience.

---

😬 The Issue

To support image processing (e.g., downloading or decoding images), the block and inline plugin methods were originally made async. This meant that every plugin, even those that didn’t need async, had to return promises — leading to extra overhead, unnecessary complexity, and slower execution overall.

---

🚀 The Optimization

We’re moving image processing into a separate, dedicated pipeline, handled during the preprocess phase — before any block or inline rendering begins.

This unlocks a huge win:
✅ All block and inline plugin methods can now be fully synchronous.

---

🔧 Updated Plugin Interface

⛔️ Before (Async-heavy):

block?: (...) => Promise<(Paragraph | Table)[]>;
inline?: (...) => Promise<InlineDocxNodes[]>;
preprocess?: (tree: Root) => void;

✅ After (Optimized and sync):

block?: (...) => (Paragraph | Table)[];
inline?: (...) => InlineDocxNodes[];
preprocess?: (tree: Root) => Promise<void>; // Only this remains async

---

⚡️ Why This Matters

• 🚀 Faster execution: No more unnecessary async chains in plugin pipelines.
• 🧠 Simpler code: Plugin authors no longer need to await everything.
• 🧪 Better performance in large documents: No async bottlenecks in rendering.
• 🔩 Better separation of concerns: Image resolution and conversion is now a one-time async pass at the start, instead of being embedded in every node traversal.

---

This change might require minor tweaks in your custom plugins — just remove async/await from block and inline methods. Everything else stays familiar.

I’m genuinely excited about how much leaner and faster things already feel with this change — especially for large document generation and batch processing. Let me know what you think or if you hit any edge cases!

Cheers 🙌