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 write | You get |
|---|---|
"quotes" | “quotes” |
'single' | ‘single’ |
--- | em dash — |
-- | en dash – |
... | ellipsis… |
Dashes use “oldschool” mode: --- produces an em dash and -- produces an en
dash.
Base-path-aware links#
Root-absolute links and image sources in markdown ([crits](/crits/),
) 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% |
| Model | Parameters (M) | Accuracy |
|---|---|---|
| Baseline | 86 | 71.4% |
| Distilled | 22 | 69.8% |
| Proposed | 111 | 78.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).