# Notion Write Math Encoding Guard

> Prevent mojibake and formula corruption when creating or updating Notion pages that contain Markdown, LaTeX formulas, vectors/matrices, and mixed Chinese-English text. Use when Notion content includes non-ASCII symbols, math delimiters, previously corrupted escapes, or unstable Notion formula rendering.

- Skill: `rainy-w-cy/notion-write-math-encoding-guard` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add rainy-w-cy/notion-write-math-encoding-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rainy-w-cy/notion-write-math-encoding-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Rainy-W-cy (https://skillmd.com/u/rainy-w-cy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rainy-w-cy/notion-write-math-encoding-guard

---


# Notion Write Math Encoding Guard

## Overview

Use this skill when Notion page content must stay readable after upload, especially for formula-heavy technical notes.
The goal is not only to prevent mojibake, but also to keep formula presentation stable in Notion preview, fetch output, and later edits.

## Workflow

1. Determine language, math density, and whether the user wants full rewrite or local edits.
2. Determine content ownership before drafting:
   - user-provided text that must be preserved
   - assistant-authored explanation that may be reformatted
3. Classify formulas before drafting:
   - plain-text-safe
   - inline-math-needed
   - block-math-needed
4. Build content in Notion-friendly Markdown with LaTeX-safe formulas and preview-stable layout.
5. For existing pages, fetch first and decide `replace_content` vs `update_content`.
6. Write to Notion.
7. Fetch again and validate encoding, delimiters, wording fidelity, and rendering stability.

## Authoring Rules

- If the user gives text to write into Notion, preserve the user's wording and intent by default.
- Do not autonomously rewrite, polish, summarize, or strengthen the user's wording unless the user explicitly asks for that.
- You may only normalize formatting, formula delimiters, headings, spacing, list structure, and obvious encoding issues when writing the user's content into Notion.
- When user wording and Notion preview stability conflict, keep the wording and change only the presentation layer.
- Prefer block formulas (`$$...$$`) for complex expressions.
- Use inline formulas (`$...$`) only for short symbols that truly need math rendering.
- Prefer LaTeX commands over decorative Unicode math glyphs.
- Use canonical forms: `\\vec{x}`, `\\mathbf{x}`, `\\begin{bmatrix}...\\end{bmatrix}`.
- Keep punctuation in formulas ASCII-only.
- Keep mixed-language prose outside formula delimiters where possible.
- Prefer plain text for simple function names and short variables in prose.
- Do not wrap every symbol in inline math by default.
- Avoid mixing backticks and math delimiters around the same token.
- For long-term notes, prefer "few block formulas + mostly plain text" over dense inline math.

## Preview-Stable Notion Layout Rules

- Write for Notion page preview first, not for raw Markdown aesthetics.
- Avoid layouts that commonly render badly in Notion preview:
  - dense inline formulas inside long Chinese sentences
  - mixed backticks and math delimiters on the same token
  - deeply nested lists containing formulas
  - long multi-clause paragraphs that alternate prose and symbols repeatedly
- Prefer short paragraphs, flat lists, and separated block formulas.
- Keep headings concise and aligned with the user's original structure.
- If the user provides an existing section order, preserve that order unless the user explicitly requests restructuring.
- Do not add explanatory sections, transition sentences, or editorial comments unless the user asked for them.
- If a table is likely to misalign or degrade in Notion preview, rewrite it into a flat bullet list only if this does not change the user-requested content structure.
- When formatting user-provided content, optimize spacing and alignment only to improve Notion readability, never to change meaning.

## Formula Style Guide

### Use plain text when:

- Mentioning a function name in prose
- Describing thresholds or parameter ranges
- Referring to simple scalars or settings
- Explaining hardware control flow, FSM names, or module names

Examples:

- `Softmax`
- `LayerNorm`
- `exp(x)`
- `sqrt(a)`
- `h <= 4`
- `N >= 3`
- `a in [0, 2]`

### Use inline math when:

- A short symbol would be ambiguous in plain text
- A sentence needs one compact mathematical token

Examples:

- `$x_i$`
- `$\\mu$`
- `$\\sigma^2$`

### Use block math when:

- The expression contains fractions, roots, summations, matrices, or updates
- The formula is central to the explanation
- The same formula may be referenced later

Examples:

$$
\\mathrm{Softmax}(x_i) = \\frac{e^{x_i}}{\\sum_{j=1}^{N} e^{x_j}}
$$

$$
x_{n+1} = \\frac{1}{2}\\left(x_n + \\frac{a}{x_n}\\right)
$$

## Notion Write Rules

- For new pages, create with title in properties and body in content.
- For existing pages, always fetch before editing.
- Prefer full `replace_content` when corruption is widespread.
- Prefer `update_content` for small, exact-match edits.
- Avoid blind global replacements on formula-heavy content.
- When a page has repeated formula corruption, prefer rebuilding the affected section from clean source text rather than patching escaped fragments in place.
- If both encoding cleanup and formula-style cleanup are needed, prefer one controlled full rewrite over many small edits.
- If the user asks to "write this content into Notion", treat the provided content as source-of-truth text.
- In that case, editing scope is limited to:
  - encoding repair
  - math delimiter stabilization
  - line break and heading normalization
  - preview-safe list and paragraph formatting
- In that case, do not:
  - rewrite the tone
  - add missing analysis on your own
  - compress or expand the substance
  - silently convert the content into a different style

## Wording Fidelity Rules

- Preserve terminology exactly when it appears intentional, including mixed Chinese-English technical phrases.
- Preserve emphasis markers, section names, and user-specified ordering unless they directly cause rendering failure.
- If a phrase is awkward but readable, keep it.
- If a phrase is unreadable because of corruption, reconstruct the smallest necessary fragment only.
- When you must repair a corrupted expression, keep the nearest recoverable wording rather than producing a cleaner paraphrase.

## Validation Checklist

After writing to Notion, verify all checks:

- Page fetch returns readable text in the requested language.
- User-provided wording has not been unintentionally rewritten.
- No mojibake markers such as `???`, replacement bursts, or obviously garbled character runs.
- Formula delimiters remain balanced.
- Backslashes in LaTeX commands are preserved.
- Critical formulas and vector/matrix snippets render in Notion UI.
- Plain-text function names do not appear wrapped in accidental math delimiters.
- API fetch noise is distinguished from true corruption:
  - escaped backslashes alone do not prove the page is broken
  - repeated `$`\...`$`-style fragments or mixed backticks/math usually indicate unstable authoring
- If API text shows escaped backslashes, verify UI rendering before concluding corruption.
- Headings, bullets, spacing, and formula blocks remain visually aligned in Notion preview.

## Failure Handling

If validation fails:

1. Rebuild the affected section from clean source text.
2. Reduce inline formulas; convert complex inline math to block formulas.
3. Convert non-essential inline math to plain text function or variable notation.
4. Revert any unnecessary wording changes and keep only formatting repairs.
5. Re-apply update with exact snippet boundaries.
6. Fetch again and re-check delimiters, backslashes, wording fidelity, and UI rendering.

## Decision Heuristics

- If the page is mostly readable but a few formulas are ugly, use `update_content`.
- If formulas are broadly inconsistent, mixed with escaped fragments, or preview is unstable, use `replace_content`.
- If the user wants a long-term notes page, optimize for stability, not for maximal LaTeX density.
- If a formula-heavy page keeps regressing after edits, simplify the notation style rather than adding more escapes.
- If the user provides final text for direct write-in, prefer preserving wording over stylistic optimization.
- If preview stability can be fixed by layout changes alone, do not touch the wording.

## Quick Snippets

See `references/math-and-vector-snippets.md` for safe equation, vector, and matrix templates.