Making diagrams with syntax-highlighted code snippets

In this article, we'll look at a scenario that commonly comes up in diagramming for software engineers, technical writers, data scientists, and plenty of others: adding small code snippets to diagrams. If your target audience is technical, you can give their brain a break by using well-formatted and properly syntax-highlighted code snippets. Vexlio allows you to do that right out of the box.

Introduction

Generally speaking, a diagram may be light on text and heavy on other visual elements such as simple boxes and arrows. For many types of technical diagrams, adding small code blocks or code snippets can lend some much-needed concreteness to otherwise abstract concepts.

Vexlio has built-in support for automatic code syntax highlighting for over 50 languages. No need to resort to third-party plugins or resign yourself to taking screenshots of your IDE: Vexlio gives you the ability to add highlighted code blocks right out of the box. Here's a few places you might find it helpful:

A simple C-style array diagram with highlighted syntax.

• Variable or class definitions in code alongside elements in a UML diagram
• JSON snippets in your API architecture diagrams
• An implementation sketch shown next to an algorithm flowchart
• HTML snippets in web development education diagrams
• Dockerfile or YAML snippets next to a deployment architecture diagram
• Bash one-liners in your setup docs

Vexlio is a diagramming app all about quality-of-life features, and if you are drawing diagrams for engineering or engineering-adjacent audiences, Vexlio has tools to help you out.

How it works

When you launch the Vexlio app, you'll be presented with a blank canvas and a tool palette on the left side of the screen. To create a syntax-highlighted code block, activate the ​ Create Syntax-Highlighted Code Box tool, or press the keyboard shortcut H. Click and drag with the mouse to create a code text box.

When you release the mouse, the text editor will pop up. Select your language from the dropdown menu at the left side of the context toolbar, and go ahead and paste or start typing your code! Just like your IDE, the syntax highlighting updates automatically as you type.

While Vexlio does not have any code auto-formatting built in, you can use the Tab key for quick indent and unindent.

Features

• Live-updating. Just like an IDE, no-need to rerun highlighting manually, regardless of whether you're typing your code or pasting it in. All code blocks are dynamic and auto-highlighting.

• Highlighting fully exportable. Whether you're exporting to PNG, PDF, or SVG, the syntax highlighting will export perfectly along with the rest of your diagram.

• Multiple themes available. Pick from several builtin themes. If you're interested in seeing more themes (or languages) added, let us know.

• Dark- and light-mode flexibility. The theme you select will automatically change between dark and light modes depending on the mode you're drawing your diagram in.

Deeper benefits

Beyond simple visual appeal, using properly highlighted code blocks in your diagrams has some deeper benefits as well, namely reduced cognitive load and a better developer experience overall, if your audience is primarily developers.

Software engineers and other professionals who work with code spend hours every day staring at code in their IDEs. Syntax highlighting becomes almost a communication channel in its own right, and when faced with code that is presented in simple black and white, it can be mentally jarring. It may take a moment longer to parse the snippet than if it had been properly highlighted.

Similarly, when switching between, say, pages of documentation with diagrams and an IDE, making sure to use proper highlighting can reduce the amount of mental effort it takes to context switch between the two.

Python implementation of a Fibonacci function and corresponding visual.

Tips for using code blocks in your diagrams

Emphasize readability

• Monospace fonts only: Stick with fonts specifically designed for source code (e.g., Fira Code, Source Code Pro) for familiarity and legibility for non-prose symbols.
• Consistent tab width: Use two or four spaces and keep it uniform across all snippets so visual cues remain reliable.
• Avoid visual clutter: Cut irrelevant sections with comment blocks like /* ... */. This illustrates that there's more detail in reality, but the detail is not relevant to the diagram.

Keep it relevant

• Align code with the diagram's focus: If the diagram explains an API endpoint, show the route handler, not unrelated helper functions.
• Match language to audience: A general audience might find YAML easier to parse than the equivalent JSON, even if JSON is the format used in reality.

Keep it short

• Stay under ~5 lines: Enough for context, short enough to digest at a glance. Leave out boilerplate like import statements.
• Link out for full listings: If relevant, provide a "full source" reference or footnote so readers can dive deeper offline.

Frequently asked questions

What languages does Vexlio support for syntax highlighting?

Vexlio comes with support for over 50 languages, including common programming and markup languages like:

• JS
• Python
• Java
• C++
• HTML

...and some other mainstream but less common ones like:

• Julia
• R
• ARM and x86 assembler

Is there a limit on how long the code blocks can be?

There's no explicit limit, but make sure you're focused on readability, and don't try to pack too much code into your diagram.

Why is my code block all one color / the wrong colors?

The most common cause of this is mistaken or incorrect syntax for the language. Vexlio's code blocks do not perform any type of code analysis like syntax checking, brace or paren matching, etc. So, give your code a once-over.

Is there any way to perform automatic line numbering?

Currently no, but if this is an important feature for you, please let us know!

How do I change the theme for an existing code block?

1. Select the code box with the normal Select, Move, Edit tool.
2. In the right-hand Sidebar → Text panel, open the "Color Theme" dropdown and pick any of the bundled palettes.
3. The change applies instantly; no need to re-paste your code.

Does syntax highlighting survive when I export to SVG/PDF and paste the diagram into Confluence or Notion?

Yes. Vexlio writes properly colored text spans into both SVG and PDF exports. When you export as SVG or PDF, and paste or attach in Confluence/Notion/wikis/etc, the exact colors and font styles remain intact. And as an added bonus, the text survives as well, so it is fully copy-pasteable. Vexlio doesn't rely on external styling like CSS, so the colors are self-contained.

Wrapping up

Adding syntax-highlighted code blocks can turn a good technical diagram into a great one by backing abstract concepts with real, concrete examples. With Vexlio's builtin highlighter you can add formatted snippets in seconds, keep them readable, and edit them later within the diagram itself. Next time you sketch an architecture, flowchart, or UML diagram, try embedding a small, focused code block.