Markdown preview

A Markdown file opens in an Editor tab in the right pane, as a Preview: headings, lists, tables, code and pictures laid out as a page. The Preview also reads the HTML a README tends to carry, and it draws Mermaid and PlantUML diagrams where their code blocks sit.

Preview and Code

Any .md or .markdown file opens this way. Double-click it in the Files panel, choose Open File in the command palette, press Ctrl+O outside a terminal, or click a path that a tool call shows in a chat. Follow Edited Files, in the chat composer’s overflow menu, opens the files the agent works on as it goes.

Two icons at the right end of the row above the file switch between the modes: an eye for Preview and a pair of angle brackets for Code. Code shows the numbered source for editing, and the same row gains B, I, H, List and Link buttons that format the selection. Open Markdown Preview in the right-click menu also takes you back to the Preview. A Markdown file over 256 KiB opens in Code, with a notice and a Render preview button.

On Linux and Windows, Sirio watches the file on disk. When an agent writes to it and you have no unsaved edits, the tab takes the new text at once and the Preview redraws, so you can read a plan while the agent is still writing it. On macOS, the tab reads the file again when it takes focus, for example when you click into it. If you do have unsaved edits, Sirio keeps them and shows “This file changed on disk.” with Reload and Keep.

A relative link to a file in the same folder or below it opens that file in Sirio. A web link opens in your default browser.

HTML

The Preview reads the HTML a README typically mixes into its Markdown: <h1> to <h6>, <br>, <hr>, <b> and <strong>, <i> and <em>, <a href>, <code> and <kbd>, <blockquote>, <pre>, <details> with its <summary>, and <img> with a width.

Sirio translates those tags into its own Markdown blocks and draws them itself, so a README’s HTML only ever lays out text and pictures. Scripts, styles, frames, forms, embedded objects and inline SVG disappear along with everything inside them. Any other tag drops away and leaves its text in place.

Sirio ignores align, so a logo in <p align="center"> sits at the left edge of the column. An HTML table or list comes through as one paragraph per cell or item, and a <details> block shows its summary in bold with the rest open beneath it. An <img> keeps a pixel width and ignores a percentage.

A paragraph that holds a single picture, on its own or inside a link, shows the picture, up to the width of the column. A picture inside a sentence, or a row of badges, shows as its alt text, which you can click. Sirio reads a relative picture path from the Markdown file’s folder, and loads pictures from the web as well.

Diagrams

A code block tagged mermaid becomes a Mermaid diagram, and one tagged plantuml, puml or uml becomes a PlantUML diagram. Until the diagram is ready, and whenever Sirio cannot draw it, the block shows as code.

Sirio draws Mermaid itself, inside the app, with nothing to install. The diagram takes the Preview’s own background, text and border colours, so it matches the appearance you chose, and a change of appearance redraws it.

PlantUML diagrams come from the plantuml on your PATH. Sirio runs it inside PlantUML’s own sandbox, with no network and no local includes, and refuses any release older than 1.2023.9, because older releases have published ways out of that sandbox. Sirio wraps a source in @startuml and @enduml unless it opens with an @start line of its own, such as @startmindmap, as GitHub and GitLab do. Each run gets 15 seconds, and Sirio runs one PlantUML diagram at a time. After you install plantuml, close the file and open it again to draw its diagrams.

When Sirio cannot draw a diagram, a one-line note under its code says why: no plantuml and no server, a version too old to sandbox, a syntax error with its line when PlantUML reports one, a timeout, an error from the PlantUML server, or a source over 64 KiB.

Sirio renders diagrams in the background, so the Preview keeps scrolling while they draw, and it keeps every finished diagram in a cache on disk: ~/.cache/Sirio/diagrams on Linux (under $XDG_CACHE_HOME when you set it), ~/Library/Caches/Sirio/diagrams on macOS and %LOCALAPPDATA%\Sirio\cache\diagrams on Windows. A diagram you have seen before comes straight from the cache.

A PlantUML server

Settings → General → Markdown preview holds a Local PlantUML row, which shows where Sirio found plantuml or says that it is not on PATH, and a PlantUML server URL field. The field starts empty, and an empty field keeps every diagram on your machine.

Once you name a server, Sirio sends a diagram’s source to it whenever the local plantuml is missing or too old to sandbox. That takes the source of your diagrams off your machine, so choose a server you trust with it, such as one you host yourself. A server gets 10 seconds to answer. Sirio saves the field as you type, diagrams that failed try again with the new setting, and Clear empties the field.

Wide content

The Preview sets its text in a column 720 pixels wide. In a wider pane the column sits in the middle. In a narrower pane the column keeps its width and the page scrolls sideways, with a scrollbar along the bottom, so a paragraph never rewraps into a thin strip. To give the Preview more room, drag the divider between the two panes or hide a side panel: Ctrl+Shift+I toggles the right panel and Ctrl+Shift+S the sidebar, or Ctrl+Shift+R and Ctrl+Shift+D on Windows.

Selecting text

Drag across the Preview to select text, over as many paragraphs as you like. A double-click takes a word, or one segment of a path or a branch name: / and \ separate segments, while -, . and _ stay inside one. A triple-click takes the whole paragraph, one list item, or one line of a code block. Ctrl+C, or Cmd+C on macOS, copies the selection, with a blank line between blocks as on the page. A click that selects nothing still follows a link, so a README’s links keep working.

Sirio holds one selection at a time across the whole app. Code keeps the editor’s own selection, with Cut, Copy and Paste in its right-click menu; see The editor.