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:

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

- [x] Task list1
- [ ] Task list2

The preceding snippet renders as:

Task list1
Task list2

A strikethrough example:

~~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:

<Callout type="note">
  This is a note callout.
</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:

<Steps>
  <Step title="Install the dependencies">
    Run `npm install`.
  </Step>
  <Step title="Start the development server">
    Run `npm run dev`.
  </Step>
  <Step title="Open the site">
    In a browser, go to `http://localhost:3000`.
  </Step>
</Steps>

The preceding snippet renders as:

Install the dependencies

Run npm install.

Start the development server

Run npm run dev.

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 ![The dashboard](dashboard.png)

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:

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.

Insert the component

Insert the Image or Video component.

For example, with content/media/dashboard.png and content/media/setup-demo.mp4:

<Image src="dashboard.png" alt="The dashboard with two connected projects" />
 
<Video src="setup-demo.mp4" title="Connecting a project" caption="Connect a project in under a minute." />

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:

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:

{
  "supportEmail": "support@example.com",
  "latestVersion": "2.4.0"
}

Reference the custom variables in a page

Reference the variables in a page:

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

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:

To insert the product name, type \{\{productName}} in your page.

Renders as:

To insert the product name, type {{productName}} in your page.