Markdown

Any .md file in src/pages is a page. Markdown is turned into HTML when the site is generated, so pages ship plain HTML and no Markdown library reaches the browser.

---
title: Privacy · Acme
description: How we use the details you send us.
layout: prose
---

## What we collect

When you use the [contact form](/contact) we receive your name and email address.

Front matter

The YAML between the --- lines becomes the page's meta:

• title, description, noindex and the other meta keys work as usual.
• layout: name picks src/layouts/name.imba; layout: false renders without one.
• Any other field (heading, updated, …) is passed to the layout as meta, so a layout can show it.

Values are what YAML makes of them: updated: 1 October 2026 stays a string.

Styling rendered Markdown

The rendered text always sits in an element with the class prose. Imba's scoped css blocks don't reach HTML that came from Markdown, so style it with global css:

global css
	.prose max-width:70ch
	.prose > * + * mt:1em
	.prose h2 fs:2xl mt:2em
	.prose a c:indigo6 td:underline

Showing Markdown in a template

For Markdown from a collection, place its HTML with the Markdown tag:

import {Markdown} from '@milktop/imba-pages/markdown'

<Markdown.prose html=entry.html>

Markdown just sets the HTML as given. Markdown is treated as trusted: HTML written inside a .md file is kept.

Code blocks

Fenced code blocks are highlighted at build time with Shiki, with no JavaScript and no CSS needed. Name the language after the fence:

```imba
export default tag Hello
	<self> "Hi"
```

Supported: imba, javascript, typescript, html, css, json, yaml, markdown, bash, shellsession, toml, diff. Other languages are shown as plain code.

Colours are written as CSS light-dark(): blocks are light by default, and follow the visitor's dark mode too when the page declares it supports both:

export def head ctx
	[<meta name='color-scheme' content='light dark'>]

Heading links

Every heading gets an id made from its text (## What we collect → id="what-we-collect"), so /privacy#what-we-collect jumps to it. Repeated headings get -1, -2.

The headings are also available as a list, for an "On this page" menu like the one on the right of these docs, each {depth, text, id}:

• for collection entries: entry.headings
• for Markdown pages: meta.headings, so the page's layout can show them

Not supported yet

Components inside Markdown (Astro's MDX), heading anchor icons, image processing.