Coming soon! The Kael'Nyrin Scrolls: The Atlas Edict

Code editor displaying Mermaid flowchart and diagram

Captain Walker

Using VSCode to create and edit Mermaid files

analysis, code, flowchart, insight, mermaid, process, thinking, visualisation, VSC, VSCode

Estimated reading time at 200 wpm: 14 minutes

The word ‘code’ is enough to send people into sudden panic attacks. If you had one, or are about to, please act in your own best interests and leave now. What is presented is a pathway and method for analysing documents, creating diagrams and gaining insights into their contents. It’s reusable, and tweakable. If you don’t like reading and learning – this is not for you.

Whether or not you agree our Fat Disclaimer applies

If you wish to continue, you do so at your own speed and effort. This is my notes. It is not a hand-holding tutorial. Some trial and error is necessary to learn.

Pre-requisites:

  1. Internet access (you may incur costs)
  2. A Windows 11 computer fully updated, and in your full legal possession and control. If you don’t have one you may incur costs.
  3. Visual Studio Code (VSC) installed – you find it and install it from Microsoft. It’s free – yes!
  4. Access to Microsoft Copilot AI (- may incur costs).

And if you did the usual quick scroll of article and thought ‘OMG! That’s gonna take hours,’ there is a non-clinical label in waiting for you – but you may know it already – cuz types like you brag about it to their friends. I’m totally uninterested in readership or hit counts. I put a lot of my learning up here for the benefit of a minority of people. Some benefit, some don’t – I don’t care who, or the numbers. It’s my diary of learning and exploration.

1. The Value of Mermaid for Process Visualisation

Mermaid is a text-based diagramming tool that allows complex processes to be described using a simple human-readable syntax. That can then be transformed into something visual. People normally think about it as ‘flow charts’. In clinical, legal and administrative settings, this is particularly valuable. Pathways, referral workflows, and decision trees change frequently. The techniques can be used in physics, mathematics, software design and much more. How do you ‘see’ what’s happening and what’s changing or changed? Maybe you’re one of those people who likes to read dense text for hours and ‘get your own picture’. That’s fine – cuz everybody has ‘individual choice’!

Mermaid offers several practical advantages:

  • Version control: because diagrams exist as plain text, every change is diffable and reversible.
  • Collaboration: clinical and technical staff can review and update the same source file without specialised diagramming software.
  • Consistency: diagrams can be regenerated from a single source, reducing the risk of stale or duplicated images in documents.
  • Integration: Mermaid diagrams render natively in Markdown previews, GitHub, and many documentation platforms.

The challenge for newcomers is not Mermaid syntax itself, but the surrounding tooling: choosing the correct file extension, configuring VSC, [which is not about ‘coding’] and understanding which Copilot Chat mode will actually modify a file rather than simply generate a preview.

2. File Standards for Mermaid in VSCode

2.1. Preferred extension: .mmd

The standard file extension for standalone Mermaid files is .mmd. The Mermaid Chart extension and related tooling recognise this extension natively, assign the correct file icon, and enable syntax highlighting and live preview automatically. Using .mmd also ensures that Copilot and other extensions treat the file consistently when applying edits.

However, most importantly, Draw.io can read the alternative .mermaid format. The .mmd extension can simply be renamed as .mermaid. Then double clicking opens it in Draw.io. For more see here.

2.2. Consequences of using non-standard extensions such as .mermaid

A file named test.mermaid may preview correctly, but it is not the recognised standard. The consequences can include:

  • loss of the dedicated Mermaid file icon in the Explorer;
  • inconsistent behaviour from extensions that expect .mmd;
  • confusion when prompting Copilot, since models and extensions are more reliably trained on the standard extension.

Renaming from .mermaid to .mmd or the other way, does not damage the file contents, but VSC tabs can become stale if the rename is performed outside the editor. In such cases, the old tab should be closed and the renamed file reopened.

2.3. Embedding Mermaid inside Markdown files

Mermaid diagrams can also live inside Markdown (.md) files as fenced code blocks:

