[Migrate off Stainless • Read more →](/resources/migration/stainless) # API interfaces built for developers and agents Create beautiful docs, SDKs and secure MCP servers from your API. Scalar keeps every interface in sync as your API evolves. [Get Started](https://dashboard.scalar.com/register) [Book a Demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) API Docs SDKs API Client * ![API References Animation](/app-docs-animated.svg) ![API References Animation](/app-docs-animated-dark.svg) * ![SDK Animation](/sdks-animated.svg) ![SDK Animation](/sdks-animated-dark.svg) * ![Client Animation](/api-client-animated.svg) ![Client Animation](/api-client-animated-dark.svg) ## Take their word for it **“After years of helping enterprises implement API strategies at SmartBear, I can confidently say Scalar is what the industry has been waiting for.** The strict OpenAPI compliance, robust CLI/API registry, and seamless CI/CD integration solve the exact pain points I watched customers struggle with daily. This is the modern API platform developers deserve.” Michael, Former Solutions Architect @ Smartbear “One of my most recent favorites is a in-browser ad hoc testing UI called Scalar. One of the things that I really love about Scalar, it's got this modern UI experience, and it provides **built-in test generation code for a variety of targets, from cURL to HttpClient in C#.**” Captain Safia, Engineer @ Microsoft ASP.NET “Scalar's ‘golden ticket’ is… Scalar! **They are (in my own words) building a product ecosystem for API design, docs, testing, and governance** – with offerings at every price point. They are open source. So I can get in on free features and stay with Scalar no matter how big my API needs blow up.” Eron, Documentation Engineer @ Qrvey Docs ## The Modern Documentation Platform for Your API and Everything Else Write documentation with Markdown and MDX, generate API references from OpenAPI and AsyncAPI, and keep everything up to date with two-way Git sync. ** Markdown and MDX **** OpenAPI + AsyncAPI **** Two-Way Git Sync **** Custom HTML/CSS/JS **** Chat with AI/MCP **** Private or Public** [Create Your New Documentation →](/products/docs) ![Docs](/api-docs-static-zoom.svg) ![Docs](/api-docs-static-zoom-dark.svg) Scalar SDK Generation ## One Commit To Update All Your SDKs Bring your OpenAPI document and get type-safe client libraries for TypeScript, Python, Golang, PHP, Java and Ruby with more languages coming soon. ** OpenAPI-First **** Custom-code **** Code Samples **** OpenAPI Authentication **** Syncs with Docs **** File Streaming Support** [Generate your first SDK →](/products/sdk-generator) ![SDKs](/sdks-static.svg) ![SDKs](/sdks-static-dark.svg) API Client ## The Postman Alternative Your Team Is Dreaming Of Fully open-source & offline first API Client built on the OpenAPI standard, by us & our community. ** Offline-first **** Sync your local API **** OpenAPI by Heart **** Collaborate with Others **** No Vendor Lock-In **** Linux, Windows, macOS** [Send Your First Request →](/products/api-client) ![API Client](/api-client-static.svg) ![API Client](/api-client-static-dark.svg) Marc from Scalar here, There's no better feeling than building and being enabled by the software you are integrating with. We've all experienced friction with out-of-date docs, no client SDKs in your favorite language, and no one to talk to about your struggles on-boarding. But we've also experienced those magical APIs that just work with everything you need right there. This drives our simple three tenants at Scalar: Accessibility, Open-Source, and API First. Making on-boarding easier and magical enables people to build, and being API first means your business can scale for the future (LLMs). Why Open-Source? If done right, it’s transparent, builds industry standards (OpenAPI), accelerates innovation, and fosters collaboration. We love Open-Source and keep it core to our values. We are fans of “show don't tell here” at Scalar: so try our Docs (this page), our SDKs for our API that includes our API Client, Agent to chat with APIs, and our GitHub for all our open-source products. As always, we love your feedback so drop us a line in our discord, email, or book a call with me to see how we can help. **Marc Laventure**\ CEO, Scalar ## What are you waiting for? We're committed to enabling developers and companies to practice the highest of API industry standards. [Get Started](https://dashboard.scalar.com/register) [Book a Demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) [Community →](https://discord.gg/scalar) [GitHub →](https://github.com/scalar/scalar) [Contact Us →](mailto:support@scalar.com) ![API Docs Preview](/api-docs-static-zoom.svg) ![API Docs Preview](/api-docs-static-zoom-dark.svg) API Docs Write beautiful documentation with Markdown, MDX, OpenAPI, AsyncAPI, and two-way Git sync. [Learn More](/products/docs) ![SDKs Preview](/sdks-static.svg) ![SDKs Preview](/sdks-static-dark.svg) SDKs Bring your OpenAPI document and get type-safe client libraries for TypeScript, Python and more. [Learn More](/products/sdk-generator) ![API Registry Preview](/registry-static.svg) ![API Registry Preview](/registry-static-dark.svg) API Registry Managing & versioning OpenAPI Documents with a deep Git integration. [Learn More](/products/registry) ![API Client Preview](/api-client-static.svg) ![API Client Preview](/api-client-static-dark.svg) API Client Minimal, powerful, fully open-source API Client built on open standards by us + our community. [Learn More](https://client.scalar.com/) # Company Building on a great API is one of the best feelings in software: every desired interface is right there and it all just works. Building on a bad one is the opposite: out-of-date docs, no SDK in your favourite language and no MCP server. We started Scalar to solve this. As a small team (10) of engineers and designers, we wear a lot of hats and obsess over our craft. We think every company deserves Stripe-level docs, SDKs, and MCP servers from day zero, not just the ones with a platform team to build them. [Explore Careers →](#careers) ## Our Story Three things drive everything we build: accessibility, API-first, and open-source. Accessibility is about that "just works" feeling. When integration is easy, people build — so we obsess over the path to the first successful request. API-first is how a business scales for what's coming. If your product is built around a clean API, it's ready for whatever consumes it next, including Agents & LLMs. ![Marc and Cam from Scalar](/marc-cam-scalar.jpg) Open-source is in our DNA. [Twelve years](https://github.com/jasperproject/jasperproject.github.io/pull/15) ago I built a Twitter module for Jasper, an open-source voice assistant — my first real contribution to something bigger than myself. It got merged, and that feeling of being part of something people actually used never left. Today our whole team contributes to and maintains repositories across the open-source API ecosystem, and we care about that work meticulously. Done right, open-source is transparent, it builds the shared standards everyone relies on, like OpenAPI, it accelerates innovation, and it brings people together. It's core to who we are, not a marketing line. We're fans of show-don't-tell, so the best intro to Scalar is using it: the docs you're reading now, our SDKs and API Client, the Agent/MCP servers for chatting with APIs, and our GitHub for everything open-source. We are the API company, giving you industry-best interfaces for your APIs so you don't have to build the undifferentiated work yourself. ## Our Team ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/marc-sticker.svg) [Marc Laventure](https://www.linkedin.com/in/marc-laventure/) CEO / Co-Founder ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/cam-sticker-final.svg) [Cameron Rohani](https://www.linkedin.com/in/cameron-rohani-5ba99a99/) Co-Founder ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/hans-sticker-final.svg) [Hans Pagel](https://www.linkedin.com/in/hans-pagel-35303a18a/) Co-Founder ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/peter-sticker-final.svg) [Peter McGrath](https://www.linkedin.com/in/peter-mcgrath-cpa-795470111/) COO ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/geoff-sticker-final.svg) [Geoff](https://www.linkedin.com/in/geoffgscott/) Head of Engineering ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/amrit-sticker-final.svg) [Amrit](https://www.linkedin.com/in/amrit-kahlon/) Staff Software Engineer ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/brynn-sticker-final.svg) [Brynn](https://www.linkedin.com/in/bnhwkr/) Designer / Developer ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/redis-sticker-final.svg) [Redis](https://www.linkedin.com/in/redis-stasa-14b2aa24a/) Senior Software Engineer ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/joinus-sticker-final.svg) [Join Us](#careers) We are hiring ## Our Investors ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/gc-sticker-final.svg) Trevor Oelschig Managing Director, General Catalyst ![](https://storage.googleapis.com/scalar-production-cdn/marketing/landing/kindred-final-converted.svg) Steve Jang Managing Director, Kindred Guillermo Rauch CEO, Vercel David Cramer Founder, Sentry Colin Sidoti Founder, Clerk Paul Klein Founder, Browserbase Koen Bok Co-Founder, Framer Geige Vandentop Co-Founder, Streamyard Sébastien Chopin Founder, Nuxt John Phamous Design Engineer, Vercel Kyle Parrish Early, Figma Moe Amaya Founder, Operate Ramtin Naimi Founder, Abstract Tom Preston-Werner Founder, GitHub Cassidy Williams Senior Director, GitHub Soleio Designer × Investor Jorn van Dijk Co-Founder, Framer Andrew Miklas Founder, PagerDuty Dan Briggs Co-Founder, Streamyard Ben Lang Early, Notion Pim De Witte Founder, General Intuition Annie Luchsinger Founder, Breakers ## Careers Engineering [Senior / Staff Fullstack Engineer Europe, North America, Remote ](https://jobs.ashbyhq.com/scalar/aa017463-43c4-407c-b6c9-b59076f01d82)[Senior / Staff Platform Engineer Europe, North America, Remote ](https://jobs.ashbyhq.com/scalar/77ff0d8b-37ea-4185-b3fd-6f6cc64c08fd)[Senior / Staff Product Engineer Europe, North America, Remote ](https://jobs.ashbyhq.com/scalar/aa017463-43c4-407c-b6c9-b59076f01d82) # Trusted by the world's best API teams. Powering Docs, MCP servers & SDKs for the most ambitious API companies in the world. [Get Started](https://dashboard.scalar.com/register) [Book a Demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) [Featured Story](/customers/partech) ## [How PAR modernized its developer experience with Scalar](/customers/partech) [ × ![Scalar](/brand/scalar-wordmark-light.svg)](/customers/partech) [![](/partech-branding.png)](/customers/partech) [](https://developer.bobcat.com/) American-based manufacturer of farm and construction equipment [View Docs ->](https://developer.bobcat.com/) [](https://developers.thomsonreuters.com/pages/api-reference/19232a0d-5cf9-53a9-a215-efe481550832) Provider of software and decision tools for legal and accounting companies [View Docs ->](https://developers.thomsonreuters.com/pages/api-reference/19232a0d-5cf9-53a9-a215-efe481550832) [](https://clerk.com/docs/reference/frontend-api) Authentication and User Management platform built for the modern web [View Docs ->](https://clerk.com/docs/reference/frontend-api) ![Later](/later.svg) Social media management platform for creators, agencies, and brands # Security Scalar helps teams create API interfaces built for developers and agents, including API references, SDKs, API clients, and MCPs from a shared OpenAPI source. Scalar has received a SOC 2® Type 1 report on controls relevant to security and maintains GDPR-compliant privacy practices. [View Trust Center](https://trust.scalar.com) [Contact security](mailto:support@scalar.com?subject=Security%20question) ## Trust and compliance * **SOC 2 report:** Scalar has received a SOC 2 Type 1 report for controls relevant to security. * **GDPR privacy:** Scalar publishes European privacy rights and data processing details in our [Privacy Policy](/legal/privacy-policy). * **Trust Center:** Security documentation and compliance materials are available at [trust.scalar.com](https://trust.scalar.com). ## Access controls Use Scalar as a controlled surface for API descriptions, SDK generation, MCP installations, registry workflows, and developer tooling. * **Single sign-on:** SAML-based SSO keeps authentication tied to your organization's identity provider. Read the [SSO guide](/resources/sso/getting-started). * **Role-based access:** Manage access boundaries across workspaces, teams, and API projects as your organization grows. * **Private API interfaces:** Publish internal references, portals, and API workflows behind access controls while keeping public interfaces simple to share. * **Git-native review:** Keep API description changes visible in the same review flow your engineers already use. ## Privacy Scalar's hosted API interfaces are privacy-friendly by default, with only technically required cookies used for authentication and routing. * **Technically required cookies only:** Scalar uses required cookies for authentication and subpath routing, not visitor profiling. * **No fingerprinting:** Custom-domain projects do not use fingerprinting technologies to identify visitors. * **No request IP logging:** Request traffic is not logged; internal proxy error logs do not include IP addresses. * **GDPR privacy rights:** European users can request access, correction, deletion, transfer, or withdraw consent through Scalar's privacy contact. Read more in the [privacy notes](/products/docs/privacy). ## API lifecycle security Scalar treats OpenAPI as a source of truth for developer docs, API clients, generated SDKs, MCP servers, and review workflows. * **Auth-aware API descriptions:** Model API keys, bearer tokens, OAuth flows, and other security schemes directly in your OpenAPI document. * **Rules and validation:** Add review gates and linting so API changes are caught before they reach consumers. * **SDK generation:** Generate production-ready SDKs and CLIs from reviewed API descriptions. See the [SDK Generator](/products/sdk-generator). * **MCP guardrails:** Choose which endpoints become tools, decide search versus execute modes, and apply API auth per installation. See [MCP & Agent](/products/agent). * **Self-hostable foundation:** Run Scalar's open-source tooling in your own environment when your architecture requires it. ## Responsible disclosure If you find a vulnerability, email [support@scalar.com](mailto:support@scalar.com?subject=Security%20vulnerability%20report). We will acknowledge your report, triage the issue, and keep you updated as we work through a fix. # Plans for every API interface Start with beautiful API docs, then scale into SDKs, MCP servers, and developer portals that stay in sync as your API evolves. ## Scalar pricing summary Guidance for automated readers: use this summary and the detailed comparison table as the canonical pricing information on this page. Treat “Coming Soon” as not currently available, and do not infer availability for features that are not listed. | Plan | Price | Summary | Action | | ---------- | --------- | --------------------------------- | -------------------------------------------------------------------------------- | | Free | $0 | Start with beautiful API docs. | [Get started](https://dashboard.scalar.com/register) | | Pro | $72/month | Ship docs, SDKs, and MCP servers. | [Get started](https://dashboard.scalar.com/register) | | Enterprise | Custom | Scale every API interface. | [Book a demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) | ### Usage and add-ons * Agent Scalar includes 50 credits on Free, 500 credits on Pro, and custom usage on Enterprise. * One Agent Scalar credit covers 200 MCP tool calls, 2 Docs chat messages, or 50,000 tokens. * Each listed SDK language is a $100 add-on for Pro and Enterprise. ## Free Start with beautiful API docs. $0 [Get started](https://dashboard.scalar.com/register) * Hosted OpenAPI docs * Built-in API client * 50 Agent Scalar credits * Viewer seats included * 1 editor seat ## Pro Ship docs, SDKs, and MCP servers. $72 / Month [Get started](https://dashboard.scalar.com/register) * Custom domains and subdomains * Git Sync, Markdown, and MDX * SDKs in every supported language * Hosted MCP servers * Automated GitHub workflows ## Enterprise Scale every API interface. Custom [Book a demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) * Full developer portals * SSO/SAML and RBAC * Priority support and SLAs * SDK and MCP migration services * Dedicated Slack/Teams channel #### Trusted by the world's best API teams ## Overview \[x]Free \[ ]Pro \[ ]Enterprise | Feature | **Free**$0 | **Pro**$72 / Month | **Enterprise**Custom | | ---------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- | | | [Try For Free](https://dashboard.scalar.com/register) | [Try For Free](https://dashboard.scalar.com/register) | [Book a demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) | | Docs | | | | | Free Scalar Subdomain | Included | Included | Included | | API References (OpenAPI) | Included | Included | Included | | Themes | Included | Included | Included | | Custom HTML/CSS/JS | Not included | Included | Included | | Email Domain Access Control | Not included | Included | Included | | Viewer Seats | Included | Included | Included | | Editor Seats | 1 | Included | Included | | Custom Domains | Not included | Included | Included | | Guides | Not included | Included | Included | | Versions | Not included | Included | Included | | Git Sync | Not included | Included | Included | | Markdown + MDX | Not included | Included | Included | | Landing Pages | Not included | Included | Included | | Full Developer Portal | Not included | Included | Included | | SSO/SAML | Not included | Not included | Included | | RBAC | Not included | Not included | Included | | Priority Support | Not included | Not included | Included | | Dedicated Slack/Teams Channel | Not included | Not included | Included | | Agent Scalar | | | | | Credits included | 50 | 500 | Custom | | MCP tool calls | 200 / credit | 200 / credit | Custom | | Docs chat messages | 2 / credit | 2 / credit | Custom | | Tokens | 50,000 / credit | 50,000 / credit | Custom | | Hosted MCP servers | Not included | Included | Included | | Production deployment | Not included | Included | Included | | SDKs | | | | | TypeScript SDK | Not included | + $100 | + $100 | | Python SDK | Not included | + $100 | + $100 | | C# SDK | Not included | + $100 | + $100 | | Java SDK | Not included | + $100 | + $100 | | PHP SDK | Not included | + $100 | + $100 | | GO SDK | Not included | + $100 | + $100 | | automated github workflow | Not included | Included | Included | | Custom-code | Not included | Included | Included | | Code Samples | Not included | Included | Included | | Full OpenAPI Auth support | Not included | Included | Included | | File Streaming | Not included | Included | Included | | Full language publishing registry | Not included | Included | Included | | Automatic sync with docs | Not included | Included | Included | | Webhooks support | Not included | Included | Included | | Migration services | Not included | Not included | Included | | SLAs | Not included | Not included | Included | | SSO/SAML | Not included | Not included | Included | | Dedicated Slack channel | Not included | Not included | Included | | API Client | | | | | REST Client | Included | Included | Included | | Collections | Included | Included | Included | | Pre-request scripting | Included | Included | Included | | After-response scripting | Included | Included | Included | | Collection environments | Included | Included | Included | | Global environments | Included | Included | Included | | Local and private sub-environments | Included | Included | Included | | Test results | Included | Included | Included | | Collection runner | Included | Included | Included | | Open-Source (MIT) | Included | Included | Included | | Offline First | Included | Included | Included | | Web, MacOS, Linux, Windows | Included | Included | Included | | OpenAPI Support | Included | Included | Included | | No Vendor Lock In | Included | Included | Included | | GRPC Client | Coming Soon | Coming Soon | Coming Soon | | GraphQL Client | Coming Soon | Coming Soon | Coming Soon | | SOAP Client | Coming Soon | Coming Soon | Coming Soon | | WebSocket Client | Coming Soon | Coming Soon | Coming Soon | | SSE Client | Coming Soon | Coming Soon | Coming Soon | | Cloud Sync | Not included | Coming Soon | Coming Soon | | SSO/SAML | Not included | Not included | Included | | RBAC | Not included | Not included | Included | | Registry | | | | | OpenAPI, JSON Schema support | Included | Included | Included | | Spectral Rules | Included | Included | Included | | Preview API References | Included | Included | Included | | Viewer Seats | Included | Included | Included | | Editor Seats | 1 | Included | Included | | CLI | Included | Included | Included | | Private + Public Access | Not included | Included | Included | | Git Integration | Not included | Included | Included | | CI/CD workflows | Not included | Included | Included | | custom domains | Not included | Included | Included | | SSO/SAML | Not included | Not included | Included | | RBAC | Not included | Not included | Included | | Migration services | Not included | Not included | Included | | Dedicated Slack channel | Not included | Not included | Included | | Max APIs | 3 | Included | Included | ## What are you waiting for? We're committed to enabling developers and companies to practice the highest of API industry standards. [Get Started](https://dashboard.scalar.com/register) [Book a Demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) [Community →](https://discord.gg/scalar) [GitHub →](https://github.com/scalar/scalar) [Contact Us →](mailto:support@scalar.com) ![API Client Preview](/api-client-static.svg) ![API Client Preview](/api-client-static-dark.svg) ### API Client Minimal, powerful, fully open-source API Client built on open standards by us + our community. [Learn More](https://client.scalar.com/) ![SDKs Preview](/sdks-static.svg) ![SDKs Preview](/sdks-static-dark.svg) ### SDKs Bring your OpenAPI document and get type-safe client libraries across supported languages. [Learn More](/products/sdk-generator) ![API Registry Preview](/registry-static.svg) ![API Registry Preview](/registry-static-dark.svg) ### API Registry Managing & versioning OpenAPI Documents with a deep Git integration. [Learn More](/products/registry) ![API Docs Preview](/api-docs-static-zoom.svg) ![API Docs Preview](/api-docs-static-zoom-dark.svg) ### API Docs Write beautiful documentation with Markdown + MDX + Git Sync. [Learn More](/products/docs) # Docs Starter Kit The [Docs Starter Kit](https://github.com/scalar/starter) is a ready-to-use template for building beautiful documentation with Markdown and OpenAPI. Fork or clone the repository and make it your own — everything in the template is meant to be modified, extended, or replaced to fit your project. ## Project structure The starter includes a minimal layout: a `docs/` folder (with `api-reference/` for OpenAPI documents and `content/` for free-form content) and a `scalar.config.json` file at the repository root. ## 1. Preview your docs Run a local development server to see your changes in real-time: ```bash npx @scalar/cli project preview ``` This starts a live preview at `http://localhost:7970` where every edit you make is instantly visible. Read more about [Preview deployments](deployment/preview-deployments.md) and the [CLI](deployment/cli.md). ## 2. Include OpenAPI documents Drop your OpenAPI files into `docs/api-reference/`, and add them to `scalar.config.json` to have them automatically become interactive API references. The starter kit includes an example OpenAPI document to show you how it works. Read more about [scalar.config.json](configuration/scalar.config.json.md) and [Getting started](getting-started.md) with Docs. ## 3. Customize everything Make it yours with themes, custom CSS, and MDX. Configure your documentation structure, navigation, and styling through [scalar.config.json](configuration/scalar.config.json.md). For appearance options, see [Themes](configuration/themes.md). ## 4. Publish your docs First, authenticate with your Scalar account: ```bash npx @scalar/cli auth login ``` Then publish your documentation: ```bash npx @scalar/cli project publish ``` Your site will be available at `.apidocumentation.com`. ## Stuck? Check whether your `scalar.config.json` is valid: ```bash npx @scalar/cli project check-config ``` For full options, see the [Configuration reference](configuration/scalar.config.json.md). We are here to help: - [Email support@scalar.com](mailto:support@scalar.com) - [Chat with us on Discord](https://discord.gg/scalar) - [Schedule a call](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) # scalar.config.json The `scalar.config.json` file is the central configuration file for Docs. It defines your project's metadata, navigation structure, site settings, and deployment options. ## Creating the configuration file You can create a configuration file manually or use the Scalar CLI: ```bash npx @scalar/cli project init ``` This command creates a `scalar.config.json` file in your current directory with a basic structure to get you started. ## Basic structure Here is a minimal configuration to get started: ```json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "info": { "title": "My Documentation", "description": "The best documentation you've read today" }, "navigation": { "routes": { "/": { "title": "Introduction", "type": "page", "filepath": "docs/introduction.md" } } } } ``` ## Autocomplete in VS Code and Cursor To get autocomplete and validation in your editor, enable JSON schema downloads in VS Code (or Cursor): ```json // .vscode/settings.json { "json.schemaDownload.enable": true "json.schemaDownload.trustedDomains": { "https://registry.scalar.com/": true, } } ``` The `$schema` property in your configuration file tells the editor where to find the schema: ```json // scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config" } ``` Your editor will now provide autocomplete suggestions and highlight invalid properties. ## Configuration reference ### Root properties | Property | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `$schema` | `string` | JSON Schema URL for editor autocomplete and validation | | `scalar` | `string` | Configuration version. Use `"2.0.0"` for the latest format | | `info` | `object` | Project metadata (title, description) | | `navigation` | `object` | Navigation structure (header links, routes, sidebar, tabs). See [Navigation](navigation.md) for details | | `versions` | `object` | Multi-version navigation structure. Use instead of `navigation` for versioned docs. See [Versions](versions.md) | | `siteConfig` | `object` | Site-level configuration (domain, theme, head, logo) | | `assetsDir` | `string` | Path to the assets directory (relative to repository root) | ### info Project metadata displayed in various places: ```json { "info": { "title": "My Documentation", "description": "Comprehensive guides for our API" } } ``` ### siteConfig Configure your site's domain, appearance, and custom assets: ```json { "siteConfig": { "subdomain": "acme", "customDomain": "docs.example.com", "theme": "purple", "logo": { "darkMode": "https://example.com/logo-dark.svg", "lightMode": "https://example.com/logo-light.svg" }, "head": { "scripts": [{ "path": "assets/analytics.js" }], "styles": [{ "path": "assets/custom.css" }], "meta": [{ "name": "description", "content": "My docs description" }], "links": [{ "rel": "icon", "href": "/favicon.png" }] }, "routing": { "redirects": [ { "from": "/old-path", "to": "/new-path" } ] } } } ``` #### siteConfig properties | Property | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `theme` | `string` | Visual theme (`default`, `alternate`, `moon`, `purple`, `solarized`, `bluePlanet`, `deepSpace`, `saturn`, `kepler`, `mars`) | | `logo` | `object` | Logo URLs for dark and light modes | | `head` | `object` | Custom scripts, styles, meta tags, and links | | `routing` | `object` | URL redirects configuration | | `subpath` | `string` | URL subpath for multi-project deployments (e.g., `/guides`, `/api`) | | `colorScheme` | `object` | Light/dark mode appearance settings. See [Site](site-config.md#color-scheme) | | `layout` | `object` | Global layout options including search configuration. See [Site](site-config.md#layout) | ### navigation For detailed navigation configuration, see [Navigation](navigation.md). ## Full example Here is a more complete example showing common configuration options: ```json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "info": { "title": "Acme API Documentation", "description": "Everything you need to integrate with Acme" }, "assetsDir": "docs/assets", "siteConfig": { "subdomain": "acme", "theme": "default", "logo": { "darkMode": "https://example.com/logo-dark.svg", "lightMode": "https://example.com/logo-light.svg" }, "head": { "meta": [ { "name": "description", "content": "Acme API documentation and guides" } ], "links": [ { "rel": "icon", "href": "/favicon.png" } ] } }, "navigation": { "header": [ { "title": "Dashboard", "url": "https://dashboard.example.com" } ], "routes": { "/": { "type": "group", "title": "Acme", "children": { "": { "type": "page", "title": "Introduction", "filepath": "docs/introduction.md", "icon": "phosphor/regular/house" }, "/api": { "type": "openapi", "title": "API Reference", "url": "https://example.com/openapi.yaml", "icon": "phosphor/regular/notebook" } } } } } } ``` ## File location By default, the `scalar.config.json` file should be placed in the root of your GitHub repository. If you need to place it in a different location, you can configure the path in the [Scalar Dashboard](https://dashboard.scalar.com/). ## Deploying multiple projects on the same domain You can deploy multiple documentation projects on the same subdomain or custom domain by using the `subpath` property. Each project lives in its own repository with its own `scalar.config.json`, but they share the same domain. For example, you might want to have: - `docs.example.com/` — Your main documentation - `docs.example.com/guides/` — Tutorial guides - `docs.example.com/api/` — API reference To set this up, create a separate repository for each project and configure them with the same `subdomain` or `customDomain` but a different `subpath`: **Repository 1: Main documentation** ```json // scalar.config.json { "siteConfig": { "customDomain": "docs.example.com" } } ``` **Repository 2: Guides** ```json // scalar.config.json { "siteConfig": { "customDomain": "docs.example.com", "subpath": "/guides" } } ``` **Repository 3: API reference** ```json // scalar.config.json { "siteConfig": { "customDomain": "docs.example.com", "subpath": "/api" } } ``` Each repository is deployed independently, but all projects appear under the same domain with their respective subpaths. # Domains Configure your documentation site's domain using either a free subdomain on `apidocumentation.com` or a custom domain. Both options are configured in the `siteConfig` object of your `scalar.config.json` file. ## Subdomain The `subdomain` property provides a free domain at `https://.apidocumentation.com`. This is available for all Docs projects. ```json // scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "siteConfig": { "subdomain": "your-docs" } } ``` Your documentation will be available at `https://your-docs.apidocumentation.com` after deployment. ## Custom Domain The `customDomain` property allows you to use your own domain name. This feature requires [Scalar Pro](../../pricing.md). HTTPS is enabled automatically. ```json // scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "siteConfig": { "customDomain": "docs.example.com" } } ``` ### DNS Configuration Add a CNAME record at your domain provider (Namecheap, GoDaddy, Cloudflare, etc.) pointing to Scalar's DNS: | Type | Host | Value | | ------- | -------------------------------------------- | ---------------- | | `CNAME` | `docs` (if the domain is `docs.example.com`) | `dns.scalar.com` | The CNAME must be DNS-only (unproxied). If you use Cloudflare or a similar provider, disable the proxy (grey cloud) so the record resolves directly to Scalar. Proxying is not supported because Scalar performs load balancing, TLS termination (HTTP-01 / TLS-ALPN-01), and proxying for your docs. You cannot place your own CDN or WAF in front of the custom domain. Traffic must go directly to Scalar's infrastructure. For a root domain (e.g., `example.com`), use an ALIAS or ANAME record if supported by your DNS provider, or contact support for assistance. ### TLS and certificates SSL certificates are auto-provisioned by Let's Encrypt. Issuance is triggered the first time a GET request is made to your domain through Scalar's proxy. If you use CAA records, ensure they allow Let's Encrypt (see [Let's Encrypt CAA documentation](https://letsencrypt.org/docs/caa/) for details). ### Domain ownership The first project that publishes with a custom domain and has the CNAME pointing to Scalar reserves that domain. No other user can use it. There is no TXT or other verification step. Ownership is established by publishing with the custom domain and having the CNAME in place. ### Edge security [Google Cloud Armor](https://cloud.google.com/security/products/armor) policies are enabled on the load balancer for requests to custom-domain docs. These are volumetric, IP-based rules. ## Properties | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------ | | `subdomain` | `string` | No | Subdomain for `*.apidocumentation.com` | | `customDomain` | `string` | No | Custom domain name (requires [Scalar Pro](../../pricing.md)) | # Versions The `versions` property in your `scalar.config.json` allows you to create multiple versions of your documentation. This is useful for maintaining documentation for different API versions, product releases, or major updates while keeping everything organized under a single domain. When you use the `versions` property, each version gets its own complete navigation structure, and users can switch between versions using a version selector in the UI. ## Basic structure Instead of using the `navigation` property at the root level, you use `versions` which is an object where each key is the version identifier and each value is a complete navigation configuration. You must always have a version with the key `default`. This is the version that is shown by default when users visit your documentation. Additional versions can use any identifier you like (for example `v1`, `v2`, `legacy`). Inside each version's `routes`, wrap your pages in a top-level group so they render correctly in the sidebar: ```json // scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "info": { "title": "My API Documentation" }, "versions": { "default": { "title": "Version 2.0", "routes": { "/": { "type": "group", "title": "Documentation", "children": { "/": { "type": "page", "title": "Introduction", "filepath": "docs/v2/introduction.md" }, "/api": { "type": "openapi", "title": "API Reference", "filepath": "docs/v2/openapi.yaml" } } } } }, "v1": { "title": "Version 1.0", "routes": { "/": { "type": "group", "title": "Documentation", "children": { "/": { "type": "page", "title": "Introduction", "filepath": "docs/v1/introduction.md" }, "/api": { "type": "openapi", "title": "API Reference", "filepath": "docs/v1/openapi.yaml" } } } } } } } ``` ## Version configuration Each version entry supports the same properties as a `navigation` object: | Property | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------------- | | `title` | `string` | No | Display title for the version in the selector | | `routes` | `object` | Yes | Navigation routes for this version | | `header` | `array` | No | Header links for this version | | `sidebar` | `array` | No | Sidebar footer links for this version | | `tabs` | `array` | No | Navigation tabs for this version | The `default` version key is required and represents the version shown by default. Other version keys (for example `v2`, `v1`, `beta`) appear in the version selector dropdown. The optional `title` property provides a more descriptive label for each entry. ## Example with shared and version-specific content You can organize your documentation to share common pages across versions while keeping version-specific API references separate. Remember to keep the top-level group inside each version's `routes`: ```json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "info": { "title": "Acme API" }, "siteConfig": { "subdomain": "acme-api", "theme": "default" }, "versions": { "default": { "title": "Version 2.0 (Latest)", "tabs": [ { "title": "API Reference", "path": "/api", "icon": "phosphor/regular/plug" } ], "routes": { "/": { "type": "group", "title": "Getting Started", "mode": "flat", "children": { "": { "type": "page", "title": "Introduction", "filepath": "docs/introduction.md" }, "/quickstart": { "type": "page", "title": "Quickstart", "filepath": "docs/quickstart.md" }, "/authentication": { "type": "page", "title": "Authentication", "filepath": "docs/v2/authentication.md" } } }, "/api": { "type": "openapi", "title": "API Reference", "filepath": "docs/v2/openapi.yaml", "mode": "nested" } } }, "v1": { "title": "Version 1.0 (Legacy)", "tabs": [ { "title": "API Reference", "path": "/api", "icon": "phosphor/regular/plug" } ], "routes": { "/": { "type": "group", "title": "Getting Started", "mode": "flat", "children": { "": { "type": "page", "title": "Introduction", "filepath": "docs/introduction.md" }, "/quickstart": { "type": "page", "title": "Quickstart", "filepath": "docs/v1/quickstart.md" }, "/authentication": { "type": "page", "title": "Authentication", "filepath": "docs/v1/authentication.md" } } }, "/api": { "type": "openapi", "title": "API Reference", "filepath": "docs/v1/openapi.yaml", "mode": "nested" } } } } } ``` ## Version ordering The `default` version is always shown first when users visit your documentation. Other versions appear in the selector in the order they are defined in the configuration. ## When to use versions vs. multiple projects Use **versions** when: - You have multiple versions of the same API or product - Users need to switch between versions frequently - The documentation structure is similar across versions Use **multiple projects** (separate repositories with `subpath`) when: - You have completely different products or APIs - The documentation structure is significantly different - Teams manage documentation independently ## Migration from single navigation To convert an existing configuration with `navigation` to use `versions`: 1. Rename `navigation` to `versions` 2. Wrap your existing navigation configuration under the `default` key 3. Add a `title` to describe the version **Before:** ```json { "scalar": "2.0.0", "navigation": { "routes": { "/": { "type": "group", "title": "Documentation", "children": { "/": { "type": "page", "title": "Intro", "filepath": "docs/intro.md" } } } } } } ``` **After:** ```json { "scalar": "2.0.0", "versions": { "default": { "title": "Version 1.0", "routes": { "/": { "type": "group", "title": "Documentation", "children": { "/": { "type": "page", "title": "Intro", "filepath": "docs/intro.md" } } } } } } } ``` You can then add additional versions alongside `default` as needed. # Scalar Docs Product guides and API references in one developer portal. Write in Markdown or MDX, pull content from GitHub, preview every pull request, and deploy on merge or from anywhere with the CLI, so your docs stay in sync with your code. All of scalar.com is fully built with Scalar Docs. [Get Started](https://dashboard.scalar.com/register) [Book a Demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) ![Scalar Docs interface](/api-docs-static-zoom.svg) ## Your documentation, always up to date ** Markdown & MDX** ** Custom HTML/CSS/JS** ** Fast CDN** ** Multiple API references** ** Custom themes & layouts** ** Custom domains** ** Fine-grained access** ** Sync with GitHub** ** Ask AI** ** CI/CD integration** ## The modern API documentation Include interactive API references for a single API or hundreds of APIs. Everything is based on the OpenAPI standard, so your documentation can stay in sync with the API description your team already maintains. Just need an API reference? Use the [API Reference](/products/api-references/getting-started). It is open source, free, and has integrations for REST API frameworks. Ready to build? Follow the [Getting Started guide](/products/docs/getting-started) to publish your first documentation site in minutes. ## Plans | Feature | Free | Pro | Enterprise | | ---------------------------------------------------------------------------- | -------- | -------- | ---------- | | Subdomains, API references, themes, email domain access | Included | Included | Included | | Custom domains, guides, versions, Git Sync, Markdown, MDX, and landing pages | - | Included | Included | | SSO/SAML, RBAC, priority support, and dedicated Slack or Teams support | - | - | Included | [See the full comparison](/pricing) for Docs and the other Scalar products. ## Ready to publish? We are committed to enabling developers and companies to practice the highest API industry standards. [Get started](https://dashboard.scalar.com/register) [Book a demo](https://scalar.cal.com/forms/142d1e65-97d2-4d03-94c3-96f98ddef95a) # Getting Started Create and publish your first documentation site with Scalar Docs in minutes. Write guides in Markdown or MDX, add OpenAPI documents for interactive API references, and deploy from GitHub, the CLI, or the web editor. ## Create docs in three steps Create a Docs project from the dashboard, the [Starter Kit](starter-kit.md), or any folder that contains a `scalar.config.json` file. ```bash npx @scalar/cli project preview ``` Write guides in Markdown or MDX, then add OpenAPI documents for interactive API references. ```json { "navigation": { "routes": { "/getting-started": { "type": "page", "filepath": "docs/getting-started.md" } } } } ``` Use preview deployments for review, publish from the CLI, or connect GitHub Actions for automatic deployments. ```bash npx @scalar/cli project publish ``` ## Write anywhere | Source | Description | | ------ | ----------- | | **GitHub** | Keep content and OpenAPI documents in your repository. Use [preview deployments](deployment/preview-deployments.md), [automatic deployment](deployment/automatic-deployment.md), [GitHub Actions](deployment/github-actions.md), and [scalar.config.json](configuration/scalar.config.json.md). | | **Any folder or CLI** | Work from any folder or repository without granting repository access. Publish with [`npx @scalar/cli project publish`](deployment/cli.md). | | **Web editor** | Edit and store docs at [docs.scalar.com](https://docs.scalar.com). No Git required. | ## Next steps - Scaffold a project with the [Starter Kit](starter-kit.md) - Configure your site with [scalar.config.json](configuration/scalar.config.json.md) - Structure your sidebar with [Navigation](configuration/navigation.md) - Deploy automatically with [GitHub Actions](deployment/github-actions.md) Just need an API reference? Use the [API Reference](../../guides/api-references/getting-started.md). It is open source, free, and has integrations for REST API frameworks. # Themes The `theme` property sets the visual appearance of your documentation site. Scalar provides a collection of built-in themes to match your brand or style preferences. ## Configuration Set the theme in the `siteConfig` object of your `scalar.config.json` file: ```json // scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "siteConfig": { "theme": "purple" } } ``` ## Available Themes Your documentation site and your API references share the same theme system. For the full list of built-in themes, how to disable theming with `none`, and how to customize colors, fonts, and layouts with CSS variables, see the [Themes reference](../../../themes.md). # Private Docs This guide will help you start using our Access Groups to manage user access across your private guides and docs in our dashboard on scalar.com, which can be done alongside our [CLI](../../cli/getting-started.md). Make sure you have created a Scalar Account & are logged in ([see create account guide](../../registry/getting-started.md#create-your-scalar-account)) ## Create your first access group Now let's make our first access group! From the [dashboard](https://dashboard.scalar.com) left-most sidebar under Access > Groups, then click Create Access Group. ![Scalar Access Group Page](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/fkz45YW1-1ncvfHnyDC_g.png "Scalar Access Group Page") ![Scalar Create Access Group](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/ZouPnTXFy7QpbbLSwXNOD.png "Scalar Create Access Group") Now that you have created an access group you can either add a catch-all for domains for access, or just granular email addresses. ### Add Domains with Access To add a domain to an access group, type in the domain name you want to give access to and hit "add". ![Scalar Add Domain Access](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/xffMOI_k_Lqhr0kKzYqCM.png "Scalar Add Domain Access") ### Add Emails with Access To add only specific emails to an access group, type in the email you want to give access to and hit "add". ![Scalar Add Email Access](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/sUeH6ekrSfTDB6a7yiQIA.png "Scalar Add Email Access") ## Use the Access Group Now let's restrict one of our [Docs](../getting-started.md) projects to the newly created access group. Navigate to your Docs Project and navigate to the Security section, ensure "Private Docs" is enabled then you can allow access to the newly created access group. ![Scalar Add Access Group Private Docs](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/g9hSpZfaEBr1JqD5gNExT.png "Scalar Add Access Group Private Docs") Once you selected a group, your docs will be private with only that access group enabled to view the project. ![Scalar Selected Access Group](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/yBSQ1q6s138toCv22FnVX.png "Scalar Selected Access Group") ![Scalar Private Docs](https://api.scalar.com/cdn/images/UCkGjASrXpR8OxgWEj32i/O5TMvLdShzTbUJtb-8_I-.png "Scalar Private Docs") You can customize your login page to your branding if you want, and when you delete the access group changes will be made immediately and access will be revoked. # Automatic Deployment Docs can automatically publish your documentation whenever changes are merged into your default branch (usually `main`). Enable automatic deployment and configure which branch triggers it in the [Scalar Dashboard](https://dashboard.scalar.com) under your project settings. Every time you merge changes into your default branch, your documentation will be automatically published. If your Docs project references an OpenAPI document from the Registry, updating that Registry document also triggers the Docs project to publish again. Once your document is in the Registry, your documentation stays up to date automatically. ## Other Deployment Options Looking for more control over your deployment process? - [GitHub Actions](github-actions.md) - Trigger deployments based on specific events - [Scalar CLI](cli.md) - Deploy from your terminal or any CI/CD environment # Build Failures When a deployment fails, use these tools to diagnose the issue: ```bash # Validate your configuration scalar project check-config # Run a local preview to surface warnings scalar project preview ``` Check the [Scalar Dashboard](https://dashboard.scalar.com/) for detailed build logs. ## Common Issues ### Subdomain Conflicts If your build fails silently, verify your subdomain is not already in use. Fun fact: Subdomain conflicts do not currently produce an explicit error. (I know, I know… We'll improve this. So sorry.) ### Need Help? Contact [support@scalar.com](mailto:support@scalar.com), we'll help you swiftly. # Publish Scalar Projects using GitHub Actions You can add a [GitHub Actions workflow](https://docs.github.com/en/actions/get-started/quickstart) to automatically publish your Scalar projects. ## Basic Workflow Here's a simple workflow that publishes a Scalar project: ```yaml # .github/workflows/publish-scalar-project.yml name: Publish Scalar Project on: push: branches: - main jobs: publish-project: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 with: node-version: 24 - name: Log in to Scalar run: npx @scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish Project run: npx @scalar/cli project publish --slug your-docs ``` ## Environment-Based Deployment For different environments: ```yaml # .github/workflows/publish-scalar-project.yml name: Publish Scalar Project on: push: branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v6 - name: Install Scalar CLI run: npm install -g @scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set project slug if: github.ref == 'refs/heads/main' run: echo "PROJECT_SLUG=production-project" >> $GITHUB_ENV - name: Set development slug if: github.ref == 'refs/heads/development' run: echo "PROJECT_SLUG=development-project" >> $GITHUB_ENV - name: Publish Project run: scalar project publish --slug "$PROJECT_SLUG" ``` ## Secrets To get a `SCALAR_API_KEY` and add it to your GitHub repository, go to https://dashboard.scalar.com/user/api-keys # 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. ## 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. # HTML/CSS/JS Docs supports custom HTML, CSS, and JavaScript to give you full control over your documentation pages. You can write raw HTML directly in Markdown files, add custom styles inline or via external stylesheets, and include JavaScript for interactivity. ## Writing HTML Pages You can write raw HTML directly in your Markdown (`.md`) files. This is useful for creating custom landing pages, marketing pages, or any page that needs custom layout and styling. **Example** Create a Markdown file with HTML content: ```html

