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:
- Internet access (you may incur costs)
- A Windows 11 computer fully updated, and in your full legal possession and control. If you don’t have one you may incur costs.
- Visual Studio Code (VSC) installed – you find it and install it from Microsoft. It’s free – yes!
- 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+Ion Windows/Linux,Cmd+Ion 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.
- Create a new file with the
.mmdextension. - Add Mermaid syntax, beginning with a diagram declaration such as
flowchart TD. - Save the file.
- Open the Mermaid Preview panel using the Preview diagram action that appears above the editor.
- 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+Ion Windows/Linux,Cmd+Ion 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 + Ion Windows and LinuxCmd + Ion 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
.docxin 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
.pdfto 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.txtand updatetest.mmdwith 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.mmdeditor; - 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:
- Ensure Agent mode is selected in the sidebar chat.
- Confirm both the source text and
test.mmdare attached. - Type a specific instruction, naming the file to be modified.
- Review the proposed diff in the editor.
- Click Keep to apply or Undo to reject.
- 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-chartparticipant 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.txtand updatetest.mmdwith a Mermaid flowchart showing the complete patient referral pathway.
These principles reduce friction and make it possible to iterate rapidly on complex diagrams.










PROVISIONAL ROMANTIC AGE-GAP COMPLIANCE AND CONSENT AGREEMENT
Captain Walker