Links & Embeds

Wikilinks

Link to any page in your site using double brackets:

Read the [[structure]] page for details.

moss resolves the link by matching the text against filenames, titles, and slugs. No full path needed. [[from-matters]] finds docs/start/from-matters.md automatically.

Display text:

See the [[structure|content structure docs]] for more.

Link to a heading:

Check [[structure#Stems]] for the definition.

Link to a block reference:

As defined in [[structure#^intro]].

Resolution rules

When multiple files could match, moss picks the best one:

1. Exact filename match
2. Filename without extension
3. Folder note (self-named file)
4. Same language tree as the source page (e.g. ![[footer]] from zh-hans/about.md prefers zh-hans/footer.md over root footer.md)
5. Closest directory first (files nearer to the linking page win remaining ties)

Explicit paths like [[zh-hans/footer]] always win over the language-tree preference.

Image and media embeds

Embed an image with standard Markdown, or with a wikilink by putting ! before the brackets. Both render the same:

![](photos/photo.jpg)
![[photo.jpg]]

The standard form is the default: write the path relative to the page, and spell a space as %20 (![](my%20photo.jpg)). If nothing is at that path, moss tries the same path from the site root, then falls back to the nearest file with that name, so a path that has gone stale still finds its file. The wikilink needs only the file name and searches the entire content tree, so no path is needed at all. The same two spellings work for video, audio, PDF and 3D model files (![](clip.mp4) or ![[clip.mp4]]).

Put images in an excluded asset folder (assets/, images/, static/, public/) so they are served but not treated as content pages, then reference them from any markdown file.

work/
├── index.md         ← uses ![](assets/poster-farewell.webp)
└── assets/
    └── poster-farewell.webp   ← not a page; served as a static file

The language-tree preference (rule 4 above) applies to image resolution too: ![[photo.jpg]] inside zh-hans/about.md prefers zh-hans/photo.jpg if it exists.

Some embeds exist only as wikilinks: page, section, table, notebook and folder transclusions (![[name]], see below), the provider players for ![[https://…]] URLs, and the style: keys. In the standard form the text in the brackets is a caption on an image, and on video or audio it plays the role of the text after the pipe: ![640x360 loop](clip.mp4) is ![[clip.mp4|640x360 loop]].

Pipe syntax controls display — a fit/position keyword (![[photo.jpg|contain top]]), a size (![[photo.jpg|400]]), or a caption (![[photo.jpg|Morning light]]). See media#Display control and media#Captions for the full rules.

Embeds

Pull content from another page inline using ! before the brackets:

![[structure#^intro]]

This inserts the referenced paragraph directly into the current page. Embeds work with:

• Full page: ![[media]]: embeds the entire page content
• Section: ![[structure#URLs]]: embeds everything under that heading
• Block: ![[structure#^intro]]: embeds a single paragraph marked with a block ID
• Folder listing: ![[journal/]]: embeds another folder's children as cards (see below)

moss detects circular embeds and stops before an infinite loop.

HTML and interactive embeds

Embed an interactive or animated .html file (an animation, a small demo, a widget) with the same ![[...]] syntax (a standard ![](folder-to-site.html) that points at an HTML file in your site embeds it the same way):

![[folder-to-site.html]]

moss serves the file as-is inside an iframe, so its own CSS and animation run normally. Keep the file in an excluded asset folder (assets/, static/) and reference it by bare filename. moss resolves the path and keeps the URL correct wherever the page is deployed. A query string passes straight through: ![[chart.html?series=a,b]].

This is the preferred way to embed interactive content. Do not hand-write a raw <iframe> or an absolute /assets/... URL. The wikilink computes the right relative path. The same ![[folder-to-site.html]] resolves to a per-language copy via the language-tree rule: put the default file at assets/animations/folder-to-site.html and a translation at zh-hant/assets/animations/folder-to-site.html, and each page picks its own.

The embed fills the page width in a 16:9 frame, so design the file to read well at that shape.

Maps

Place a map in the body with style:map. The embed stays where you write it, with the same width, alignment, and caption controls as other media:

![[#|style:map|align-right 50%|Places in this article]]
![[Travel diary|style:map|wide]]
![[/places/kyoto/|style:map|align-left 40%|Kyoto]]

# selects the current document. A named document selects that document's location: values; neither form transcludes its body. A place target ending in / keeps the existing place-map behavior. Article maps use all coordinate-bearing locations from the target's frontmatter, with the same precision and route: rules as its own map. A heading or block fragment does not select separate location data.

An explicit map of the current document replaces its automatic locator. The map: frontmatter switch and [site].locator setting still control automatic maps; they do not hide embeds you place in the body. If the target cannot be resolved or has no coordinate-bearing locations, moss reports an unavailable map instead of embedding the article text.

Folder listings

A wikilink whose path ends with / embeds a folder's children inline:

# A Reader's Notebooks

A personal record of my reading and writing.

## Recent journal

![[journal/|limit:5,more]]

## Books

The trailing slash signals a folder embed, not a page. The cards inherit the target folder's sort (see frontmatter#Sort), so a journal/ folder with dated entries renders date-sorted cards, and a projects/ folder of dateless entries renders alphabetically.

Pipe parameters (comma-separated):

Examples:

![[journal/]]                       # full listing
![[journal/|limit:5]]               # 5 most recent (or whatever the journal's sort picks)
![[journal/|limit:5,more]]          # 5 newest + "More →" link
![[news/|sort:date,limit:3]]        # override sort axis per-embed

Paths follow the same resolution as other wikilinks: relative paths anchor at the current page's folder, absolute paths (/journal/) anchor at the site root.

When to use folder listings vs children_source

Two ways to render another folder's children on a page:

For a page with a single primary listing, children_source is the right choice. Use ![[folder/]] when you want the listing inline among other content.

Block references

Mark any paragraph with a ^block-id at the end of the line:

moss turns a folder of markdown files into a website. ^intro

Other pages can then link to or embed this paragraph using [[page#^intro]] or ![[page#^intro]]. Block IDs are stable — they don't change when you reword the paragraph or rename the heading above it.

Markdown links

Standard markdown links work as you'd expect:

[Visit Example](https://example.com)
[About page](about.md)
[Section link](/docs/writing/structure/)

Both relative and absolute paths work. External links open in a new tab.

Bilingual content

Create translations by appending a language suffix to the filename:

When translations exist, a language toggle appears on the page automatically.

Language detection

moss resolves a page's language in this order:

1. lang frontmatter field
2. Filename suffix (.zh-hans.md)
3. Content auto-detection
4. Site default language

Linking translations with different names

When translations have different filenames, use translationKey to connect them:

# posts/hello.md
---
translationKey: hello-post
---

# posts/ni-hao.md
---
translationKey: hello-post
lang: zh-hans
---

Both files show a language toggle linking to each other.