`. Never put bare text directly inside it.
```html
A quotation or emphasized takeaway.
```
Invalid:
```html
Bare text is not allowed here.
```
### Code blocks
Escape code as HTML text. Add a supported language hint when known; omit the class when unknown.
```html
.card {
display: grid;
}
```
Inline code uses `display: grid` outside ``.
## Code block best practices
- Put only source-confirmed code, code comments, or intentionally demonstrated terminal/data syntax inside ``. Explanatory prose belongs in paragraphs outside the code block.
- Never classify an entire mixed plaintext section as code because nearby lines contain syntax or because a percentage of its lines look code-like. When source block boundaries are unavailable, segment the material line by line and wrap only contiguous, confidently identified code lines.
- Preserve the source order by alternating paragraphs and code blocks when an explanation introduces or follows an example. Do not merge the explanation into the example.
- When classification is uncertain, fail closed: render the text as a paragraph and use inline `` for identifiers or short expressions instead of creating a code block.
- Before saving, inspect every generated code block for natural-language sentences that are not source-authored code comments. Split any mixed block rather than converting prose into comments.
- For conversions from unstructured or flattened text, compare every generated code-block boundary with the source before writing. After writing, verify the semantic separation of prose and code in returned `body.html`, not merely that `` tags survived sanitization.
### Tables
Use semantic rows and cells. Include a header row when the first row labels columns.
```html
Property | Purpose |
|---|
display | Selects the layout model |
```
## Images
Upload the image first and use the returned renderable media URL, not a local path, signed upload URL, storage key, or numeric upload id.
```html
```
Provide meaningful alt text based on what the image contributes to the lesson. Do not persist editor-only attributes such as `data-upload-id`, `data-uploading`, or `data-upload-error`.
## Videos
Allow at most one video block in the entire lesson. Place it at or near the beginning when video is the primary material. Persist only a ready video block.
### YouTube
Use the normalized user-supplied YouTube URL as the source. Do not create an iframe.
```html
```
The editor also supports Vimeo and Twitch with the same structure and the matching `data-video-provider`, but never add an external video unless the user supplied it or explicitly asked for one to be found.
### Uploaded video
Complete the upload and processing flow first. Use the final media URL from the completed upload as `data-video-src`.
```html
```
Do not persist a pending block, an upload id, or a signed storage URL.
## Links
Normalize links to absolute HTTP(S) URLs.
### Raw text link
Use descriptive text when possible:
```html
Read the complete guide.
```
### Rich card
Validate the URL through the URL extraction endpoint first. Require a meaningful title plus useful image/description metadata appropriate to a large preview.
```html
```
### Inline rich card
Validate the URL through URL extraction first. Require a meaningful title; favicon is preferred and the extracted image can serve as fallback.
```html
Continue with .
```
The renderer fetches current metadata at display time. Do not embed scraped title, description, image, or favicon inside the anchor. Extraction validates that the renderer is likely to produce a useful preview; it does not endorse the destination or prove it is safe.
## Validation
Before sending lesson HTML:
- Count custom video blocks and stop if there is more than one.
- Confirm every blockquote has paragraph children and no bare text.
- Confirm every uploaded image/video uses its final media URL.
- Confirm every card/inline URL passed metadata extraction.
- Confirm raw links have safe absolute HTTP(S) hrefs and useful visible text.
- Confirm code text is escaped and tables are structurally complete.
- Confirm every code block contains code rather than adjacent explanatory prose, and that uncertain text was left as a paragraph with inline code where appropriate.
After the write, inspect returned `body.html` and ensure the API retained the intended tags, semantic prose/code boundaries, video data attributes, image sources, and rich-link attributes.