---
title: "Authoring Components"
description: "Formatting and MDX components reference."
url: https://beacon-arodoni.vercel.app/format
---
# Authoring Components in Beacon
## Product logo
To show your product logo on the documentation site, add an image file named
`logo` to the `content/` folder, such as `content/logo.svg`. Supported file
types are `.svg`, `.png`, `.jpg`, `.jpeg`, and `.webp`.
To show a different logo in dark mode, also add a file named `logo-dark`, such
as `content/logo-dark.svg`. If you don't add one, the site shows your `logo`
file in both modes.
The top bar displays the logo 24 pixels high and scales the width to match.
For the sharpest result, use an SVG file. Keep only one `logo` file and one
`logo-dark` file in `content/`, or the build fails.
The local development server reads the logo when it starts, so restart it after
you add or change the logo.
## Table, task list, and strikethrough
Tables, task lists, and strikethrough work through `remark-gfm` in Beacon.
The following examples show a table, a task list, and strikethrough text.
A table example:
```markdown
| Table column1 | Table column2 | Table column3 |
| --- | --- | --- |
| Table cell | Table cell | Table cell |
```
The preceding snippet renders as:
| Table column1 | Table column2 | Table column3 |
| --- | --- | --- |
| Table cell | Table cell | Table cell |
A task list example:
```markdown
- [x] Task list1
- [ ] Task list2
```
The preceding snippet renders as:
- [x] Task list1
- [ ] Task list2
A strikethrough example:
```markdown
~~Anything else~~ is not needed
```
The preceding snippet renders as:
~~Anything else~~ is not needed
## Callouts
Use the `Callout` component to highlight notes, tips, important information, and warnings.
For example:
```markdown
This is a note callout.
```
Sample renderings:
> **Note**
>
> This is a note callout.
> **Tip**
>
> This is a tip callout.
> **Important**
>
> This is an important callout.
> **Warning**
>
> Always keep your API keys private. Do not share them in public repositories.
## Steps
Use the `Steps` and `Step` components to show a procedure as a numbered sequence. Each `Step` takes a `title` and numbers itself, so you can add, remove, or reorder steps without renumbering them.
For example:
```markdown
Run `npm install`.
Run `npm run dev`.
In a browser, go to `http://localhost:3000`.
```
The preceding snippet renders as:
1. **Install the dependencies**
Run `npm install`.
2. **Start the development server**
Run `npm run dev`.
3. **Open the site**
In a browser, go to `http://localhost:3000`.
## Images and videos
To add images and videos to your pages, you can use:
- The `Image` and `Video` components
- Markdown image syntax, such as ``
Use the `Image` component when you want a caption or a set width.
To add an image or video to a page with the `Image` or `Video` component:
1. **Place the file in the media folder**
Put the file in the `content/media/` folder.
Supported file types are `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.mp4`, `.webm`, and `.mov`.
2. **Insert the component**
Insert the `Image` or `Video` component.
For example, with `content/media/dashboard.png` and `content/media/setup-demo.mp4`:
```mdx
```
Set `src` to the file's path inside `content/media/`, such as `screenshots/dashboard.png` for a file in a subfolder.
You can also set `src` to a full URL, such as `https://example.com/diagram.png`.
Both components take these properties:
| Property | Component | Required | Description |
| --- | --- | --- | --- |
| `src` | Both | Yes | The file in `content/media/`, or a full URL. |
| `alt` | `Image` | Yes | Text that describes the image for screen readers. |
| `title` | `Video` | Yes | A short name for the video, read by screen readers. |
| `caption` | Both | No | Text to show below the image or video. |
| `width` | `Image` | No | The image width in pixels, in quotes, such as `width="320"`. By default, the image is its natural width, up to the width of the page. |
| `poster` | `Video` | No | An image in `content/media/` to show before the video plays. |
| `autoPlay` | `Video` | No | Add `autoPlay` with no value to play the video automatically, muted and on a loop, like an animated GIF. |
When previewing locally, the local development server copies `content/media/`
when it starts, so restart it after you add or change a file.
## Documentation variables
To insert a variable in a page, write its name inside double curly braces.
Variables work in frontmatter and in the page body, including inside code
blocks.
Beacon has two built-in variables:
| Variable | Value |
| --- | --- |
| `productName` | The product name |
| `projectName` | The project name |
The build fails if a page uses a variable that doesn't exist.
### Add your own variables
To define more variables:
1. **Add variables to the JSON file**
Add the variables to `content/variables.json` as names and string values.
Variable names can contain only letters, digits, and underscores, and can't reuse a built-in name. The build fails if the file isn't valid JSON or if a value isn't a string.
For example:
```json
{
"supportEmail": "support@example.com",
"latestVersion": "2.4.0"
}
```
2. **Reference the custom variables in a page**
Reference the variables in a page:
```mdx
---
title: Get help
description: How to contact support about version {{latestVersion}}.
---
# Get help
If you have questions about version {{latestVersion}}, email
[{{supportEmail}}](mailto:{{supportEmail}}).
```
The page renders as:
```text
If you have questions about version 2.4.0, email support@example.com.
```
Restart the development server after you edit `content/variables.json`.
### Show a variable name as literal text
To show a variable's name in curly braces without replacing it, for example in
a code block, put a backslash in front of it. `\{{productName}}` renders as
`{{productName}}`.
This works in code blocks, inline code, and frontmatter. In regular text, MDX
treats curly braces as code, so an escaped variable renders as nothing. In
regular text, put a backslash in front of each opening brace instead. For
example, this line in a page:
```mdx
To insert the product name, type \{\{productName}} in your page.
```
Renders as:
```text
To insert the product name, type {{productName}} in your page.
```