Reference files & media

moss references anything with wikilinks: write a filename, title, or media name inside [[double brackets]]. moss searches your whole folder for the filename, so you never have to write out a path.

Links match by filename, title, and URL. Common variants:

SyntaxWhat it does
[[filename|link text]]Custom display text (what follows the pipe is what readers see)
[[filename#Section heading]]Link to a heading
[[filename#^intro]]Link to a paragraph (block reference)

Add ^intro at the end of a paragraph to give it a stable block ID, then reference it elsewhere with [[page#^intro]].

Embeds

Add ! before the brackets to inline the target's content into the current page, instead of just linking to it:

SyntaxWhat it embeds
![[filename]]The whole file
![[filename#Section name]]One section of a file
![[filename#^intro]]One paragraph of a file
`<!--MOSS_MARKER_FOLDER_LIST:path=folder/from=Get Started/Reference files & media.md-->`

A path ending in / means a folder. Folder embeds take parameters — for example, <!--MOSS_MARKER_FOLDER_LIST:path=albums/|from=Get Started/Reference files & media.md|limit=5--> shows only the latest 5 items and appends a "More →" link.

Media

Drop images, videos, and other files into your folder, then reference them with a wikilink or standard markdown. moss resolves the filenames and optimizes the media files automatically.

![[sunset.jpg]]
![Sunset over the coast](photos/sunset.jpg)
![[sunset.jpg|Sunset over the coast]]

In the last two forms, "Sunset over the coast" becomes the caption below the image, and also serves screen readers and search engines.

An embed needs an empty line above it to become a figure. An embed that hugs the previous paragraph is treated as an inline image, and its caption and sizing parameters are ignored.

Supported media types:

Put media in an excluded asset folder (assets/, images/, static/, public/) and it's served publicly but never becomes a page.

Control the display

Append parameters after a pipe to control an image's size, fit, and position:

![[cover.jpg|400]]           # 400px wide
![[cover.jpg|100%]]          # 100% wide
![[cover.jpg|200x150]]       # width × height
![[headshot.jpg|cover top]]  # fit + position

Size: write a width or width × height. Units: px (default), %, vh — e.g. 400, 100%, 200x150.

Fit (maps to CSS object-fit): cover (default — fill and crop), contain (show the whole image), fill, none, scale-down. Position: center, top, left, bottom-right, and so on.

Each pipe carries one meaning — size, fit and position, or a caption — never mixed in the same pipe.

Go deeper

For the finer points — resolution priority, circular-embed handling, cover images, children_source — see Links & Embeds and Media.

Published with moss