# 110. MDX and markdown
**For app developers.** How a page or a piece of content is written in MDX or plain markdown, how the build lowers it like any other component, how a page picks a file by its data, the component map that styles markdown's elements, highlighted code and the collections an index reads.
## MDX is a feature of fsr
The parser, the highlighter and frontmatter are Cargo features of the CLI, on by default. An install that wants none of them turns the defaults off and keeps what it needs:
```sh
cargo install snapfire_fsr_cli --no-default-features --features tera
```
| Feature | Reads |
| --- | --- |
| `mdx` | `.mdx` and `.md` routes and imports |
| `mdx-highlight` | `mdx`, plus fenced code highlighted at build |
| `mdx-frontmatter` | `mdx`, plus YAML or TOML frontmatter as `export const meta` |
An fsr built without `mdx` refuses an `.mdx` page or import by name rather than leaving it out. A `build.rs` that builds an application gets the features with the build dependency's defaults.
`fsr use app mdx` writes a starter `mdx-components.tsx` and, with highlighting built in, `styles/code.css`. `fsr new shop --with mdx` starts an application with them.
## A page written in MDX
`page.mdx` beside a route's loader is the route's page. It follows MDX: ESM at the top, markdown with JSX in it and `{expressions}`:
```mdx
export const meta = { title: "Install ยท The FSR handbook" };
# Install
{props.steps.map((step) => (
{step.command}{step.explains}
))}
This page is {props.steps.length} steps from `src/content.ts`.
```
The loader runs first, as for `page.tsx`. Its data is `props`. `export const meta` is the route's meta, a plain object since an MDX file has no `{ data }` to read; a route whose loader also exports `meta` is refused. `page.md` is markdown alone, MDX's `md` format, with no JSX and no expressions. Raw HTML in it is left out with a warning in the build report.
The build turns the file into TSX and lowers that, so everything chapter 102 says about a component holds. An import lowers, a vendored component becomes an island, an expression lowers where it can and what does not is moved into an island the browser renders, as for a page. A residue names the line and column of the `.mdx`, here under `[build] strict`:
```text
routes/page.mdx:3:6: `window` is not bound here; an import the build cannot follow or a name from outside the body
```
## Importing a file
An `.mdx` or `.md` file under the app is a module whose default export is a component:
```tsx
import Post, { meta, toc } from "../content/first.mdx";
export default function Page() {
return (
{meta.title}
);
}
```
`toc` lists the file's headings, each `{ depth, id, text }`. `generated/mdx.d.ts` declares `*.mdx` and `*.md` for the type checker.
## A page that picks a file by its data
The blog's post page is one route for every post. It imports the file its data names, the way a Next page does:
```tsx
export default async function PostPage({ post }: PostSlugProps) {
const { default: Body, meta } = await import(`../../../content/posts/${post.file}`);
return
{meta.title}
;
}
```
The build reads the template: every file under the directory it names that fits it is a choice, lowered once, subdirectories included as a webpack context includes them. A file in a subdirectory is chosen by its path there, so `` import(`../content/${entry.file}`) `` reaches `plaza/tutorials/010-join.md` with `file` set to that path. This holds for a template import of any file, `.tsx` as much as `.mdx`. `
` renders the one whose name the key spells and `meta` is that file's export. A key that names no file renders nothing. The page may be `async` when everything it awaits is such an import; any other `await` belongs in its loader.
## Collections
An index needs every post's title without a list of its own. `[mdx.collections]` names a directory:
```toml
[mdx.collections]
posts = "content/posts"
```
The build writes `generated/content.ts` with one entry per `.mdx` or `.md` file under it, subdirectories included, by path:
```ts
import { posts } from "@generated/content";
export const titles = posts.map((post) => post.meta.title);
export const paths = () => posts.map((post) => ({ slug: post.slug }));
```
Each entry is `{ slug, file, meta, toc, excerpt }`: `file` is the path under the collection's directory and is what a template import takes. `slug` is that path without its extension. A file in a subdirectory has a `/` in both, `plaza/tutorials/010-join`, so a catch-all route takes the slug whole and a loader splits it to group by directory. A directory named `node_modules` or starting with `.` is left out. `excerpt` is the plain text of the file's first paragraph or `null` when it has none. A loader sorts and filters the list like any other constant.
## The component map
`mdx-components.tsx` at the app's root maps the elements markdown writes to components, as Next reads it:
```tsx
import type { MDXComponents } from "mdx/types";
function Heading({ id, className, children }: { id?: string; className?: string; children?: any }) {
return