Links and Media

SevenMark uses double brackets for wiki links, external links, anchors, and file media.

[[target]]
[[target | display]]
[[#style="..." || target | display]]

The optional parameter prefix must end with ||. Without ||, the bracket body is parsed as the target text itself.

Parsing is target-first: after an optional parameter prefix, the parser reads the first unescaped | as the display separator and the last unescaped # in the target as the anchor separator. Escaped separators stay in the target text.

Link Targets

Wiki Pages

Plain targets are document links:

[[HomePage]]
[[API Reference | API documentation]]
[[Tutorial | Getting started guide]]

Use document: when you want to make the document namespace explicit:

[[document:Guide | Guide page]]

Anchors

Append an anchor to a document target with #, or start the target with # for an anchor in the current document.

[anchor(installation)]
## Installation

[[Guide#installation | Jump to installation]]
[[#installation | Jump within this page]]

If a literal # belongs in the title, escape it:

[[C\# Guide | C# Guide]]

If several unescaped hashes appear in the target, the last one starts the anchor:

[[Guide#install#linux | Linux install anchor]]

Category and User Pages

category: and user: are wiki namespaces:

[[category:Programming Languages | Category page]]
[[user:Alice | Alice's page]]

External URLs

Targets that start with http:// or https:// are external links. Other schemes are not rendered as external URLs.

[[https://example.com]]
[[https://rust-lang.org | Official Rust website]]
[[https://github.com/rust-lang/rust | Rust GitHub repository]]

If no display text is provided, the target itself is displayed.

File Media

Use file: targets for file media:

[[file:image.png | Alt text for image]]
[[file:screenshot.jpg | Application screenshot]]

The file title after file: is resolved by the preprocessing and postprocessing stages. Link targets and file media are separate AST nodes: links become LinkElement, and file media becomes MediaElement.

The source syntax identifies a File document; it does not contain a storage key, CDN base URL, rendition URL, or caller-selected resize operation. A server adapter resolves the current File-to-media association into a checked, public-asset responsive image contract. Published candidates carry absolute HTTPS URLs for the public R2/assets origin; the renderer does not construct these URLs from storage keys or accept relative/protocol-relative paths.

Responsive Rendering Contract

For a ready File association, the resolver supplies the renderer with:

• the media identity, immutable rendition identity, and exact association/surface versions;
• the exact published content version;
• one fallback candidate and a strictly ordered candidate set;
• the actual width, height, MIME type, byte size, and opaque variant key of every candidate;
• the intrinsic geometry used to reserve layout space.

The projection also exposes a nested safe processor metadata object containing format, source width/height, animated, pages, and EXIF-derived orientation. Restricted source metadata such as raw EXIF fields is not part of this contract.

The HTML renderer emits src, srcset, intrinsic width/height, and a caller-owned sizes profile. The profile is selected by RenderConfig and is independent of authored media parameters. It never joins a raw storage key to a file_base_url, and markup cannot provide an arbitrary sizes value. When the caller supplies RenderConfig::file_document_base_url (the V7 adapter uses /file/), the default File link appends the URL-encoded File title. Without that caller-owned base, no implicit wrapper link is emitted. Explicit checked #url, #document, #category, and #user parameters retain precedence.

The V7 document server currently selects document_content_v1 for the normal document occurrence:

(min-width: 1536px) 998px,
(min-width: 1280px) calc(100vw - 458px),
(min-width: 1024px) calc(100vw - 378px),
(min-width: 768px) calc(100vw - 48px),
calc(100vw - 24px)

This profile is audited against the document shell and is application policy, not general SevenMark grammar. Invalid presentation parameters produce diagnostics but never invalidate an otherwise valid resolved file.

NamuMark File Syntax Sugar

SevenMark accepts NamuMark file brackets as input syntax sugar and immediately maps them to the same canonical MediaElement AST:

[[파일:image.png]]
[[파일:image.png|width=120&height=80&object-fit=cover]]
[[파일:#1f1e33.jpg#|width=100]]
[[Page|[[파일:logo.png|width=25]]]]

The | section on 파일: media is interpreted as NamuMark-style image parameters separated by &. Valid key=value entries become canonical SevenMark media parameters. Unitless width and height values are normalized to pixels, and the NamuMark object-fit spelling becomes canonical fit. A file title that starts with # may use NamuMark's trailing # disambiguation form; the trailing marker is removed from the stored file title.

width=120&height=80&object-fit=cover
→ #width="120px" #height="80px" #fit="cover"

Linked Files

To make file media clickable, keep the file: target as the media source and add a link parameter in the prefix:

[[#url="https://example.com" || file:logo.png | Logo]]
[[#document="Guide" || file:guide-cover.png | Guide cover]]
[[#category="Rust" || file:rust-logo.png | Rust category]]
[[#user="Alice" || file:avatar.png | Alice]]

Media link parameters are resolved in this priority order:

#url > #document > #category > #user

Add #anchor to append a fragment to the selected media link:

[[#document="Guide" #anchor="installation" || file:guide-cover.png | Installation]]

These parameters are media wrapper links. On a normal link element such as [[#url="https://a.example" || Guide | Label]], the target remains Guide; the #url parameter does not override the link target.

Theme-aware Files

File media can use #theme="light" or #theme="dark" in the parameter prefix. The renderer exposes valid theme values as data-theme="light" or data-theme="dark" on the media wrapper; other values are ignored.

[[#theme="light" || file:logo-light.svg | Light logo]]
[[#theme="dark" || file:logo-dark.svg | Dark logo]]

This is useful when the frontend chooses which file to show in light and dark color schemes.

Parameters

Parameters can be applied before the target by ending the parameter prefix with ||.

[[#style="float:right; width:180px" || file:sample.png | Example]]
[[#class="external-doc" || https://example.com/docs | Docs]]
[[#theme="dark" || file:logo-dark.svg | Dark logo]]

Common renderer parameters include #style, #class, and #dark-*. For file: media, #theme="light" and #theme="dark" provide a dedicated theme hint.

File media is one target in the shared parameter specification:

Parameter	Meaning
#width	Display width; unitless numbers are pixels
#height	Display height; unitless numbers are pixels
#fit	contain, cover, fill, none, or scale-down
#align	left, center, or right
#style, #dark-style	Sanitized wrapper declarations
#class	Additional wrapper classes
#theme	light or dark visibility
#url, #document, #category, #user, #anchor	Optional wrapper link

Unknown, unsupported, non-canonical, or invalid parameters are reported as structured render and LSP diagnostics. A resolved image remains rendered with the caller-owned responsive profile.

If the prefix does not contain ||, it is not a parameter prefix:

[[#style="color:red" Guide | The target includes the #style text]]

Backslash escapes the next character inside bracket syntax, so \|, \#, and \] can be used when those characters should be literal target or display text.

Link targets are not parsed recursively inside link or media display text. Media targets are allowed in link display content so Namumark linked-image syntax can map to existing link and media AST nodes without creating a dedicated compatibility AST.

Media and Links in Complex Structures

In Tables

{{{#table
[[#head [[Name]] [[Image]] [[Link]]]]
[[[[John]] [[[file:john.jpg | John's photo]]] [[[https://john.com | Profile]]]]]
}}}

In Lists

{{{#list #type="numeric"
[[Profile images:]]
[[[[file:avatar1.png | User 1]]]]
[[[[file:avatar2.png | User 2]]]]
[[Documentation: [[https://docs.example.com | Official docs]]]]
}}}

External Media Embeds

Provider embeds still use provider parameters such as [[#youtube #id="..."]]. For YouTube, Spotify, Discord, and related embeds, see External Media Embeds.