```mermaid
flowchart TD
   A[Start] --> B[End]

VSC renders these blocks in the Markdown preview without additional extensions. This approach suits documentation files, whereas .mmd is preferable for diagrams that are maintained as standalone artefacts.

3. Required VS Code Extensions

Several extensions are needed to turn VSC into a productive environment for Mermaid diagramming.

3.1. GitHub Copilot Chat

GitHub Copilot Chat provides the conversational interface used to request edits. Two interaction methods are relevant:

  • Inline Chat (Ctrl+I on Windows/Linux, Cmd+I on macOS), which edits the active file directly.
  • Sidebar Chat, which can edit files only when set to Agent mode.

The default sidebar chat mode does not write to files; it returns responses within the chat panel.

3.2. Mermaid Chart extension

The official Mermaid Chart extension adds:

  • live diagram preview panels;
  • syntax highlighting for Mermaid code, including blocks inside Markdown;
  • pan and zoom;
  • export to PNG and SVG;
  • error highlighting with line numbers.

It also supplies the @mermaid-chart chat participant, which is optimised for generating and previewing diagrams. That participant should not be used when the goal is to modify an existing file, because it returns results in the chat panel rather than applying edits.

3.3. Mermaid Markdown Syntax Highlighting

This extension provides colour coding for Mermaid syntax in both .mmd files and Markdown code blocks. It is lightweight and improves readability as diagrams grow in complexity.

3.4. Optional: Mermaid AI Skills for Copilot

Mermaid AI Skills extends Copilot with diagram-specific capabilities. While useful for generating diagrams conversationally, it does not automatically solve the problem of editing a specific file. The correct chat mode and participant selection remain essential.

4. Basic Workflow: Editing and Previewing a .mmd File

Once a .mmd file exists and the Mermaid Chart extension is installed, the basic workflow is straightforward.

  1. Create a new file with the .mmd extension.
  2. Add Mermaid syntax, beginning with a diagram declaration such as flowchart TD.
  3. Save the file.
  4. Open the Mermaid Preview panel using the Preview diagram action that appears above the editor.
  5. Edit the text; the preview updates automatically.

For example, a simple top-down flowchart can be written as:

flowchart TD A[Start Referral] –> B[Collect Patient Info] B –> C[Review Eligibility] C –> D[Send Referral to Specialist] D –> E[End Process]

The preview panel renders this immediately. Saving is important because Copilot Chat reads from disk when applying edits; unsaved changes may not be reflected in subsequent AI operations.

5. Common Beginner Obstacles

Several recurring issues affect newcomers when combining Mermaid with Copilot in VSC.

5.1. AI generates diagrams in the chat panel instead of editing the file

The most common problem is that the AI produces a rendered diagram or code block inside the chat panel rather than updating the open file. This occurs when the wrong chat participant or mode is used. The @mermaid-chart participant, provided by the Mermaid Chart extension, is designed for diagram generation and preview — it does not overwrite existing files.

5.2. Confusing the roles of Copilot Chat modes

Copilot Chat has multiple modes. The default mode answers questions. Edit mode can propose changes. Agent mode is the one that can inspect files, apply diffs, and modify the workspace. Beginners often ask the default or Edit mode to rewrite a file, only to receive a response in chat

5.3. Sidebar chat versus Inline Chat

Two interfaces are available:

  • Inline Chat (Ctrl+I on Windows/Linux, Cmd+I on macOS) appears inside the editor and modifies the active file directly. It is the fastest way to apply a change to the file currently being edited.
  • Sidebar Chat keeps conversation history visible but requires Agent mode and explicit file attachment to edit files.

Beginners sometimes expect the sidebar chat to behave like Inline Chat, but it does not modify files unless the correct mode and context are set.

5.4. Stale tabs after renaming a file outside VS Code

When a file is renamed in the operating system rather than through the VSC interface, the open tab continues to point to the old path. The tab title may show a mixed state such as test.mermaid (test.mmd). The solution is to close the stale tab and reopen the renamed file from disk.

5.5. Explorer panel showing Timeline view instead of folder contents

The Explorer sidebar can display views such as Timeline, Outline, or Source Control. If the folder tree is not visible, the file may appear impossible to locate or rename. Collapsing non-folder views or using the operating system’s file manager resolves this

6. How to Make Copilot Edit the File Directly

The following methods make Copilot apply changes to the actual .mmd file rather than returning results in the chat panel.

6.1. Using Inline Chat for immediate in-file edits

Inline Chat is the most direct method. With the target .mmd file open and active, press:

  • Ctrl + I on Windows and Linux
  • Cmd + I on macOS

A chat input appears inside the editor. Type a plain instruction such as:

Replace this with a patient referral flowchart including GP referral, triage, specialist review, treatment, and follow-up.

Copilot proposes a diff directly in the file. Press Accept to keep the changes or Discard to reject them. This method bypasses the sidebar entirely and is ideal for single-file edits.

6.2. Using Agent Mode in the sidebar chat

The sidebar chat panel is useful when the conversation history needs to remain visible. To make it edit files, switch the mode selector at the bottom of the chat panel to Agent. Agent Mode can inspect open files, apply diffs, and modify the workspace. The default chat mode answers questions; it does not write to files.

6.3. Avoiding @mermaid-chart participants for file edits

The @mermaid-chart participant, provided by the Mermaid Chart extension, is designed for diagram generation, preview, and rendering. It produces diagrams inside the chat panel. It does not overwrite the source .mmd file. For edits, use the default Copilot agent rather than @mermaid-chart.

6.4. Attaching files explicitly and naming them in prompts

When using the sidebar chat, attach the file to be edited. This can be done by:

  • clicking the + button above the input box and selecting the file;
  • typing # followed by the filename;
  • ensuring the target file is the active editor and naming it explicitly in the prompt.

For example:

Update test.mmd to add a decision diamond after Review Eligibility with two paths: Approved and Not Approved.

Explicit naming reduces ambiguity and ensures the diff is applied to the correct file.

6.5. Accepting diffs with Keep or Undo

When Copilot proposes changes in Agent Mode, the modified lines are highlighted as a diff in the editor. Two controls appear:

  • Keep: applies the proposed changes.
  • Undo: reverts them.

After keeping the changes, the Mermaid Preview panel updates automatically if it is already open. This diff-and-accept cycle is the standard way to review AI-generated edits before committing to them.

7. Building Diagrams from External Documents

Clinical processes are often described in Word documents, PDFs, or emails. Copilot Agent cannot read binary formats such as .docx directly; it can only inspect plain text files open in the workspace.

7.1. Why .docx files cannot be read directly

A .docx file is a compressed archive of XML documents, images, and metadata. Copilot Chat does not parse this format. Attempting to attach a .docx file will fail or produce no useful content. The text must be extracted first.

7.2. Converting source material to plain text

The source document should be converted to .txt or .md. Options include:

  • opening the .docx in Word and using File → Save As → Plain Text;
  • copying the relevant text into a new file in VSC and saving it as .txt;
  • exporting from another tool to Markdown.
  • exporting from .pdf to plain text.

Only the relevant sections need to be included. A focused source file produces better results than a long document full of boilerplate. Copilot or other AI, is not fussy about the loss of formatting that would appear when .docx or .pdf is converted to .txt or .md. The important thing is that the contents remain the same.

7.3. Attaching the text file to Copilot Chat

Once the text file is saved in the workspace, attach it to the chat panel. This can be done by clicking the + icon above the input box and selecting the file, or by typing # followed by the filename. The file should appear as a pill above the prompt, alongside the target .mmd file.

7.4. Prompting for a complete flowchart update

With both files attached, issue a clear instruction such as:

Read patient-referral-easy-read conv.txt and update test.mmd with a Mermaid flowchart that maps the full patient referral process from GP to specialist.

The Agent will read the source text, infer the steps and decisions, and propose a diff for test.mmd. Review the diff, click Keep, and inspect the preview.

8. A Repeatable Workflow for Continuous Diagram Development

After the initial diagram exists, most work consists of refinement. A consistent workflow prevents repeated confusion about which chat mode to use.

8.1. Keeping the source text and target .mmd file open

Maintain three elements on screen:

  • the source text file or notes;
  • the test.mmd editor;
  • the Mermaid Preview panel.

This layout allows each change to be traced from source to syntax to rendered output.

8.2. Iterating through prompt, diff, keep, and preview

Each iteration follows the same steps:

  1. Ensure Agent mode is selected in the sidebar chat.
  2. Confirm both the source text and test.mmd are attached.
  3. Type a specific instruction, naming the file to be modified.
  4. Review the proposed diff in the editor.
  5. Click Keep to apply or Undo to reject.
  6. Check the Mermaid Preview panel for the visual result.

For example:

Add a node for GP triage before Review Eligibility in test.mmd.

Make the Not Approved path loop back to Collect Patient Info in test.mmd.

Specific, scoped prompts produce more reliable diffs than vague requests.

8.3. Verifying changes in the Mermaid Preview panel

The preview panel is the final arbiter. Syntax errors, missing connections, or incorrect node shapes are immediately visible. If the preview fails to render, the error message in the panel or editor usually points to the offending line. Fix the syntax manually or prompt Copilot to repair it.

9. Summary of Key Principles

Working productively with Mermaid in VSC depends on a small number of distinctions.

9.1. Match the chat mode to the task

Different Copilot Chat interfaces produce different outcomes:

  • Inline Chat edits the active file directly.
  • Sidebar Chat in Agent mode can edit files when the target is explicitly attached or named.
  • The @mermaid-chart participant generates and previews diagrams in the chat panel; it does not overwrite files.

Using the wrong mode or participant results in diagrams appearing in chat rather than in the source file.

9.2. Use the standard .mmd extension

The .mmd extension is recognised by the Mermaid Chart extension, provides the correct file icon, and behaves predictably with Copilot. Non-standard extensions such as .mermaid may preview correctly but can cause inconsistent tooling behaviour in VSC.

9.3. Reopen files after external renames

Renaming a file outside VSC leaves the open tab pointing to a stale path. Close the old tab and reopen the renamed file before continuing work.

9.4. Be explicit about which file to modify

Ambiguous prompts often lead to responses in the chat panel or new untitled files. The most reliable prompts name the target file, attach any source files, and describe the change in plain language. For example:

Read patient-referral-easy-read conv.txt and update test.mmd with a Mermaid flowchart showing the complete patient referral pathway.

These principles reduce friction and make it possible to iterate rapidly on complex diagrams.