Markdown Reference

A quick reference for the markdown and MDX syntax used across this site. Each section shows the code and the rendered result.

Headings

## Major Section (H2)
### Sub-section (H3)
#### Detail (H4) — use sparingly

Use exactly one # (H1) per page. Since this page already has one, the examples above start at H2.

Text Formatting

**bold** for emphasis and UI labels
*italic* for introducing key terms
`backticks` for code, file names, and identifiers
~~strikethrough~~ for deprecated content

Rendered:

bold for emphasis and UI labels italic for introducing key terms backticks for code, file names, and identifiers ~~strikethrough~~ for deprecated content

Links

Internal links use root-relative paths — do not include the .mdx extension:

[Getting Started](/mkio/getting-started)
[Jump to section](/mkio/getting-started#uploading-content)

Rendered:

Getting Started Jump to section

External links:

[MediaKind](https://www.mediakind.com)

Rendered: MediaKind

Images

Always include descriptive alt text so the image is accessible to screen readers.

Where to store images

There are two places you can store image files:

/public/ folder (recommended for shared assets)

Files placed in /public/ are served at the root URL path. Use this for images shared across multiple pages or product sections.

public/
  images/
    beam/
      beam-architecture-overview.png
    mkio/
      mkio-dashboard-screenshot.png

Reference them with an absolute path starting with /:

![Beam architecture overview](/images/beam/beam-architecture-overview.png)

Next to your .mdx file (page-specific assets)

For images used only by a single page, you can place the file in the same folder as the .mdx file and use a relative path:

src/content/docs/beam/quick-start/
  index.mdx
  quick-start-ui.png

![Quick start UI](./quick-start-ui.png)

Naming conventions

Use lowercase with hyphens: beam-encoder-settings.png, not BeamEncoderSettings.PNG
Prefix with the section name for shared images: beam-, mkio-, api-
Be descriptive: live-encoder-audio-tab.png, not screenshot1.png

File size and format

Prefer PNG for UI screenshots and diagrams; JPEG for photos
Compress images before committing — keep files under 500 KB where possible
For diagrams, SVG is preferred when the source is available

Rendered example

![MediaKind logo](/images/mkcirclebadge.png)

Rendered:

MediaKind logo

Keep images to a minimum. Only use screenshots when text alone cannot explain a UI action.

Lists

Unordered:

- Item one
- Item two
  - Nested item

Rendered:

Item one
Item two
- Nested item

Ordered (use for sequential steps):

1. First step.
2. Second step.
3. Third step.

Rendered:

First step.
Second step.
Third step.

Tables

| Field   | Required | Notes                  |
| :------ | :------- | :--------------------- |
| region  | Yes      | Use a supported region |
| profile | No       | Advanced only          |

Rendered:

Field	Required	Notes
region	Yes	Use a supported region
profile	No	Advanced only

With text alignment:

| Left aligned | Right aligned | Centered |
| :----------- | ------------: | :------: |
| Apple        | 100           | -        |
| Oranges      | 1,000         | n/a      |
| Carrots      | 40            | -        |

Rendered:

Left aligned	Right aligned	Centered
Apple	100	-
Oranges	1,000	n/a
Carrots	40	-

Code Blocks

Always specify a language tag after the opening fence:

```bash
pnpm dev
```

Rendered:

pnpm dev

```json
{
  "name": "example"
}
```

Rendered:

{
  "name": "example"
}

Supported languages include: bash, json, javascript, typescript, python, yaml, http, txt, and more.

Do not prefix terminal commands with $ or >.

Blockquotes

> This is a blockquote. Use sparingly — prefer Callout components for tips and warnings.

Rendered:

This is a blockquote. Use sparingly — prefer Callout components for tips and warnings.

Horizontal Rules

Use --- on its own line to create a visual separator between sections.

Common Gotchas

New pages do not appear in the sidebar until you add them to the folder’s _meta.json.
.md files cannot use React components — rename to .mdx if you need components.
Do not include .mdx in internal links — /mkio/getting-started, not /mkio/getting-started.mdx.
One # heading per page — using multiple H1s breaks the document outline.
Always add a language tag to code blocks — unlabelled fences render without syntax highlighting.