# Writing Content (Markdown, MDX & Shortcodes)

## Writing Content

**Skill level:** Beginner · **Used in:** journal posts, project and service pages, team member bios, legal and text pages

Every content file has two parts: the **frontmatter** between the two `---` lines at the top (settings and short texts, written in YAML), and the **body** below it (longer text, written in Markdown). Files that end in `.mdx` can also use **shortcodes**: small components such as callouts, steps, and tabs. The theme's `/components/` page shows every shortcode, with its code (source: `src/content/pages/english/components.mdx`).

Bodies are shown on journal posts, project pages, service pages, team member pages, and text pages such as the legal pages. Shortcodes work in all of them when the file ends in `.mdx`.

### Short Texts In The Frontmatter
Section titles and lines in Margo use two small conventions:

```yaml
title: "Recent work,\nfrom brief to *shelf*"
description: "**Two ways in, both priced up front.** A monthly seat for ongoing work."
```

- In a two-tone heading, `\n` splits the lighter first line from the darker second line, and `*word*` sets one word in the serif accent font. Use one accent per heading, or none.
- In a line, the `**bold**` lead is set darker than the rest.
- Wrap text in double quotes. If the text itself has a double quote, use single quotes around it instead.

### Markdown Basics
```md
## A section heading
### A smaller heading

Plain text. **Bold**, _italic_, `inline code`, and [a link](/contact/).

- A list item
- Another item

1. A numbered step
2. Another step

> A quote.
```

- Start body headings at `##`. The page title is already the main heading.
- Headings feed the table of contents: `##` and `###` on journal posts, `##` on text pages. It shows when a page has two or more. `enable` under `[settings.markup.tableOfContents]` in `config.toml` turns it off.
- Links to other sites open in a new tab.

### Images In The Body
```md
![A ribbed mustard vase holding dried grass](../../../assets/images/projects/ceramic-forms/gallery-2.jpg)
```

A path relative to the content file, into `src/assets/images/`, is optimized at build time, as on `/components/`. A path that starts with `/` points to the `public/` folder and is served as it is. Frontmatter image fields such as `image` are different: write them from `/images/`, and they read from `src/assets/images/`. See [Icons & Images](/margo/customization/icons-images/).

Always write alt text that describes what is visible.

### Code Blocks
Fence code with three backticks and the language. Every block gets syntax highlighting and a copy button. Add `title="..."` to show a file name:

````md
```toml title="config.toml"
[settings]
  colorMode = "system"
```
````

Code block colors follow `[settings.markup.codeBlocks] theme` in `config.toml`: `auto` (follows light and dark mode) or `dark` (dark in both).

### Shortcodes
Use these in `.mdx` files. They are available everywhere without an import (the list is in `src/lib/shortcodes.ts`). Leave an empty line after the opening tag and before the closing tag when the inside is Markdown.

**Callout**: a highlighted note. `type` is `note`, `tip`, `warning`, or `danger`; `title` is optional.

```mdx
<Callout type="tip" title="Check proofs at real size">
  Print a page at 100% before you sign off.
</Callout>
```

**Steps**: numbers every `##` or `###` heading inside it.

```mdx
<Steps>

### Send the brief

A few lines about the project.

### Book a first call

Pick a time that works.

</Steps>
```

**Accordion**: a collapsible block. Accordions with the same `group` close each other.

```mdx
<Accordion label="What files do I get?" group="files" expanded="false">

Editable source files, print-ready PDFs, and web exports.

</Accordion>
```

**Tabs**: tabbed content.

```mdx
<Tabs>
  <Tab name="Overview">The first tab.</Tab>
  <Tab name="Discovery">The second tab.</Tab>
</Tabs>
```

**Button**: a theme button, with the same options as buttons in content files (`variant`: `fill`, `outline`, `fill-white`, `text`, or `circle`; `hoverEffect`: `text-flip`, `creative-fill`, `magnetic`, or `magnetic-text-flip`).

```mdx
<Button label="Start a project" url="/contact/" variant="outline" />
```

**VideoInline**: a YouTube video, or your own file.

```mdx
<VideoInline src="rFVpSwgCkCo" provider="youtube" />
<VideoInline src="/videos/test-video.mp4" provider="html5" poster="/images/home/studio-reel.jpg" />
```

**ListCheck**: a list with check icons.

```mdx
<ListCheck>

- **One label per colour**: every new product needed its own label.
- **Files in one inbox**: every reorder waited for one person.

</ListCheck>
```

**CodeTabs**: several code fences as tabs. Each `title` becomes a tab, and the visitor's choice is remembered across the site.

````mdx
<CodeTabs>

```bash title="npm"
npm install
```

```bash title="pnpm"
pnpm install
```

</CodeTabs>
````

**FileTree** (a folder tree from a nested list) and **Kbd** (keyboard keys: `<Kbd>⌘</Kbd>`) work too.

`/components/` also shows `Card` and `CardWrapper` (information cards with an icon and a button), `ImageList` and `ImageItem` (image rows, with an optional video), and `Testimonial`. `Notice` still works and renders a callout (`info` → note, `success` → tip, `warning` → warning, `error` → danger).

<Aside type="caution" title="MDX is stricter than Markdown">
  In `.mdx` files, `{`, `}`, and `<` have a special meaning. If a build fails
  on a line with one of them in normal text, put the text in backticks or
  write `\{` and `&lt;`. Plain `.md` files don't have this rule, but can't
  use shortcodes.
</Aside>

### The Components Page
`/components/` is a demo of the shortcodes. It is left out of site search (`[settings.search] exclude` in `config.toml`) and of the AI files (`excludeFromAi: true` in its file). Delete `components.mdx` in each language folder of `src/content/pages/` before launch, or keep it as a reference.

### Do It With AI
```text
Write a journal post about [TOPIC] as an .mdx file in src/content/blog/english/. Match the
frontmatter of the other posts in that folder (title, description, image, date, author,
categories, tags). Use ## headings, one <Callout type="tip">, and <Steps> for any how-to part.
Keep it under [N] words. Then create the french and arabic versions with the same file name.
```