# Teaching OpenWiki to Draw: From “No Diagrams” to an Upstream PR > Source: > Published: 2026-07-10 21:01:01+00:00 In [Part 1](https://medium.com/towards-artificial-intelligence/openwiki-source-code-docs-that-write-and-maintain-themselves-a-hands-on-look-fcec781e28e4) I covered what OpenWiki is — LangChain’s take on Karpathy’s “LLM Wiki,” applied to codebases. In [Part 2](https://medium.com/@reachyogeshchavan/b6cfd1180c38) I ran it for real and learned that model choice makes or breaks an agentic doc run. This part is about the thing I *didn’t* get on the first pass, and what happened when I chased it: **diagrams.** It turned into the most satisfying leg of the whole experiment — because it ended not with a workaround in my own copy, but with a pull request against the actual project. OpenWiki produced a genuinely good wiki for my Spring Boot + Angular monorepo — architecture overview, auth flow, domain model, API surface, the works. All accurate, all source-grounded. All prose and tables. Not a single diagram. And for a codebase, that’s a real miss. The fastest way to explain a JWT refresh handshake or how Booking, Event, and Settlement relate isn't a paragraph — it's a picture. A newcomer skims a sequence diagram in five seconds and *gets* it. So the obvious question: can I get OpenWiki to draw? If you want diagrams that live inside a docs-as-code wiki, the format matters. I went with **Mermaid** [1], and the reasoning is worth stating because it’s the same logic that makes OpenWiki itself work: Mermaid is *just fenced markdown* — a ``` mermaid block. It stays diffable, it versions alongside the code, and it renders where the docs already live. (One honest caveat: GitHub and GitLab render it natively; **Bitbucket's file view historically does not**, so verify your host before assuming inline rendering. Agents and Obsidian read it fine either way.) Here’s the thing that clicked. OpenWiki [2] is **prompt-driven** — under the hood it’s an LLM writing markdown files. If it can write a table, it can write a ``` mermaid block. Diagrams aren't a missing *feature*; they're a missing *instruction*. So I ran a deliberately tight, one-off pass on an isolated copy — using Opus, the reliable choice from Part 2 — asking it to add exactly two diagrams and touch nothing else: a sequence diagram of the auth flow, and an ER diagram of the core entities. “Read only the files needed to make these accurate.” It nailed it. Not “plausible-looking” — *accurate*. It opened the actual auth interceptor and read the token lifetimes out of config. The sequence diagram it produced: It even captured the single-in-flight-refresh behaviour — the detail where concurrent 401s queue behind one refresh call — because it read that out of my interceptor. And in the ER diagram it correctly drew one relationship as a “soft link,” having noticed that a foreign-key-shaped column was actually a plain Long with no ORM relation. That's the difference between a diagram that helps and one that lies. Then I tried to render the sequence diagram. It failed. Not the content — the **syntax**. Opus had written a message label like store new token; queue concurrent 401s. In a Mermaid sequence diagram, a semicolon is a *statement separator*. That one ; split the line into a second, malformed statement, and the parser rejected the entire block. On GitHub it would have rendered as nothing — or as a raw error box. The content was correct. A single poison character made it un-renderable. This is the lesson worth carrying: **auto-generated diagrams need a validation pass.** The model gets the meaning right and occasionally gets the grammar wrong, and Mermaid has a few characters — semicolons, pipes, unescaped angle brackets — that quietly detonate inside labels. A mermaid lint step in CI catches this class of bug for free. A one-off prompt gave me diagrams once. But I run openwiki --update on new commits — would the diagrams survive? Would they stay in sync? I didn't want to guess, so I read the source. Two findings changed my whole approach: I also checked whether AGENTS.md could serve as a persistent "please draw diagrams" instruction. It can't — OpenWiki reads that file only to manage its own reference stub, and treats other docs as *source material to document*, not as authoring instructions. Conclusion: a durable diagram capability can’t be a prompt I remember to type. It has to live in the system prompt, and it has to explicitly tell update runs to *keep diagrams in sync* and to *follow label-safety rules.* The quick path was to patch my own copy’s system prompt and move on. But this is open source, and the same gap will bite anyone who runs OpenWiki. So I built it as a **contributable feature** instead. The design, optimized to actually get merged: Everything green: the full test suite (plus the new tests), typecheck, lint, and formatting. This is the question a maintainer will ask, and it has a real answer. A one-off prompt only affects one run. A setting buys three things a prompt can’t: That framing — *durability + correctness + discoverability*, not mere convenience — is what turns “nice idea” into “worth a config key.” Shipping to someone else’s project is as much etiquette as code. The project’s CONTRIBUTING is blunt: **one PR = one change**, and *link an issue for anything non-trivial.* So: A quick note on sequencing, because I went back and forth on it: the textbook move is “open the issue, wait for a maintainer 👍, *then* PR.” But that advice was written for *before* you have code. Once you’re holding a complete, CI-clean, tightly-scoped implementation — and you’re wary of someone else grabbing the issue — opening the PR that references the issue is a legitimate, often *preferred* move. Design discussion and code review happen in one place, and an issue with a linked PR is effectively claimed. CONTRIBUTING only required me to *link* an issue, never to wait for approval. So I opened it. The result of chasing a missing feature through a demo, a bug, a source dive, and a design: Whether or not it merges in exactly this shape, that’s the arc I wanted to share: a prompt-driven tool is *extensible by anyone who reads its prompts*, the failure modes are real but small (a semicolon!), and the most satisfying way to close a gap in an open-source tool is to close it for everyone. [1] “Mermaid — diagramming and charting tool,” official documentation. Available: [https://mermaid.js.org](https://mermaid.js.org) [2] LangChain, “OpenWiki,” GitHub repository. Available: [https://github.com/langchain-ai/openwiki](https://github.com/langchain-ai/openwiki) [3] Y. Chavan, “feat: add optional Mermaid diagram generation (OPENWIKI_DIAGRAMS),” langchain-ai/openwiki, Pull Request #199. Available: [https://github.com/langchain-ai/openwiki/pull/199](https://github.com/langchain-ai/openwiki/pull/199) *← Back to **Part 2** · Start at **Part 1* [Teaching OpenWiki to Draw: From “No Diagrams” to an Upstream PR](https://pub.towardsai.net/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr-b596f352154e) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.