Writing Content

Skill level: Beginner · Used in: blog posts, changelog entries, feature pages, legal and text pages

The text below the frontmatter of a content file is written in Markdown. Files that end in .mdx can also use shortcodes: small components such as callouts, steps, and tabs. The /components/ page of the theme shows every shortcode (source: src/content/pages/english/components.mdx).

Markdown Basics

## A section heading
### A smaller heading

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

- A list item
- Another item

1. A numbered step
2. Another step

![Alt text that describes the image](/images/gallery/1.jpg)

> A quote.

• Start post headings at ##. The page title is already the # heading.
• Links to other sites open in a new tab automatically.
• In the Markdown body, an image path that starts with / points to the public/ folder: /images/gallery/1.jpg is public/images/gallery/1.jpg, served as it is. Frontmatter image fields such as image are different: they read from src/assets/images/ and are optimized. See Icons & Images.
• Headings feed the “On this page” table of contents on posts, legal pages, and guide feature pages.

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 in the header:

```ts title="deploy.config.ts"
export default defineConfig({ region: "eu-west" });
```

Tabs for alternatives, such as package managers: wrap several fences in <CodeTabs>. Each title becomes a tab, and the visitor’s choice is remembered across the site:

<CodeTabs>

```bash title="npm"
npm install @cloud/sdk
```

```bash title="pnpm"
pnpm add @cloud/sdk
```

</CodeTabs>

Code block colors follow [settings.markup.codeBlocks] theme in config.toml (auto or dark).

Shortcodes

Use these in .mdx files. They are available everywhere without an import. 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="Pin the CLI version">
  Lock the version in CI so builds don't change under you.
</Callout>

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

<Steps>

### Install the CLI

Run `npm install -g @cloud/cli`.

### Deploy

Run `cloud deploy`.

</Steps>

FileTree: a folder tree from a nested list. A name ending in / is a folder, bold highlights a file, and text after the name is a comment.

<FileTree>

- src/
  - pages/
    - **index.astro** the home page
- package.json

</FileTree>

Kbd: keyboard keys.

Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to search, or <Kbd keys={["Ctrl", "Shift", "P"]} />.

Tabs: tabbed content.

<Tabs>
  <Tab name="Overview">The first tab.</Tab>
  <Tab name="Details">The second tab.</Tab>
</Tabs>

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

<Accordion label="How are builds billed?" group="faq" expanded="false">
  Per second of build time, after the free minutes.
</Accordion>

Button: a theme button, with the same options as buttons in content files.

<Button label="Start for free" url="/signup/" variant="fill" />

VideoInline: a YouTube video or your own file.

<VideoInline src="rFVpSwgCkCo" provider="youtube" />
<VideoInline src="/videos/demo.mp4" provider="html5" poster="/images/video-thumbnail.jpg" />

ListCheck: a list with check icons.

<ListCheck>

- **Fast releases**: every push ships in minutes.
- **Safe rollbacks**: one click back to any deploy.

</ListCheck>

/components/ also shows Card and CardWrapper (information cards), ImageList and ImageItem (image galleries), and Testimonial. Notice still works and renders a callout (info → note, success → tip, warning → warning, error → danger).

Do It With AI

Write a [blog post | changelog entry | guide] about [TOPIC] as an .mdx file in
src/content/[blog | changelog]/english/. Match the frontmatter of the other files in that folder.
Use ## headings, code fences with title="..." where useful, <CodeTabs> for npm and pnpm commands,
one <Callout type="tip">, and <Steps> for any how-to part. Keep it under [N] words.