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:

```matlab
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:

```matlab
%[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

| Syntax | Renders as |
|--------|-----------|
| `%%` | Section break |
| `%[text] # Title` | H1 heading |
| `%[text] ## Section` | H2 heading |
| `%[text] **bold**` | **Bold** |
| `%[text] *italic*` | *Italic* |
| `` %[text] `code` `` | `Monospace` |
| `%[text] <u>text</u>` | Underlined text |
| `%[text] $ a = \\pi r^2 $` | Inline equation |
| `%[text]{"align":"center"} $ ... $` | Centered/display equation |
| `%[text] - item` | Bullet |
| `%[text] - last \` | Last bullet |
| `%[text] 1. item` | Numbered list |
| `%[text] 2. last \` | Last numbered item |
| `%[text] [text](url)` | External hyperlink |
| `%[text] [text](internal:id)` | Internal link to an anchor |
| `%[text] %[text:anchor:id] ...` | Anchor (link target) |
| `%[text:tableOfContents]{"heading":"..."}` | Table of Contents |

**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

```matlab
%[text:table]
%[text] | Method | Result |
%[text] | --- | --- |
%[text] | Trapezoidal | 1.9998 |
%[text:table]
```

## Example

```matlab
%[text] # Sinusoidal Signals
%[text] Examples of sinusoidal signals in MATLAB.
%[text:tableOfContents]{"heading":"Contents"}
%[text] - sine waves
%[text] - cosine waves \
x = linspace(0,8*pi);
%%
%[text] ## Sine Wave
plot(x,sin(x))
title('Sine Wave')
xlabel('x (radians)')
ylabel('sin(x)')
grid on
%%
%[text] ## Cosine Wave
plot(x,cos(x))
title('Cosine Wave')
xlabel('x (radians)')
ylabel('cos(x)')
grid on
%%
%[text] ## Summary
%[text] The sine and cosine functions are $ \\pi/2 $ radians out of phase.

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

## Common Patterns

### Mathematical Explanations with Equations

```matlab
%[text] ## Theory
%[text] The discrete Fourier transform is defined as:
%[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $
%[text] where $ x(n) $ are the time-domain samples and $ k $ indexes the frequency bins.
```

### Code with Inline Comments

```matlab
%%
%[text] ## Data Processing
%[text] Load and filter the data, then visualize the results.
data = load('measurements.mat');
filtered = lowpass(data, 0.5);  % Apply lowpass filter
plot(filtered)
title('Filtered Data')
```

### Tiled Layouts for Comparison

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

```matlab
%%
%[text] ## Comparison of Methods
tiledlayout(1,2)
nexttile
plot(method1)
title('Method 1')
nexttile
plot(method2)
title('Method 2')
```

## 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 clea