{title}
{description ? (
{description}
) : null}
{title}
```
### Fonts and images
Inter is loaded at weights 400 and 700, so set `fontFamily: 'Inter'` — any other family falls back to it. Pages with non-Latin text get matching Noto fonts added when the site builds; the editor preview only has Inter, so non-Latin text can look different there. Emoji are not supported and draw as an empty box.
Use the `logo` prop as an `img` source, and handle `null` for a site with no logo.
### Imports
A template can import other files inside your project — a shared color, a helper next to it — and those are bundled when the site builds. Packages are not available: an npm package, or a Node builtin like `node:fs`, fails the build and names the import. Inline whatever the card needs.
## When a card fails
- A template that throws, or returns an invalid style value, skips the card for that page. The build log names your file and the error once, and the page is published without an `og:image` tag.
- A template file that is missing or does not compile fails the build.
- A card that takes more than 20 seconds to render is skipped.
## Previewing in the editor
With the configured template open in the Scalar editor, the preview pane draws the card as you type, using your theme and a page from your site, and shows how the link looks on Slack, LinkedIn, iMessage and Discord. It renders in the browser — layout and colors match, but the final PNG is produced when the site builds.
## Learn more
- [Satori's supported CSS](https://github.com/vercel/satori#css)
- [Satori playground](https://og-playground.vercel.app), for trying out layouts
- [The Open Graph protocol](https://ogp.me)
# Ask AI
Ask AI adds an AI-powered assistant to your documentation site. The assistant searches across all your docs content, combines information from multiple pages, and returns a short, accurate answer.
Ask AI is enabled by default for all Scalar Docs projects. No setup required.
## How it works
When a user asks a question, Ask AI searches through all your published documentation. It can combine information from multiple sources to give a complete answer, even when the answer spans several pages.
## AsyncAPI documents
We do not currently support AsyncAPI for Ask AI. [AsyncAPI](../../../asyncapi.md) documents render as API references on your site, but they are not part of the context Ask AI answers from, so it cannot describe your channels or messages.
Need it? Tell us on [GitHub](https://github.com/scalar/scalar/issues/new) or email [support@scalar.com](mailto:support@scalar.com).
## MCP integration
You can connect your docs AI to LLMs like Cursor, Claude Code, Windsurf, and other tools that support Model Context Protocol (MCP). This gives the LLM the full context of your documentation, so it can answer questions about your API and product without you copy-pasting docs into the chat.
Just add /mcp to your Scalar Docs domain.
### Cursor
Add the following to your `.cursor/mcp.json`:
```json
{
"mcpServers": {
"scalar-docs": {
"url": "https://
```
### Hiding Default Page Elements
You can hide the table of contents via page configuration in `scalar.config.json`:
```json
{
"navigation": {
"routes": {
"/my-landing-page": {
"type": "page",
"filepath": "documentation/landing.md",
"layout": {
// We don't want the table of contents here:
"toc": false
}
}
}
}
}
```
## Site-Wide Head Configuration
The `siteConfig.head` configuration allows you to inject custom HTML elements into the `` of your documentation pages. This enables you to add custom stylesheets, JavaScript files, meta tags for SEO and social sharing, and link elements like favicons.
All head configuration is done within the `siteConfig.head` object in your `scalar.config.json` file.
**Example**
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"siteConfig": {
"head": {
"scripts": [
{
"path": "documentation/assets/analytics.js"
}
],
"styles": [
{
"path": "documentation/assets/styles.css"
}
],
"meta": [
{
"name": "description",
"content": "Documentation for my API"
}
],
"links": [
{
"rel": "icon",
"href": "/favicon.png"
}
]
}
}
}
```
## Scripts
The `scripts` array allows you to include custom JavaScript files in your documentation. Scripts can be injected into the `` or at the end of the `` tag, depending on your needs.
### Example
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"siteConfig": {
"head": {
"scripts": [
{
"path": "documentation/assets/analytics.js",
"tagPosition": "bodyClose"
}
]
}
}
}
```
### Properties
| Property | Type | Required | Description |
| ------------- | ------------------------------------- | -------- | ----------------------------------------------------------------- |
| `path` | `string` | Yes | Relative path to the JavaScript file from your configuration root |
| `tagPosition` | `"head" \| "bodyOpen" \| "bodyClose"` | No | Where to inject the script tag (defaults to `"head"`) |
### Tag Position
- `head`: Scripts are injected into the `` element. Use this for scripts that need to load early, such as analytics initialization or critical functionality.
- `bodyOpen`: Scripts are injected immediately after the opening `` tag. Use this for scripts that need to access the DOM as soon as possible but do not need to block page rendering.
- `bodyClose`: Scripts are injected just before the closing `` tag. Use this for non-critical scripts or analytics that should not block page rendering.
## Styles
The `styles` array allows you to include custom CSS files to customize the appearance of your documentation site.
### Example
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"siteConfig": {
"head": {
"styles": [
{
"path": "documentation/assets/styles.css"
}
]
}
}
}
```
### Properties
| Property | Type | Required | Description |
| ------------- | ------------------------------------- | -------- | ---------------------------------------------------------- |
| `path` | `string` | Yes | Relative path to the CSS file from your configuration root |
| `tagPosition` | `"head" \| "bodyOpen" \| "bodyClose"` | No | Where to inject the style tag (defaults to `"head"`) |
## Meta Tags
The `meta` array allows you to add meta tags for SEO, social sharing (Open Graph, Twitter Cards), and other metadata. Meta tags can be provided as an array of objects or as a key-value object.
### Array Format
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"siteConfig": {
"head": {
"meta": [
{
"name": "description",
"content": "Documentation for my API"
},
{
"property": "og:title",
"content": "My API Documentation"
},
{
"property": "og:image",
"content": "https://example.com/og-image.png"
}
]
}
}
}
```
### Properties
| Property | Type | Required | Description |
| ---------- | -------- | ----------- | ------------------------------------------------------- |
| `name` | `string` | Conditional | The meta `name` attribute (use for standard meta tags) |
| `property` | `string` | Conditional | The meta `property` attribute (use for Open Graph tags) |
| `content` | `string` | Yes | The meta tag content value |
### Common Meta Tags
**SEO Meta Tags**
```json
"meta": [
{
"name": "description",
"content": "Comprehensive API documentation"
},
{
"name": "keywords",
"content": "API, documentation, REST"
}
]
```
**Open Graph Tags (for social sharing)**
```json
"meta": [
{
"property": "og:title",
"content": "My API Documentation"
},
{
"property": "og:description",
"content": "Comprehensive API documentation"
},
{
"property": "og:image",
"content": "https://example.com/og-image.png"
},
{
"property": "og:type",
"content": "website"
}
]
```
**Twitter Card Tags**
```json
"meta": [
{
"name": "twitter:card",
"content": "summary_large_image"
},
{
"name": "twitter:title",
"content": "My API Documentation"
},
{
"name": "twitter:image",
"content": "https://example.com/twitter-image.png"
}
]
```
## Links
The `links` array allows you to add link elements to the ``, commonly used for favicons, preconnect hints, and other resource links.
### Example
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"siteConfig": {
"head": {
"links": [
{
"rel": "icon",
"type": "image/png",
"href": "/favicon.png"
},
{
"rel": "preconnect",
"href": "https://fonts.googleapis.com"
}
]
}
}
}
```
### Properties
| Property | Type | Required | Description |
| -------- | -------- | -------- | ---------------------------------------------------------------- |
| `rel` | `string` | Yes | The relationship type (e.g., `icon`, `preconnect`, `stylesheet`) |
| `href` | `string` | Yes | The URL or path to the resource |
| `type` | `string` | No | The MIME type of the resource (e.g., `image/png`) |
### Common Link Types
**Favicon**
```json
"links": [
{
"rel": "icon",
"type": "image/png",
"href": "/favicon.png"
}
]
```
**Preconnect (for performance optimization)**
```json
"links": [
{
"rel": "preconnect",
"href": "https://fonts.googleapis.com"
},
{
"rel": "preconnect",
"href": "https://fonts.gstatic.com",
"crossorigin": "anonymous"
}
]
```
**Canonical URL**
```json
"links": [
{
"rel": "canonical",
"href": "https://docs.example.com"
}
]
```
## Common Use Cases
### Analytics Integration
Add analytics scripts like Fathom, Google Analytics, or other tracking tools:
```json
"scripts": [
{
"path": "documentation/assets/analytics.js",
"tagPosition": "bodyClose"
}
]
```
### Custom Branding and Styling
Override default styles to match your brand:
```json
"styles": [
{
"path": "documentation/assets/style.css"
}
]
```
### SEO Optimization
Add comprehensive meta tags for better search engine visibility and social sharing:
```json
"meta": [
{
"name": "description",
"content": "Your comprehensive API documentation"
},
{
"property": "og:title",
"content": "API Documentation"
},
{
"property": "og:description",
"content": "Your comprehensive API documentation"
},
{
"property": "og:image",
"content": "https://example.com/social-preview.png"
}
]
```
### Favicon Configuration
Add custom favicons for your documentation site:
```json
"links": [
{
"rel": "icon",
"type": "image/png",
"href": "/favicon-32x32.png",
"sizes": "32x32"
},
{
"rel": "icon",
"type": "image/png",
"href": "/favicon-16x16.png",
"sizes": "16x16"
},
{
"rel": "apple-touch-icon",
"href": "/apple-touch-icon.png"
}
]
```
## Path References
When referencing files in `siteConfig.head`:
- For `scripts` and `styles`: Use the full path relative to your configuration root (e.g., `documentation/assets/script.js`)
- For `links` like favicons: Use root-relative paths (e.g., `/favicon.png`) since these files should be in your `assetsDir` and are served from the site root
Make sure your asset files are located in the directory specified by `assetsDir` or use absolute paths from your configuration root.
# MDX
MDX lets you use JavaScript and JSX components inside your Markdown files.
## Prerequisites
* Use `.mdx` instead of `.md` for the file extension.
## Configuration
Reference MDX files the same way as Markdown files:
```json
// scalar.config.json
{
"$schema": "https://registry.scalar.com/@scalar/schemas/config",
"scalar": "2.0.0",
"navigation": {
"routes": {
"/example": {
"title": "Example",
"type": "page",
"filepath": "docs/content/example.mdx" // .mdx extension
}
}
}
}
```
## Frontmatter
Add metadata at the top of your MDX files:
```markdown
---
title: "Page Title"
description: "Page description for SEO"
---
# Content
This is the content of the page.
```
## Importing Components
Import and use other MDX files as components:
```markdown
// Import MDX from other files
import Intro from './intro.mdx'
Custom styled content
```
Custom Styles
Interactive elements work too:
```markdown
```
Click me
## Expressions
Embed JavaScript expressions using curly braces:
**Code**
```markdown
The current year is {new Date().getFullYear()}.
```
**Preview**
The current year is 2026.
# GitHub
Docs connects to GitHub to read your files, open pull requests, and publish when you merge. Here's what that connection can and can't do.
## Setup
1. **Install the Scalar GitHub App.** You pick which repositories it can access. Change the selection any time.
2. **Link your GitHub user.** This attributes commits and pull requests to you.
Access is always limited to the repositories you pick. Nothing else.
## Switch repositories
For a project already connected to GitHub or Bitbucket, you can switch to another repository on either provider without disconnecting first.
The destination repository must already contain your documentation. Switching does not copy files or open a pull request to move them, so move your documentation to the destination yourself before switching.
1. Open your documentation project in the [Scalar Dashboard](https://dashboard.scalar.com) and go to **Settings → Git Sync**.
2. Click **Switch repository** beside the connected repository.
3. Choose GitHub or Bitbucket, authorize access if prompted, and select the repository containing your docs. For GitHub, make sure the Scalar GitHub App has access to that repository.
4. Review the confirmation, which names the repository you are leaving and the destination, then click **Switch**.
The editor reloads the destination repository, replacing the contents of the docs project. Future edits are committed to the new repository. Files in the previous repository stay as they are, and your live site keeps serving its current build until the next publish.
Scalar uses the destination repository's default branch and looks for a `scalar.config.*` file in the current configuration directory, the repository root, and `scalar-docs/`, in that order. If none is found, it keeps the project's current configuration path. Check the configuration and **Tracked branch** in Git Sync before publishing.
## What we can access
Only in the repositories you select:
- **Contents** — read your files and write changes through commits and pull requests.
- **Pull requests** — open and update pull requests.
- **Metadata** — basic repository info (required for every GitHub App).
## What we can't access
- Repositories you didn't select.
- Your other code across your account or organization.
- Repository settings, collaborators, or branch protection.
## "Act on your behalf"
GitHub shows this line for any app that can write to a repository, because your commits and pull requests are attributed to you. It's about attribution, not broad access. See GitHub's own [explanation](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps#about-github-apps-acting-on-your-behalf).
## Manage access
Change repositories or revoke access from GitHub under **Settings → Applications → Installed GitHub Apps**, or from the [Scalar Dashboard](https://dashboard.scalar.com). Removing a repository cuts off access to it right away.
# Markdown Support
We support all standard Markdown features, based on GitHub-flavored Markdown (GFM).
## Headings
Use one to six `#` characters to create headings from level one through six.
```md
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```
## Text Formatting
Emphasize text with bold, italic, strikethrough, and inline code.
**Bold text**
_Italic text_
~~Strikethrough text~~
`Inline code`
```md
**Bold text**
*Italic text*
~~Strikethrough text~~
`Inline code`
```
## Lists
Create unordered lists with `-` and nest items by indenting them.
* Unordered list item
* Another item
* Nested item
* Another nested item
```md
- Unordered list item
- Another item
- Nested item
- Another nested item
```
Create ordered lists with numbers, nesting items the same way.
1. Ordered list item
2. Another item
1. Nested item
2. Another nested item
```md
1. Ordered list item
2. Another item
1. Nested item
2. Another nested item
```
## Links and Images
Link to absolute URLs, other Markdown files, and embed images.
[Absolute URLs](https://example.com)
[Relative link](/products/docs/components/tables)
```md
[Absolute URLs](https://example.com)
[Relative link](/products/docs/components/tables)
```
## Code Blocks
Wrap code in fenced blocks and add a language for syntax highlighting.
```javascript
function example() {
return "Hello, World!";
}
```
````md
```javascript
function example() {
return "Hello, World!";
}
```
````
## Blockquotes
Quote text with `>`, spanning multiple lines as needed.
> This is a blockquote
>
> It can span multiple lines
```md
> This is a blockquote
>
> It can span multiple lines
```
## Tables
We support standard GitHub-flavored Markdown tables.
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
```md
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
```
For alignment, escaping pipe characters, and best practices, see [Tables](/products/docs/components/tables).
## Task Lists
Track work with checkboxes using `- [ ]` for open items and `- [x]` for completed ones.
* [x] Completed task
* [ ] Pending task
* [ ] Another pending task
```md
- [x] Completed task
- [ ] Pending task
- [ ] Another pending task
```
## Hints
We support GitHub-style alerts for highlighting important information.
Useful information that users should know, even when skimming content.
Helpful advice for doing things better or more easily.
Key information users need to know to achieve their goal.
Urgent info that needs immediate user attention to avoid problems.
Advises about risks or negative outcomes of certain actions.
```md
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
# Buttons
Buttons are interactive elements that link to external resources or other pages. Each button can include an icon and, by default, opens links in a new tab.
## Properties
| Prop | Type | Default | Description |
| --------- | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | `string` | _required_ | The label shown on the button. |
| `href` | `string` | _required_ | The URL the button links to. |
| `icon` | `string` | — | Icon shown before the label. Accepts a built-in [icon key](/products/docs/components/icons#built-in-icons) (Phosphor or Simple Icons) or a [custom URL](/products/docs/components/icons#custom-icons). |
| `variant` | `'primary'` `'secondary'` | `primary` | Visual style of the button. |
| `target` | `'_blank'` `'_self'` | `_blank` | Where the link opens. `_blank` adds `rel="noopener noreferrer"` automatically. |
## Examples
### Basic Button
[View Documentation](https://docs.scalar.com)
```md Markdown