matlab-create-live-script

Live Scripts

Plain-text .m files that render as rich documents in the MATLAB Live Editor. Version-control friendly — never use binary .mlx.

When to Use

• Tutorials, reports, analysis notebooks, or documentation
• Interactive exploration with inline figures and equations
• Version-controlled content (plain-text .m, not binary .mlx)
• Converting an existing binary .mlx file to plain-text .m

When NOT to Use

• Regular scripts without rich formatting
• Function files
• MATLAB older than R2025a

Converting from .mlx

To convert a binary .mlx file to a plain-text .m live script, run the following at the MATLAB Command Window. The recipe is not part of the resulting .m file:

editor = matlab.desktop.editor.openDocument(mlxPath, Visible=0);
editor.saveAs(newMPath);  % use .m extension
editor.closeNoPrompt;

Rules

• Text lines use %[text] — NOT bare %
• One paragraph = one %[text] line — do not hard-wrap; let the Live Editor handle line width
• No empty %[text] lines — they render as unwanted blank space
• Section headers: %% on its own line, then %[text] ## Title on next line
• No blank lines in the file, except a single blank line directly before %[appendix]
• No figure command — implicit figure creation only
• No more than one plot per section (unless using tiled layouts)
• No close all or clear
• No mfilename — does not work as intended in live scripts. Hardcode filenames or use pwd.
• Escape these characters when used as literal text (not as markdown syntax): *, _, [, ], `, \. Also escape . after a digit and # at line start.
• Equations use single-$ inline form only: $ a = \\pi r^2 $ (no $$ ... $$). For a centered/display equation, wrap the line: %[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $
• Inside an equation, LaTeX commands take double backslashes (\\sin, \\frac, \\pi) and markdown characters take single (\_, \*). Use a tool that takes literal text (Edit, Write, fwrite) — don't use Bash heredocs; they collapse \\ to \ even when quoted, which corrupts LaTeX equations.
• Last list item (bulleted or numbered) ends with \
• Every file ends with the required appendix
• Avoid fprintf — drop the semicolon or use disp(). Output appears inline below the code that produced it, not in the Command Window.
• Outputs should serve the reader's understanding, not verify execution

Required Appendix

Every live script must end with:

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

Reading live scripts (Token Optimization)

When reading a live script file, ignore everything below the %[appendix] marker. The appendix contains embedded images and metadata that consume tokens without adding useful information. All code and text content appears before it.

Format Reference

IDs (anchors, and any other id-bearing element): letters, digits, and underscores only. No hyphens — my-section won't bind; use my_section. For anchors, place the marker immediately after %[text] at the start of the line.

Tables

Example

Common Patterns

Mathematical Explanations with Equations

Code with Inline Comments

Tiled Layouts for Comparison

Use only when side-by-side comparison is important to the illustration:

Workflow

1. Plan — Title, setup, analysis sections, summary
2. Write — %[text] for text, %% for sections, appendix at end. Use a tool that takes literal text (Edit, Write, fwrite). Don't use Bash heredocs (cat > file <<EOF); they collapse \\ to \ even when quoted, which corrupts LaTeX equations.
3. Validate (if MATLAB attached) — Run the code through evaluate_matlab_code to confirm it executes cleanly. Note the wall-clock time — Embed Outputs takes about the same.
4. Embed Outputs (optional, if MATLAB attached) — Run executeLiveScript("<absolute-path>.m") to save each section's outputs (plots, displayed values) inline next to the code that produced them.
5. Verify Rendering (optional, if MATLAB attached) — Run export("<absolute-path>.m", "<absolute-path>.html") to produce an HTML approximation of the rendered document. Read it back to confirm equations are typeset, figures appear inline, %[text] directives don't leak as literal text, etc. Delete the .html when done — it's a verification artifact, not a deliverable.

The Write step is the load-bearing one — Write alone produces a valid live script the user can open and run. Validate, Embed Outputs, and Verify Rendering are progressive enhancements that require an attached MATLAB session. Without one, stop after Write. After Embed Outputs, the file is rewritten to disk by MATLAB — re-read before any further edits.

executeLiveScript

Bundled in the scripts/ folder of this skill. Add to path before first use:

Calling executeLiveScript(filePath) returns nothing on success. Runtime errors inside the script do not raise exceptions — the script writes them into the appendix as "dataType":"error" blocks; grep the saved .m to find them.

Run Validate before Embed Outputs. If a cell errors during Embed Outputs, that cell becomes an error block and outputs in cells after it are stripped from the file. Run through evaluate_matlab_code first.

If Embed Outputs errors with "Nested Live Editor execution" or hangs past the Validate time: retry once with the MATLAB desktop visible. If that also fails, the on-disk file from Write is still valid — skip Embed Outputs and let the user run the script themselves.

Checklist

Before finishing a live script, verify:

• File has .m extension
• Sections use %% alone on its own line, followed by %[text] ##
• No blank lines or empty %[text] lines (except one blank line directly before %[appendix])
• Each paragraph is a single %[text] line (no hard-wrapping)
• One plot per section (unless tiled layout)
• Bulleted and numbered lists end with backslash on last item
• LaTeX command backslashes are doubled in the saved file: \\sin, \\frac, \\pi
• No figure commands
• No close all or clear at start
• No mfilename
• Appendix is present and correctly formatted
• Outputs serve the reader, not the developer

Not Yet Supported

Minor features planned for a future revision:

• Interactive controls (sliders, dropdowns, numeric inputs)
• Hide Code View (output view that hides the source code)

Copyright 2026 The MathWorks, Inc.

----`