Media
Put images, videos, and other files anywhere in your project folder. Reference them from markdown; moss handles path resolution, optimization, and progressive loading.
Images
Reference an image with standard markdown syntax:

Or with a wikilink:
![[sunset.jpg]]
moss resolves the path automatically. It also extracts image dimensions and generates a tiny blurred placeholder so the page doesn't jump as images load.
Supported formats: .jpg, .jpeg, .png, .gif, .svg, .webp, .avif.
Video
Drop video files in your folder and reference them the same way:

The wikilink ![[demo.mov]] does the same by name.
moss transcodes .mov files to .mp4 (H.264 + AAC) in the background. The preview opens immediately and video loads progressively as transcoding completes. Reference the original .mov filename; moss serves the converted .mp4 automatically.
The standard form also embeds audio (), PDF, HTML and 3D model files that are in your site, each giving the same player as its wikilink, and a YouTube, Vimeo or CodePen address () gives the same player as ![[https://www.youtube.com/watch?v=…]]. A size in the alt text works as it does after the pipe ( matches ![[demo.mov|400]]), and plain alt text becomes the player's accessible label, as the text after the pipe does for ![[demo.mov|a label]].
A video takes a caption when a width is written before it: ![[demo.mp4|100%|Caption]] shows the player with the caption beneath. Add loop as its own | segment to make it a silent looping clip that keeps the caption: ![[demo.mp4|loop|100%|Caption]]. Inside the caption text the word is just a word, so ![[demo.mp4|100%|A loop of rope]] stays as written.
Display control
Control how media displays with pipe syntax — append a fit/position keyword, a size, or a caption after a |:
![[photo.jpg|contain top-left]]
Fit values (maps to CSS object-fit):
| Value | Effect |
|---|---|
cover | Fill the area, cropping if needed (default) |
contain | Show the whole image, letterboxing if needed |
fill | Stretch to fill exactly |
none | Natural size, no scaling |
scale-down | Like contain, but never enlarges |
Position values (maps to CSS object-position):
center, left, right, top, bottom, top-left, top-right, bottom-left, bottom-right
Combine them: ![[panorama.jpg|contain center]], ![[headshot.jpg|cover top]].
For a point the nine names do not reach, write a focus point focus:X%,Y%, whole percentages from 0 to 100 measured from the top-left, e.g. ![[photo.jpg|focus:20%,62%]]; the crop lines that point of the picture up with the same point of the frame, so focus:50%,50% is center and focus:0%,0% is top-left.
Size — a width, or width × height, in place of fit/position:
| Pipe | Result |
|---|---|
![[photo.jpg|400]] | 400px wide |
![[photo.jpg|100%]] | full container width |
![[photo.jpg|200x150]] | 200 × 150px |
A bare number is pixels; px, %, and vh are also accepted. One value sets width; WxH sets both.
A pipe segment carries one meaning — moss reads it as size, then fit/position, then caption text — so size and fit can't share a single pipe.
This syntax works in wikilinks, markdown images, and bare filenames inside shortcodes.
Captions
An image in its own paragraph — an empty line above it, nothing else on the line — with non-empty alt text renders as a semantic <figure> with a visible <figcaption>:

<figure>
<img src="…/light.jpg" alt="">
<figcaption>Morning light, Yangshuo</figcaption>
</figure>
This is Pandoc's implicit-figure convention, on by default; the default theme sets captions italic and centered.
Three ways to write one:
| Syntax | Caption | Alt text |
|---|---|---|
 | the alt text | none: the caption names the image |
![[photo.jpg|Caption]] | the alias | none: the caption names the image |
 then *Caption* on the next line | the italic line | the bracket text, a separate description |
In the first two, the image is announced once, through its caption, so the <img> carries alt="": a screen reader would otherwise read the same words twice. The third form is for when the caption is a credit line or a title and the image needs a real description. Write the description in the brackets and put the caption on an italic line of its own directly under the image; the line must start on a new line, so  *beta* on one line stays a paragraph with an image in it.
An image title () is the title attribute of the <img>, the browser tooltip, and does not change the caption.
An image with no text at all ( or ![[photo.jpg]]) gets alt="", which marks it decorative, and the build logs Accessibility: image '…' on '…' has no alt text. That line is advice: it does not count as a problem for --strict. A picture inside a link that has its own words ([ Opening hours](hours/)) gets no such line, since the link's words name it; a picture that is a link's only content still does. There is no separate marker for a deliberately decorative image yet, so the line is the cost of leaving one bare.
For the wikilink form, the alias becomes a caption only when it isn't a size or fit/position keyword — those are read first.
No figure is emitted when the alt is empty (![[photo.jpg]] or ) — moss keeps a plain <img> rather than caption an undescribed image — or when the image shares its line with other text (a trailing *italic* caption is the one exception, above).
For richer caption markup, hand-write a <figure>; raw HTML passes through untouched. Turn the behavior off site-wide with implicit_figure = false under [site] in .moss/config.toml.
Notebooks
Jupyter notebooks (.ipynb files) run directly in the browser via JupyterLite — no server, no Python installation required. The entire runtime (~20 MB) runs as WebAssembly in the visitor's browser. Place a .ipynb file in your project and it appears alongside your other content.
HTML files
Plain .html files in your project are served as-is. Use them for interactive content, embeds, or pages that need full control over their markup.
Cover images
Any page can declare a cover image in its frontmatter:
---
title: My Project
cover: screenshots/hero.png
---
Covers appear in card layouts when a section uses children_style: card. moss detects the media type from the file extension. Override with cover_type for non-image covers:
---
cover: demo.mp4
cover_type: video
---
Valid cover types: image (default), video, iframe.