Markout and AI-generated code

[fcapolini]

Markout, AI, and the Future of Maintainable Code

I've been thinking a lot about where web development is heading, especially with the rise of AI code generation. After some reflection and discussion, I realized something important:

What makes Markout user-friendly for humans is exactly what makes it AI-friendly.

And that has powerful implications for maintainability.

The Alignment

1. HTML as the Primary Artifact

• For you: You see the actual page. No hidden virtual DOM or complex abstraction layer.
• For AI: The output is the final artifact. The AI doesn't need to generate code that produces HTML—it just generates HTML directly.
• For maintenance: What you see in the source is what you get in the browser. The code is the documentation.

2. Declarative, Not Imperative

• For you: You state what you want (e.g., :class-valid=${!error}), not the steps to achieve it.
• For AI: LLMs excel at generating declarative statements, not complex imperative logic with state management and side effects.
• For maintenance: Predictable behavior means fewer surprises. The rules are few and explicit.

3. Plain JavaScript for Logic

• For you: No new templating language or framework-specific API to learn.
• For AI: LLMs are trained on JavaScript. They generate correct, idiomatic code more reliably.
• For maintenance: You use existing JavaScript knowledge—no need to reference a framework-specific API.

4. Components are HTML Fragments

• For you: Open a component and immediately understand it.
• For AI: Generate a complete component as a single, coherent HTML block.
• For maintenance: Everything lives in one place. Reduced context switching.

5. Kits Provide a High-Level Vocabulary

• For you: bs-navbar ::items=${[...]} replaces 22 lines of boilerplate.
• For AI: Uses the same high-level tags. Less to generate, fewer errors.
• For maintenance: Cleaner, more concise code. Easier to review.

The Virtuous Cycle

This creates a powerful loop:

1. You write the initial structure or prompt an AI.
2. The AI generates Markout code—simple, declarative, and direct.
3. You review and refine the HTML and JavaScript.
4. The compiler catches errors before runtime, with file and line numbers.
5. The codebase remains accessible, understandable, and safe to change.

The AI can even help with debugging because the code flow is so linear and clear.

The Real Impact: Maintainability

The principles that make Markout friendly to both humans and AI directly translate to long-term maintainability:

✅ The code is the documentation. No mental mapping from framework to output.
✅ Reduced context switching. Everything lives in one place.
✅ Explicit behavior. No "magic" merging or implicit rules.
✅ Compiler as safety net. Errors caught at compile time, in your editor.
✅ Safe refactoring. Change one thing, and the compiler tells you what broke.

The Honest Trade-Off

Yes, the ecosystem is smaller than React's. You won't find a library for every use case. But the system is designed to make building and adapting components straightforward—wrapping custom elements with :prop- and :on-, or defining your own kits.

It's a trade-off: a deeper, more tailored codebase for a shallower, more flexible ecosystem.

Where We're Going

I believe tools that keep the web native, declarative, and simple will be the foundation of the next generation of AI-assisted development. Markout's philosophy aligns perfectly with that future.

I'd love to hear your thoughts. How are you thinking about AI in your development workflow? What would make Markout even better for the AI era?

---

Let's discuss. 🚀

---

This post is available under the same license as the project itself. Feel free to adapt and share it.