Markdown and Mermaid

crystl opens markdown files in its own viewer, in the right sidebar beside the terminal. A file opens rendered by default: headings, lists, tables, code blocks, and Mermaid diagrams, drawn the way you would read them on GitHub. One button switches to the source when you want to edit it.

Agents use the same viewer. When an agent writes a plan, a runbook, or a diagram of your architecture, it can put the rendered file in front of you instead of printing it into the terminal.

Opening a file

• From the sidebar. The markdown view is one of the right sidebar’s views. Cmd + ] and Cmd + [ cycle the views, and a first press opens the sidebar if it is closed. See keyboard shortcuts.
• From the files drawer. Use the edit action on a .md file in the files drawer, and the sidebar switches to the viewer with that file open. Agent instruction files such as CLAUDE.md and AGENTS.md are the exception: they open in their own agent file editor.
• From an agent. crystl markdown show <path> opens a file from the agent’s gem. See for agents below.

Settings → General → terminal → Open markdown files with chooses crystl’s own viewer or your system’s default app for markdown. See settings.

View and edit

The viewer has two modes, and a button in its corner switches between them:

• view shows the rendered document. This is the default.
• edit shows the markdown source, ready to type into.

The button names the mode you will switch to: it reads edit while you view, and view while you edit.

Switching modes never touches your draft. The text, the cursor position, the undo history, and any unsaved change all stay as they were. So you can edit a table, switch to view to check it, and switch back to keep editing.

Links to a heading in the same document ([setup](#setup)) scroll to that heading in view mode.

Mermaid diagrams

A fenced code block tagged mermaid renders as a diagram in view mode:

```mermaid
flowchart LR
  lead[lead shard] --> parser[parser worker]
  lead --> tests[tests worker]
  parser --> merge{merge to main}
  tests --> merge
```

The diagram draws in place, in the same position as the code block in the source. Every diagram type that Mermaid 11 supports works: flowcharts, sequence diagrams, class and state diagrams, entity-relationship diagrams, Gantt charts, and the rest. Diagrams use a dark theme to match the app.

Rendering is offline. crystl ships the markdown and Mermaid libraries inside the app, so a diagram renders without a network connection and the file’s content never leaves your machine.

When a diagram has an error

A diagram with a syntax error does not stop the rest of the document. In its place, the viewer shows the message Could not render this Mermaid diagram. Click edit to correct it., then Mermaid’s own error, then the diagram’s source. Switch to edit, fix the line, and switch back to view to check it.

Mermaid’s syntax is documented at mermaid.js.org. Agents like Claude Code or Codex write it well, so you can also ask the agent to draw the diagram for you.

Remote images

An image in a markdown file can point at a web address. If the viewer loaded it as soon as you opened the file, the image’s host would learn your IP address, the time, and which document you opened. That matters when you preview someone else’s README.

So the viewer does not load remote images on open. Each one shows as a placeholder that names its host and says why it is held back. Click Load on the placeholder to load that one image. When a document holds back two or more images, a Load all button appears too.

When you load an image, crystl fetches it in a private session that writes nothing to disk. A loaded image stays loaded while you edit the same file. When you open another file, crystl forgets it. Images stored inside the file itself (data: images) display straight away. There is no setting for this, because the safe behavior is the only behavior.

What the viewer will not run

The viewer shows a document. It does not run it. crystl removes scripts, forms, input fields, and embedded style sheets from the rendered page, and it draws Mermaid diagrams in Mermaid’s strict security mode. A markdown file from an untrusted repository can do no more than display text, tables, and diagrams.

For agents

crystl markdown show <path> opens one of the gem’s markdown files in the viewer. It opens in view mode by default, so an agent that has just drawn a diagram can show you the diagram and not its source:

crystl markdown show docs/architecture.md               # rendered, diagrams drawn
crystl markdown show docs/architecture.md --mode edit   # the source
crystl edit CHANGELOG.md                                # short alias; opens the source

crystl markdown list finds the gem’s markdown files. Both commands are free on every tier. The file must be a .md file inside the calling gem, and the command works only on the gem you are looking at. To stop agents from opening the sidebar on their own, turn on the block in Settings → General → Workbench. Full details are in the CLI reference.