Instruction file imported from CodeCraftsman-Jr/Simulink-integration (.github/instructions/matlab-live-scripts.instructions.md). Copyright stays with the author.

MATLAB Live Script Generation Rules

Sources:

• github.com/matlab/rules/blob/main/live-script-generation.md (CC BY 4.0)
• MathWorks Help: Plain Text File Format for Live Scripts Requirements: MATLAB R2025a or later

Core Principle

Plain text live scripts are .m files that look exactly like regular MATLAB code but contain special markup comments (%[...]) that MATLAB renders as formatted rich text, equations, images, outputs, and controls in the Live Editor.

All markup is in comments beginning with %[ — regular % comments are still used for code documentation.

Section Structure

%% Section Title
%[text]
%[text] ## Section Heading
%[text] Body paragraph text here.
%
% Regular code comment (not displayed as rich text)
code_here = 1;

• %% starts a new Live Script section
• %[text] ## Heading inside a section creates a subheading
• %[text] alone is a blank line in the formatted text

Text Markup (%[text])

Every live text line starts with %[text] (note the space after the bracket).

Headings

%[text] # Title
%[text] ## Section Heading
%[text] ### Subsection Heading

Inline Formatting

%[text] This is **bold**, *italic*, `monospaced`, <u>underlined</u> text.

Alignment

%[text]{"align":"center"} Centered paragraph.
%[text]{"align":"right"} Right-aligned.

Hyperlinks

%[text] Click [here](https://www.mathworks.com) for more info.

Equations (LaTeX)

Use $equation$ for inline math, $$equation$$ for display (block) math.

Critical: Use \\ (double backslash) for LaTeX commands within the $...$ delimiters:

%[text] Compute the torque $T = \\frac{3P}{2}(\\lambda_d I_q - \\lambda_q I_d)$.
%[text] $$T_e = \\frac{3P}{4}(\\lambda_d I_q - \\lambda_q I_d)$${"altText":"Torque equation"}

Equation attributes (optional JSON after closing $ or $$):

%[text] $\omega = 2\pi f${"altText":"Angular frequency","displayMode":"block"}

Lists

Bulleted List

Each item ends with a trailing backslash \ (except last item):

%[text] - Item one\
%[text] - Item two\
%[text] - Item three

Numbered List

%[text] 1. Step one\
%[text] 2. Step two\
%[text] 3. Step three

Code Blocks in Text

Verbatim block (no syntax highlighting):

%[text] ```
%[text] x = sin(theta);
%[text] ```

MATLAB code example block (syntax highlighted):

%[text] ```matlabCodeExample
%[text] Id = 0;
%[text] Iq = Irated;
%[text] ```

Tables

%[text:table]
%[text] | Header 1 | Header 2 |
%[text] |---|---|
%[text] | Cell A | Cell B |
%[text:table]

Table of Contents

%[text:tableOfContents]{"heading":"Contents"}

Displaying Code Output

DO NOT use fprintf or disp calls to show results in Live Scripts. Instead, drop the semicolon from the expression — MATLAB auto-displays it:

% WRONG - produces ugly fprintf-style output in live script
fprintf('Motor speed: %.1f rpm\n', motorSpeed);

% CORRECT - Live Script shows formatted output cell automatically
motorSpeed     % No semicolon → auto-displayed

This keeps output in the correct inline output cells with proper formatting.

Images

Add images using references to the appendix:

%[text] ![Alt text](text:image:img_001)

Then define in the appendix:

% [img_001]
% image data: <base64 content>

Outputs (%[output:...])

Reference a stored output cell inline:

%[output:out_001]

Then define in the appendix:

% [out_001]
% output data: <data>

Interactive Controls (%[control:...])

%[control:slider:ctrl_001]{"position":[0,100]}
%[control:dropdown:ctrl_002]{"position":[0,50]}
%[control:editfield:ctrl_003]{"position":[0,50]}
%[control:checkbox:ctrl_004]{"position":[0,50]}
%[control:button:ctrl_005]{"position":[0,80]}

Live Editor Tasks (%[task:...])

%[task:task_001]

Appendix Block Format

The appendix goes at the very bottom of the file, after all code and text:

%[appendix]{"version":"1.0"}
%---
%[metadata:view]
% data: {"layout":"inline","rightPanelPercent":40}
%---
%[img_001]
% image data: iVBORw0KGgoAAAANSUhEUgAA...
%---
%[out_001]
% output data: <serialized output>
%---

Complete File Template

%% PMV Motor Controller — MTPA Analysis
%
% PMV_LEV6000V2_IPM — MTPA operating points analysis.
%

%% Setup
%[text]
%[text] ## Setup
%[text] Load motor parameters and configure the operating range.

load('PMV_LEV6000V2_Parameters.m');  % Load Ld, Lq, lambda_pm, P, Irated

%% MTPA Calculation
%[text]
%[text] ## MTPA Calculation
%[text] The MTPA condition minimizes $|\\mathbf{I}|$ for a given torque $T_e$.
%[text]
%[text] Optimal d-axis current:
%[text] $$I_d^* = \\frac{\\lambda_{pm}}{2(L_d - L_q)} - \\sqrt{\\left(\\frac{\\lambda_{pm}}{2(L_d-L_q)}\\right)^2 + I_q^2}$${"altText":"MTPA d-axis current"}

IqRange = linspace(0, Irated, 100);
IdMTPA  = lambda_pm / (2*(Lq - Ld)) - sqrt((lambda_pm/(2*(Lq-Ld))).^2 + IqRange.^2);

%% Results
%[text]
%[text] ## Results

figure;
plot(IdMTPA, IqRange);
xlabel('Id (A)'); ylabel('Iq (A)'); title('MTPA Trajectory');
grid on

%[appendix]{"version":"1.0"}
%---
%[metadata:view]
% data: {"layout":"inline","rightPanelPercent":40}

Source Control Tips

1. Disable output saving before committing live scripts — outputs create massive base64 blobs in the appendix: MATLAB → Live Editor → Save → uncheck "Save Output"
2. Keep the appendix minimal — no stored image/output cells unless presentation-critical
3. Store .m plain text format in git (not .mlx binary) for clean diffs
4. Use %% section separators so Cell Mode in MATLAB editor still works without Live Editor

PMV Application Notes