# Markdown extensions

> Markdown and MDX features the theme adds: heading IDs, smart typography, callouts, and MDX expressions.

export const year = new Date().getFullYear();

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 {#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:

```md
## 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:

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

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

Example deep links on this page: [smart typography](#smart-typography),
[callouts](#callouts), [MDX expressions](#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 {#smart-typography}

The theme uses
[remark-smartypants](https://github.com/silvenon/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 {#base-links}

Root-absolute links and image sources in markdown (`[crits](https://anucybernetics.github.io/astro-theme-university/crits/)`,
`![photo](https://anucybernetics.github.io/astro-theme-university/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 {#callouts}

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

```md
:::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.

:::tip

This is a live callout rendered with the `:::tip` directive.

:::

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

```md
:::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](https://anucybernetics.github.io/astro-theme-university/docs/components/callout) for the full API and
component syntax.

## Syntax highlighting

Fenced code blocks get syntax highlighting via [Shiki](https://shiki.style/)
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:

````md
```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.

```md
| 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 {#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:

```mdx
export const courseName = "COMP1234";

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

This page was built in {year}.

### Frontmatter in the body

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

```mdx
---
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:

```ts
// src/site-data.ts
export const courseCode = "COMP1234";
export const convenor = "Dr Smith";
```

```mdx
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](https://anucybernetics.github.io/astro-theme-university/docs/getting-started/configuration/#site-config)).
