# Markdown Markdown is a widely-supported plain-text format that reads cleanly in any editor and renders consistently across tools. Wikilayer stores every node body as markdown, parses it with goldmark + GFM, and adds a few project-specific extensions for cross-linking and embedded callouts. ## CommonMark and GFM Everything in [CommonMark](https://commonmark.org/) plus [GitHub-Flavored Markdown](https://github.github.com/gfm/), with one exception: a heading line in a body is refused, because [a heading is a node's place](block:39329) and the renderer writes it from the node's title. So bodies carry: - Bold (`**text**`), italic (`*text*`), strikethrough (`~~text~~`). - Inline code (`` `text` ``) and fenced code blocks with an optional language tag. - Unordered lists (`-`, `*`, `+`), ordered lists (`1.`), nested lists by indentation. - Blockquotes (`> `). - Tables (GFM pipe syntax). - Task lists (`- [x]`, `- [ ]`). - Horizontal rules (`---`). - Links (`[text](url)`) and images (``). ## Wikilayer extensions A few forms get rewritten during render. ### Short refs A short ref is a link written against a node's id, which the renderer rewrites into the wiki's own URL. It survives a title or slug change because the id does not move. #### Page short refs `[text](page:N)` resolves to the target page's canonical URL: `/{owner}/{wiki}/{id}-{slug}`, or `/{owner}/{wiki}/{lang}/{id}-{slug}` for a page in a non-primary language. Slugs may rotate on rename; the id is stable. #### Block short refs `[text](block:N)` resolves to the anchor `#block-N`: on the block's own page it is an in-page link, from any other page it is the block's page URL plus that anchor. ### Admonitions Visual callouts written as `> [!KIND]` blockquotes, in the GitHub admonition syntax. #### Callouts GitHub-flavored admonitions render as styled boxes. The first line of the blockquote names the kind: ``` > [!NOTE] > Body text. ``` Supported kinds: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`. Each gets its own colour and icon. #### Map embeds A `[!MAP]` admonition with `lat, lng` on the next line embeds an interactive map widget. A third line, if present, becomes the caption. ``` > [!MAP] > 44.7866, 20.4489 > Belgrade, the city centre. ``` ### Image embeds A picture is stored on the server and embedded by its `/s/` path. Two [MCP](page:4409) tools store one: - `upload_image` takes a public `http` or `https` address, or a file attached in the conversation, and the server fetches it itself, so its bytes need not pass through the agent's context. It suits an agent in a browser chat, which has no shell. - `request_upload` issues a single-use address that an agent with a shell posts a local file to: `curl --data-binary @ -H 'Content-Type: ' ''`. Either way the picture is converted to JPEG with its longest side at most 1600 px and stored under the wiki; `upload_image` answers with its path, and with `request_upload` the POST does. The path goes into the body exactly as given, written inline: ``. #### Beside the text, with a caption A picture alone in its paragraph spans the text. Given a title, it stands beside the text on the right, the way an encyclopedia shows a thumbnail: the title becomes its caption, the text wraps on its left, and a click opens the picture whole. ```  ``` The alt text describes the picture for a reader who cannot see it; the caption says what to take from it. A tall picture, or one that illustrates rather than explains, reads better beside the text; a screenshot or a diagram whose detail matters keeps the full width. On a phone-width screen the picture spans the screen, and the mobile apps show every picture full width. #### No external hosts A picture is embedded only from the wiki's own store, by its `/s/` path. A write naming a picture on GitHub, Imgur or another host, a `data:` URI or a full URL is refused, and a picture from elsewhere already in a body shows as a link. External pictures rot, get rate-limited, and tell their host who read the page. #### Without object storage there is no workaround If neither `upload_image` nor `request_upload` appears in the tool list, object storage isn't configured on this deploy and image embedding isn't available; an external host is no substitute. --- ## Links here - [History](page:3089) - [MCP](page:4409) --- [All pages](https://wikilayer.org/smee-again/wikilayer-howto/en/index.md)