CustomizeCustom Scripts

Custom Scripts

Add custom JavaScript snippets to your documentation site for analytics, widgets, or any custom functionality not covered by built-in integrations.

Inject custom JavaScript into your published documentation site. Use custom scripts for analytics providers not covered by built-in integrations, consent banners, A/B testing tools, or any custom functionality.

Prerequisites

  • A documentation project with publishing access

  • A .js or .mjs script file added to your documentation project

Configure custom scripts from the Editor

You can manage custom scripts directly from the Editor without editing JSON.

Open Site Config

In the Editor, click Site Config in the top toolbar.

Navigate to Custom Scripts

Select Custom Scripts from the left sidebar.

Add a script

Click Add Script and select the script file from your project. Only .js and .mjs files are available for selection.

Publish

Click Publish to deploy the script to your live site. Custom script changes appear in the Changes panel alongside content edits.

Configure custom scripts via documentation.json

If you manage configuration in version control, add scripts directly to documentation.json:

{
  "scripts": [
    { "src": "scripts/consent-banner.js" },
    { "src": "scripts/custom-tracking.mjs" }
  ]
}

Each entry in the scripts array supports the following properties:

PropertyTypeRequiredDescription
srcstringYesRelative file path to a .js or .mjs file in your project, or an external URL
categorystringNoConsent category name matching a key in integrations.cookies. Defaults to essential (always loads). See Cookie Consent.

Script file requirements

  • Files must use a .js or .mjs extension.
  • Paths are relative to your project root (for example, scripts/analytics.js).
  • Maximum file size is 5 MB.
  • The file must exist in your documentation project before you can reference it.
  • External URLs must use HTTPS.

Script paths must be relative — no leading /, ./, or ../. Path traversal patterns are rejected for security.

External scripts

You can also reference scripts hosted on external CDNs or third-party services:

{
  "scripts": [
    { "src": "https://cdn.example.com/widget.js", "category": "marketing" }
  ]
}

External URLs must use HTTPS. The same category consent gating applies to external scripts.

When you configure cookie consent categories in your integrations.cookies settings, scripts respect the following rules:

ScenarioBehavior
Script has category: "essential" or no category setAlways loads regardless of consent state
Script category matches a configured consent categoryLoads only after the user grants consent for that category
Script category is not defined in integrations.cookiesLoads by default (only explicitly configured categories are gated)
User revokes consent after granting itScript stops loading on subsequent page navigations

Scripts react to consent changes in real time. If a user updates their cookie preferences, gated scripts load or stop loading without requiring a full page refresh.

If you want a script to always run regardless of consent settings, either set its category to "essential" or omit the category field entirely.

Loading behavior

Custom scripts load using a non-blocking strategy after the page becomes interactive. This means:

  • Scripts do not block initial page rendering or content display
  • Scripts execute after the main document content loads and hydrates
  • Multiple scripts load in the order defined in the scripts array
  • Local scripts are served from a secure CDN with aggressive caching (30-day TTL)

This ensures your documentation pages remain fast for readers even when multiple custom scripts are configured.

Security considerations

Custom scripts execute in your readers' browsers with full page access.

  • Only add scripts you trust and have reviewed.

  • Audit script contents periodically, especially if they interact with user data or external services.

Malicious or misconfigured scripts can break your documentation site or compromise reader privacy. Test scripts in a staging environment before publishing to production.

Troubleshooting

Script not loading: Verify the file exists in your project and uses a .js or .mjs extension. Check the browser developer console for syntax errors.

Script conflicts: If multiple scripts interfere with each other, try reordering them in the scripts array. Scripts load in the order they appear in the configuration.

Changes not visible: Custom script changes require publishing. Check that you have published after making edits.

What's next

Was this page helpful?