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:

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

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

![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.

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:

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

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

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

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

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

</Accordion>

Tabs: tabbed content.

<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).

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

VideoInline: a YouTube video, or your own file.

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

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

<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).

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

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.