Generating Scalar

How API References Are Rendered

A topic generated from an OpenAPI file contains a single ScalarApiReference node. The renderer turns that node into an interactive Scalar API reference. The node carries only the location of the spec:

[
  "ScalarApiReference", 
  { 
    "specUrl": "swagger/data-store.openapi.yaml", 
    "format": "application/yaml" 
  }
]

specUrl is relative to the topic's own directory in the data store. Settings are not stored in the topic; every API reference on the site reads the same scalar.json.

Editing the Settings

Edit scalar.json in the root of the data store directory (next to chrome.json). It is a flat JSON object of Scalar configuration options:

{
  "layout": "modern",
  "hideClientButton": true,
  "hideSearch": true,
  "defaultOpenAllTags": true,
  "hiddenClients": ["go", "java", "php", "ruby"]
}

The data store serves the file as a static asset at /data/scalar.json and the browser reads it each time an API reference loads. Reload the page to see a change; there is no rebuild. If the file is missing, the renderer falls back to hideClientButton: true and withDefaultFonts: false.

Important: There is no transtype or REST endpoint for scalar.json. If you refresh the data store with rsync --delete, the file is removed unless it is part of the source directory or excluded with --exclude=scalar.json.

Commonly Changed Options

layout

modern (two columns, operations expanded) or classic (operations as collapsed cards).

showSidebar, hideSearch

Show or hide Scalar's own sidebar and search. The application already provides a table of contents, so both are normally off. The sidebar cannot start collapsed; it is either shown or hidden.

showToolbar, showDeveloperTools

always, localhost or never.

defaultOpenAllTags, defaultOpenFirstTag

Control which tag groups start expanded.

hiddenClients

Language targets to remove from the Client Libraries list. Entries may be a target such as node, a client such as fetch, or a full id such as node/fetch.

documentDownloadType

both, yaml, json, direct or none.

localization

Override individual interface strings under translations. For example, to shorten the download link label:

{ "localization": 
  { "translations": 
    { "download": 
      { "openapi": "Download" } 
    } 
  } 
}

Overrides merge over every built-in language, so the same text appears for all locales.

Settings the Renderer Controls

A few settings are applied by the renderer after scalar.json is read, so values in the file have no effect:

url — always resolved from the node's specUrl.
forceDarkModeState — follows the application's light/dark switch. Scalar's own toggle is not shown, and the API reference reloads when the theme changes.
localization.locale — taken from the topic language, so a German topic renders Scalar in German. Scalar includes English, Russian, Spanish, French, German, Chinese (Simplified), Arabic and Portuguese.