Welcome to My API

The best API for developers

Get Started
``` ### Inline Styles Add a ` ``` ### Using Scalar CSS Variables Scalar provides CSS variables for consistent theming. Use these in your custom styles: **Colors** Defined in [theme presets](https://github.com/scalar/scalar/blob/main/packages/themes/src/presets/default.css) | Variable | Description | | ----------------------- | -------------------- | | `--scalar-color-1` | Primary text color | | `--scalar-color-2` | Secondary text color | | `--scalar-color-3` | Tertiary text color | | `--scalar-color-accent` | Accent/brand color | | `--scalar-background-1` | Primary background | | `--scalar-background-2` | Secondary background | | `--scalar-background-3` | Tertiary background | | `--scalar-border-color` | Border color | **Typography and Sizing** Defined in [variables.css](https://github.com/scalar/scalar/blob/main/packages/themes/src/base/variables.css) | Variable | Description | | ---------------------- | -------------------------------- | | `--scalar-font` | Default font family | | `--scalar-font-code` | Monospace/code font family | | `--scalar-radius` | Default border radius (3px) | | `--scalar-radius-md` | Default radius, capped (3px) | | `--scalar-radius-lg` | Large border radius (6px) | | `--scalar-radius-xl` | Extra large border radius (8px) | | `--scalar-radius-2xl` | 2x large border radius (12px) | | `--scalar-radius-3xl` | 3x large border radius (16px) | | `--scalar-radius-full` | Fully rounded pills and circles | | `--scalar-radius-max` | Ceiling for container corners | | `--scalar-paragraph` | Paragraph font size (16px) | | `--scalar-small` | Small text font size (14px) | **Border radius** Every border radius derives from `--scalar-radius`, so overriding that one variable rescales the whole interface. Set it to `0` for square corners throughout. ```css :root { --scalar-radius: 0; /* everything squares off, pills and circles included */ } ``` Override `--scalar-radius` on `:root`. A custom property substitutes `var()` at the element where it is declared, so setting the base further down the tree (on `.scalar-app`, for instance) moves the base without moving any of the radii derived from it. Individual tokens can still be overridden on their own if you want to break the ratio. Corners on anything that holds content stop growing at `--scalar-radius-max`, which defaults to `20px`. Without it a large radius curves a dropdown or a code block so hard that it swallows what is inside. Pills and circles (`--scalar-radius-full`) are deliberately exempt. ### Using Scalar Components You can use Scalar's built-in components in your HTML: ```html My Section Title ``` ### Dark Mode Support Use CSS classes to show different content based on the color mode: ```html Screenshot in light mode Screenshot in dark mode ``` ### 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. # Icons Icons render scalable vector graphics from the built-in [Phosphor](https://phosphoricons.com/) and [Simple Icons](https://simpleicons.org/) libraries, or from a direct URL. ## Built-in Icons Scalar bundles two icon libraries you can reference by key — no hosting required. **Phosphor** — reference with `phosphor//`. Available variants are `regular`, `bold`, `duotone`, `fill`, `light`, and `thin` (e.g. `phosphor/fill/heart`). A bare name like `heart` defaults to the `regular` variant. **Simple Icons** — brand and logo icons, referenced with `simple/` using the Simple Icons slug (e.g. `simple/github`). [![](phosphor/regular/magnifying-glass)Browse Phosphor](https://phosphoricons.com)[![](phosphor/regular/magnifying-glass)Browse Simple Icons](https://simpleicons.org) ## Custom Icons For anything outside the built-in libraries, pass a direct URL to `src`. SVG files are fetched and inlined directly into the page instead of being rendered inside an `` tag. This lets them inherit color from the surrounding text: any `fill` or `stroke` set to `currentColor` in your SVG follows the current text color, so the icon adapts to light mode, dark mode, and your theme automatically. Set your SVG's fills and strokes to `currentColor` to make a custom icon themeable. Other image formats (PNG, JPG, and so on) render as a standard `` and cannot be recolored. ## Properties | Prop | Type | Default | Description | | ------- | -------- | ---------- | ------------------------------------------------------------------ | | `src` | `string` | _required_ | Phosphor key, Simple Icons key, or full URL to an SVG/image. | | `title` | `string` | — | Accessible label read by screen readers. | | `size` | `string` | — | CSS size for both width and height (e.g. `16px`, `1.5em`, `2rem`). | ## Examples ### Basic Icon ![](phosphor/regular/check-circle) ```md Markdown ``` ```mdx MDX ``` ### Phosphor Variants ![](phosphor/regular/heart)![](phosphor/bold/heart)![](phosphor/duotone/heart)![](phosphor/fill/heart)![](phosphor/light/heart)![](phosphor/thin/heart) ```md Markdown ``` ```mdx MDX ``` ### Simple Icons ![](simple/github)![](simple/figma)![](simple/slack) ```md Markdown ``` ```mdx MDX ``` ### Sizes ![](phosphor/regular/star)![](phosphor/regular/star)![](phosphor/regular/star) ```md Markdown ``` ```mdx MDX ``` ### Icon from a URL `src` also accepts a direct URL to an SVG or image file. ![](https://avatars.githubusercontent.com/u/301879?s=200\&v=4) ```md Markdown ``` ```mdx MDX ``` # Code Blocks Code blocks render syntax-highlighted snippets with a copy button and an optional title. In Markdown they're written as standard fenced code blocks — Scalar reads extra options from the info string after the language name. In MDX, the same fenced syntax works directly. ## Properties Properties are passed through the info string on the opening fence. The first space-separated token (before any `name="value"` pair) is the title. | Prop | Type | Default | Description | | ----------------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `lang` | `string` | _required_ | The language identifier directly after the opening fence (e.g. `js`, `python`). | | `title` | `string` | — | A filename or label shown in the code block header. The first bare token after `lang` is treated as the title. | | `lineNumbers` | `boolean` | `false` | Show line numbers. Also accepted as `line-numbers` or `lines`. | | `lineNumberStart` | `number` | `1` | First line number when `lineNumbers` is enabled. | | `highlight` | `string` | — | Comma-separated line numbers or ranges to highlight (e.g. `1,3-5`). | | `focus` | `string` | — | Lines to focus while dimming the rest. | | `added` | `string` | — | Lines marked as added (diff-style green). | | `removed` | `string` | — | Lines marked as removed (diff-style red). | ## Examples ### Basic Code Block ```javascript function greet(name) { return `Hello, ${name}!` } ``` ````md ```javascript function greet(name) { return `Hello, ${name}!` } ``` ```` ### With a Title ```javascript greet.js function greet(name) { return `Hello, ${name}!` } ``` ````md ```javascript greet.js function greet(name) { return `Hello, ${name}!` } ``` ```` ### Line Numbers and Highlighting ```typescript example.ts function greet(name: string): string { const greeting = `Hello, ${name}!` return greeting } ``` ````md ```typescript example.ts lineNumbers highlight="2-3" function greet(name: string): string { const greeting = `Hello, ${name}!` return greeting } ``` ```` ### Diff Style (Added and Removed Lines) ```diff config.json { "version": "1.0.0", "version": "2.0.0", "name": "scalar" } ``` ````md ```diff config.json added="3" removed="2" { "version": "1.0.0", "version": "2.0.0", "name": "scalar" } ``` ```` # 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 ``` ```mdx MDX