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. You don't need to specify the full path — [[getting-started]] finds docs/start/getting-started.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. <!-- moss-embed:footer.md --> 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 embeds#

Embed images with ! before the brackets:

![[photo.jpg]]
![[poster-farewell.webp]]

moss resolves the filename by searching the entire content tree — you don't need a relative path. Put images in an excluded asset folder (assets/, images/, static/, public/) so they are served but not treated as content pages, then reference them by bare filename from any markdown file.

work/
├── index.md         ← uses ![[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.

Pipe syntax controls display: ![[photo.jpg|contain top]]. See media for the full option set.

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: <!-- moss-embed:docs/media.md --> — embeds the entire page content
• Section: <!-- moss-embed:docs/structure.md#URLs --> — embeds everything under that heading
• Block: <!-- moss-embed:docs/structure.md#^intro --> — embeds a single paragraph marked with a block ID
• Folder listing: <!--MOSS_MARKER_FOLDER_LIST:path=journal/|from=docs/author/wikilinks-and-embeds.md--> — embeds another folder's children as cards (see below)

moss detects circular embeds and stops before creating an infinite loop.

Folder listings#

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

# William Blake's Notebooks

A personal record of my reading and writing.

## Recent journal

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

## Books

The trailing slash is the signal that this is a folder, 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 here, 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 most pages with a single primary listing, frontmatter children_source is the right choice. Use <!--MOSS_MARKER_FOLDER_LIST:path=folder/|from=docs/author/wikilinks-and-embeds.md--> 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 specific 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/start/structure/)

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

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.