How-to
Website
Web app
Slides
Custom elements
Desktop / phone
Render Markdown
Markdown(text) shows Markdown text on a page: release notes, a post's body, a field a user wrote. It renders a small, predictable Markdown, the same at build time and in the browser, so a hydrated page repaints exactly what was painted. This page shows release notes held in a state, and one line of inline Markdown:
Needs: a picture img.png in public/, which the last line shows. It claims /: paste it into a new project, or replace the starter's src/pages/Home.wf with it.
page Notes(path: "/", title: "Release notes", description: "What changed in this release.") {
state body = "## Version 3.3\n\nThis release adds:\n\n- Markdown pages\n- `wf docs`\n\n> Ship it."
Heading("Release notes").h1
Markdown(body)
Markdown("Inline *emphasis*, a [link](/about) and an .")
}
How it works
The page shows a "Release notes" heading, then the body: a "Version 3.3" heading, a paragraph, a two-item list and a quote, then a line with emphasis, a link and a picture.
The page's h1 is a Heading of its own. A # heading inside Markdown is drawn as an h1 too, but the build cannot see into text that may change, so a page whose only h1 comes from Markdown draws an A12 warning.
What Markdown supports:
| Kind | Syntax |
|---|---|
| Blocks |
|
| Inline |
` |
A paragraph's lines run together, as in CommonMark. To break a line, end it with two spaces or a \.
Raw HTML in the text is shown as text, not run, so Markdown from a user or an API is safe to render. A link or a picture goes through the scheme check every other URL does (Security):
- A link or picture whose URL a browser would run —
javascript:,vbscript:, adata:URL — is drawn as its words, with no link and no picture. - A picture carried in its address (
,data:image/svg+xml,…) is drawn, since an<img>runs nothing it shows. A link to one is still drawn as its words. - A site-relative URL (
/about,/img.png) is addressed from the site'sbase_path, asLink(to:)'s is.
Write a table
To write a table, give a header row, a delimiter row with as many cells, then the rows, as in GitHub's Markdown:
| Function | Does | Where |
|---|:-:|--:|
| `log(x)` | Prints to the console | anywhere |
| `t("key")` | A translation \| a plural | anywhere |
The rules:
- A
:at the left, at both ends or at the right of a delimiter cell aligns its column left, centre or right. - The pipes at either end of a row may be left out, and
\|is a pipe inside a cell. - A row with fewer cells than the header has empty ones; cells past the header's are dropped.
- The rows run to a blank line or another block, and a table may start right after a paragraph's last line.
- A cell takes the inline Markdown a paragraph does.
Escape a character with a backslash
To show a punctuation mark without its Markdown meaning, put a backslash before it, as in CommonMark:
| You write | It shows |
|---|---|
|
|
|
|
|
the brackets and parentheses, with no link |
|
|
|
|
|
|
|
|
one backslash |
Every ASCII punctuation mark can be escaped this way (\-, \{, \(, \_, \& and the rest), and an escaped mark is only the character it is: it makes no link, no emphasis and no entity.
How escapes behave in links:
- In a link's words, an escaped bracket is a bracket like any other (
[a\]b](/c)). The words hold no unescaped[, so in[a [b](/c)onlybis the link. - In a URL, an escape is read as the character it is, so
[x](javascript\:alert\(1\))is checked as thejavascript:alert(1)URL it says, and drawn as its words.
Where a backslash is shown as written:
- before anything that is not ASCII punctuation, as in
C:\Users; - in a code span or a fence, where nothing is Markdown;
- at the end of a paragraph's, a heading's or a list item's last line, which has no line after it to break to.
A fence's language takes escapes too: c\+\+ after the backticks is c++.
Variations
Show text somebody else wrote with .inert
Documentation from a language server, a /// comment or a package's readme is text somebody else wrote. It often has HTML entities in it, and links and pictures that should not be followed or fetched from where you show it. To show it, add .inert:
page Hover(path: "/", title: "Hover", description: "Documentation from a language server.") {
state docs = "Returns a list of <T> — see [the guide](https://example.com/guide).\n\n"
Heading("Hover").h1
Markdown(docs).inert
}
It draws one paragraph, Returns a list of <T> — see the guide., with no link in it, and leaves the badge out. Under .inert:
- Entities are decoded, then escaped.
<color>shows as<color>, and a<script>, written out or encoded, is shown as text. In `codeand in a fence an entity stays as written, as CommonMark leaves it. The named entities are the ones documentation is written with —<>&"' , the dashes, quotes and arrows, and a few signs — and any numeric entity works (<,<`). - A link is drawn as its words, with no
<a>. - A picture is left out, with the space after it. A paragraph of nothing but pictures is left out with them.
- Everything else is drawn as plain
Markdowndraws it: paragraphs, fences,code,**strong**,*em*and_em_, headings, lists, quotes, rules and backslash escapes. A language server escapes its documentation this way: the CSS one writesmargin\-topand<length\-percentage>\{1,4\}, which.inertshows asmargin-topand<length-percentage>{1,4}. An escaped&begins no entity:\<shows the four characters<.
inert: also takes a value, Markdown(docs, inert: untrusted), and follows it. Plain Markdown is unchanged: an entity in it shows as it was written, so a page that wrote < to mean those four characters still shows them.