Skip to main content

Markdown extensions

The theme configures several remark and rehype plugins that extend standard Markdown. These work automatically in all .md and .mdx content files.

Custom heading IDs

Headings automatically get an id derived from their text, but sometimes you need a shorter or more stable anchor. Append {#your-id} to the end of a heading to set it manually:

## My heading {#my-id}

The {#my-id} is stripped from the rendered text and the heading’s id attribute is set to my-id. You can then deep-link to it with a standard fragment link:

[jump to My heading](#my-id)

[link from another page](/docs/guides/markdown-extensions#my-id)

Example deep links on this page: smart typography, callouts, MDX expressions.

A custom ID helps when heading text is long, might change, or you want a readable fragment for cross-page links. Otherwise the ID auto-generates from the heading text: spaces become hyphens, everything lowercased.

Autolinked headings

Every heading gets a # anchor appended, visible on hover; clicking it (or copying the link) gives a permalink. This works for both custom and auto-generated IDs. The anchor is a mouse affordance only: it’s hidden from assistive technology and out of the tab order, since screen-reader and keyboard users navigate by heading directly.

Smart typography

The theme uses remark-smartypants to convert plain-text punctuation into typographic equivalents:

You writeYou get
"quotes"“quotes”
'single'‘single’
---em dash —
--en dash –
...ellipsis…

Dashes use “oldschool” mode: --- produces an em dash and -- produces an en dash.

Root-absolute links and image sources in markdown ([crits](/crits/), ![photo](/images/photo.avif)) are automatically prefixed with the site’s configured base at render time. This keeps a site deployed under a sub-path (e.g. GitLab Pages at /courses/comp4020) from shipping 404s on every internal prose link. When base is / (the default), this is a no-op.

The convention this enforces: a root-absolute path is always site-internal. To link to a page on the same domain but outside your base (say, another course site), use a full URL. A post-build check (part of checkLinks) fails the build if any rendered href or src escapes the base. Such a link would 404 in production while resolving fine locally.

Links in raw markdown consumed by machines (the /llms.txt outputs and any content APIs built from collection bodies) are unaffected. The rewrite happens at the HTML layer only.

Callouts

Container directives (:::) create styled callout boxes. Four types are available:

:::tip

A helpful suggestion.

:::

:::info

Additional context.

:::

:::warning

Something to watch out for.

:::

:::error

A critical issue.

:::

Always include blank lines around the ::: markers and their content; without them, the formatter may reflow the text into the directive markers.

A [label] on the opening marker becomes the callout’s title, and :::danger and :::caution are accepted as aliases for error and warning:

:::warning[Heads up]

Titled callout.

:::

The same directive syntax also renders a native disclosure widget: :::details[Summary text] wraps its content in <details>, with the label as the <summary>.

See the Callout component docs for the full API and component syntax.

Syntax highlighting

Fenced code blocks get syntax highlighting via Shiki with the theme’s custom light and dark colour schemes that match the site’s colour scheme. Just specify the language after the opening fence:

```ts
const message: string = "highlighted";
```

Tables

A table marks its header row with weight and a single rule in the brand colour, separates rows with hairlines, and sits flush with the text block on both sides. Column alignment is markdown’s own: --: right-aligns a column, which is what a column of numbers wants, and the theme sets its figures at a fixed width so the digits line up.

| Model     | Parameters (M) | Accuracy |
| :-------- | -------------: | -------: |
| Baseline  |             86 |    71.4% |
| Distilled |             22 |    69.8% |
| Proposed  |            111 |    78.2% |
ModelParameters (M)Accuracy
Baseline8671.4%
Distilled2269.8%
Proposed11178.2%

Wide tables

Markdown tables render full-width. Because CSS ignores overflow on table boxes, the theme wraps every table in a .at-table-wrap scroll container at render time, so a table wider than its column scrolls sideways in place rather than pushing the page out.

MDX expressions

In .mdx files, JavaScript expressions use single curly braces. This is standard MDX syntax, not a theme plugin.

Inline variables

Define variables with export const and reference them in the body:

export const courseName = "COMP1234";

Welcome to {courseName}. This page was built in {new Date().getFullYear()}.

This page was built in 2026.

Frontmatter in the body

To use frontmatter values in the body of an MDX file, re-export them:

---
title: My page
code: COMP1234
---

export const code = frontmatter.code;

Welcome to {code}.

Site-wide variables

For values shared across multiple pages, define them in a plain TypeScript module and import where needed:

// src/site-data.ts
export const courseCode = "COMP1234";
export const convenor = "Dr Smith";
import { courseCode, convenor } from "../../site-data";

This site is for {courseCode}, convened by {convenor}.

Keep this separate from src/site-config.ts: that file should use defineSiteConfig from astro-theme-university/types and hold only fields matching the theme’s SiteConfig type (see configuration).