> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/site-customization.md).

# Site customization

Update your site's branding, styling, and layout to match your organization's identity. This includes theming elements like color palette, logos, and more.

## The SiteCustomizationSettings object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"SiteCustomizationSettings":{"allOf":[{"$ref":"#/components/schemas/SiteCustomizationSettingsBase"},{"type":"object","properties":{"updatedAt":{"description":"When the customization settings were updated. If missing, customization was not updated.","$ref":"#/components/schemas/Timestamp"}}}]},"SiteCustomizationSettingsBase":{"type":"object","properties":{"title":{"description":"Title to use for the published site. If not defined, it'll fallback to the default content title.","$ref":"#/components/schemas/SiteTitle"},"localizedTitle":{"description":"Localized titles for the site, keyed by locale. If not defined, the localized title will not be changed.","$ref":"#/components/schemas/LocalizedString128"},"styling":{"type":"object","properties":{"theme":{"$ref":"#/components/schemas/CustomizationTheme"},"primaryColor":{"$ref":"#/components/schemas/CustomizationThemedColor"},"tint":{"$ref":"#/components/schemas/CustomizationTint"},"infoColor":{"$ref":"#/components/schemas/CustomizationThemedColor"},"successColor":{"$ref":"#/components/schemas/CustomizationThemedColor"},"warningColor":{"$ref":"#/components/schemas/CustomizationThemedColor"},"dangerColor":{"$ref":"#/components/schemas/CustomizationThemedColor"},"corners":{"$ref":"#/components/schemas/CustomizationCorners"},"depth":{"$ref":"#/components/schemas/CustomizationDepth"},"links":{"$ref":"#/components/schemas/CustomizationLinksStyle"},"font":{"$ref":"#/components/schemas/CustomizationFont"},"monospaceFont":{"$ref":"#/components/schemas/CustomizationMonospaceFont"},"background":{"deprecated":true,"$ref":"#/components/schemas/CustomizationBackground"},"icons":{"$ref":"#/components/schemas/CustomizationIconsStyle"},"codeTheme":{"type":"object","properties":{"default":{"$ref":"#/components/schemas/CustomizationThemedCodeTheme"},"openapi":{"$ref":"#/components/schemas/CustomizationThemedCodeTheme"}},"required":["default","openapi"]},"sidebar":{"type":"object","properties":{"background":{"$ref":"#/components/schemas/CustomizationSidebarBackgroundStyle"},"list":{"$ref":"#/components/schemas/CustomizationSidebarListStyle"}},"required":["background","list"]},"search":{"$ref":"#/components/schemas/CustomizationSearchStyle"}},"required":["theme","primaryColor","infoColor","successColor","warningColor","dangerColor","corners","depth","links","font","monospaceFont","codeTheme","background","icons","sidebar","search"]},"internationalization":{"type":"object","deprecated":true,"properties":{"locale":{"$ref":"#/components/schemas/CustomizationLocale"}},"required":["locale"]},"favicon":{"$ref":"#/components/schemas/CustomizationFavicon"},"header":{"type":"object","properties":{"preset":{"$ref":"#/components/schemas/CustomizationHeaderPreset"},"logo":{"$ref":"#/components/schemas/CustomizationThemedURL"},"primaryLink":{"description":"Destination to open when visitors click the site title/logo in the header.","$ref":"#/components/schemas/ContentRef"},"backgroundColor":{"deprecated":true,"description":"Color of the background in the header. This value is now deprecated in favour of the new theming colors.","$ref":"#/components/schemas/CustomizationThemedColor"},"linkColor":{"deprecated":true,"description":"Color of the links in the header. This value is now deprecated and will be phased out in favour of the new theming colors.","$ref":"#/components/schemas/CustomizationThemedColor"},"links":{"type":"array","items":{"$ref":"#/components/schemas/CustomizationHeaderItem"}}},"required":["preset","links"]},"footer":{"type":"object","properties":{"logo":{"$ref":"#/components/schemas/CustomizationThemedURL"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomizationFooterGroup"}},"copyright":{"type":"string","maxLength":300}},"required":["groups"]},"announcement":{"$ref":"#/components/schemas/CustomizationAnnouncement"},"themes":{"description":"Customization options for the dark/light theme modes.\n","type":"object","properties":{"default":{"$ref":"#/components/schemas/CustomizationDefaultThemeMode"},"toggeable":{"description":"Should the reader be able to switch between dark and light mode","type":"boolean"}},"required":["default","toggeable"]},"feedback":{"type":"object","properties":{"enabled":{"type":"boolean","description":"If true, feedback gathering is enabled"}},"required":["enabled"]},"ai":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/CustomizationAIMode"},"suggestions":{"$ref":"#/components/schemas/CustomizationSuggestedQuestions"}},"required":["mode"]},"advancedCustomization":{"type":"object","properties":{"enabled":{"type":"boolean","description":"If true, Advanced customization is enabled"}},"required":["enabled"]},"pageActions":{"type":"object","properties":{"items":{"type":"array","description":"Ordered list of the page actions enabled in the page menu. This is the source of truth for\nwhich actions are enabled and in which order: the position defines the display order, the\nfirst action is the default one, surfaced as the main button on the page, and actions not\npresent in the list are disabled. An empty list turns the page menu off entirely: no action\nis shown, not even the `assistant`. On a non-empty list the `assistant` action follows the\n`ai.mode` setting rather than its own presence: it is kept (prepended by default if missing,\notherwise keeping its position) when the assistant is enabled and absent when it is disabled.\nWhen the menu is off, the assistant stays reachable from the header via `ai.mode`.\n","items":{"$ref":"#/components/schemas/CustomizationPageActionType"}}},"required":["items"]},"externalLinks":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/SiteExternalLinksTarget"}},"required":["target"]},"pagination":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the pagination navigation should be displayed on pages."}},"required":["enabled"]},"trademark":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the GitBook trademark (\"Powered by GitBook\") should be visible"}},"required":["enabled"]},"privacyPolicy":{"type":"object","properties":{"url":{"$ref":"#/components/schemas/URL"}}},"socialPreview":{"type":"object","properties":{"url":{"$ref":"#/components/schemas/URL"}}},"socialAccounts":{"$ref":"#/components/schemas/SiteSocialAccounts"},"insights":{"type":"object","properties":{"trackingCookie":{"type":"boolean","description":"Whether GitBook identifies the visitor on the site using a cookie.","default":true}},"required":["trackingCookie"]}},"required":["styling","internationalization","favicon","header","footer","themes","feedback","ai","advancedCustomization","trademark","externalLinks","pagination","pageActions","privacyPolicy","socialPreview","socialAccounts","insights"]},"SiteTitle":{"type":"string","description":"Title of the site","minLength":2,"maxLength":128},"LocalizedString128":{"type":"object","description":"Localized string value with a 128 character limit, keyed by locale. Contains overrides for non-default languages only.","additionalProperties":{"type":"string","maxLength":128},"propertyNames":{"$ref":"#/components/schemas/TranslationLanguage"}},"TranslationLanguage":{"type":"string","enum":["en","fr","de","es","it","pt","pt-br","ru","ja","zh","zh-tw","yue","ko","ar","hi","nl","pl","tr","sv","no","da","fi","el","cs","hu","ro","th","vi","id","ms","he","uk","sk","bg","hr","lt","lv","et","sl"]},"CustomizationTheme":{"type":"string","description":"The theme to apply to the site. Supercedes the old header preset themes.\n- `clean`: Modern theme featuring translucency and minimally-styled elements.\n- `muted`: Sophisticated theme with decreased contrast between elements.\n- `bold`: High-impact theme with prominent colors and strong contrasts.\n- `gradient`: Trendy theme featuring colorful gradients and splashes of color.\n","enum":["clean","muted","bold","gradient"]},"CustomizationThemedColor":{"type":"object","properties":{"light":{"$ref":"#/components/schemas/Color"},"dark":{"$ref":"#/components/schemas/Color"}},"required":["light","dark"]},"Color":{"type":"string","pattern":"^#(?:[0-9a-fA-F]{3}){1,2}$"},"CustomizationTint":{"type":"object","properties":{"color":{"$ref":"#/components/schemas/CustomizationThemedColor"}},"required":["color"]},"CustomizationCorners":{"type":"string","enum":["straight","rounded","circular"]},"CustomizationDepth":{"type":"string","description":"The degree of visual depth (through shadows, gradients and elevation effects) of elements on the site.\n- `subtle`: Subtle shadows and minimal elevation.\n- `flat`: Flat elements, no shadows and no elevation.\n","enum":["subtle","flat"]},"CustomizationLinksStyle":{"type":"string","description":"The style used for regular links in the main content, header and footer. Sidebar items are styled separately.\n- `default`: Links are colored in the primary color and feature an underline in the same color.\n- `accent`: Links are colored the same as body text and feature an underline in the primary color.\n","enum":["default","accent"]},"CustomizationFont":{"oneOf":[{"$ref":"#/components/schemas/CustomizationDefaultFont"},{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"}]},"CustomizationDefaultFont":{"type":"string","enum":["ABCFavorit","Inter","Roboto","RobotoSlab","OpenSans","SourceSansPro","Lato","Ubuntu","Raleway","Merriweather","Overpass","NotoSans","IBMPlexSerif","Poppins","FiraSans"]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048},"CustomizationMonospaceFont":{"oneOf":[{"$ref":"#/components/schemas/CustomizationDefaultMonospaceFont"},{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"}]},"CustomizationDefaultMonospaceFont":{"type":"string","enum":["FiraCode","IBMPlexMono","JetBrainsMono","SourceCodePro","RobotoMono","SpaceMono","DMMono","Inconsolata"]},"CustomizationBackground":{"type":"string","enum":["plain","match"],"deprecated":true,"description":"The background style has been deprecated and will be removed in a future release. Use the `tint` settings instead."},"CustomizationIconsStyle":{"type":"string","enum":["regular","solid","duotone","light","thin"]},"CustomizationThemedCodeTheme":{"type":"object","properties":{"light":{"$ref":"#/components/schemas/CustomizationCodeTheme"},"dark":{"$ref":"#/components/schemas/CustomizationCodeTheme"}},"required":["light","dark"]},"CustomizationCodeTheme":{"type":"string","enum":["default-light","default-dark","monochrome-light","monochrome-dark","andromeeda","aurora-x","ayu-dark","catppuccin-frappe","catppuccin-latte","catppuccin-macchiato","catppuccin-mocha","dark-plus","dracula","dracula-soft","everforest-dark","everforest-light","github-dark","github-dark-default","github-dark-dimmed","github-dark-high-contrast","github-light","github-light-default","github-light-high-contrast","gruvbox-dark-hard","gruvbox-dark-medium","gruvbox-dark-soft","gruvbox-light-hard","gruvbox-light-medium","gruvbox-light-soft","houston","kanagawa-dragon","kanagawa-lotus","kanagawa-wave","laserwave","light-plus","material-theme","material-theme-darker","material-theme-lighter","material-theme-ocean","material-theme-palenight","min-dark","min-light","monokai","night-owl","nord","one-dark-pro","one-light","plastic","poimandres","red","rose-pine","rose-pine-dawn","rose-pine-moon","slack-dark","slack-ochin","snazzy-light","solarized-dark","solarized-light","synthwave-84","tokyo-night","vesper","vitesse-black","vitesse-dark","vitesse-light"]},"CustomizationSidebarBackgroundStyle":{"type":"string","description":"- `default`: No background, content sits directly against sidebar edge.\n- `filled`: Muted background color that extends to sidebar edges.\n","enum":["default","filled"]},"CustomizationSidebarListStyle":{"type":"string","description":"- `default`: Simple list items without special styling, groups are inset with a line.\n- `pill`: Rounded capsule shape around selected/active items.\n- `line`: Continuous line next to all items, with colored line part for selected/active items.\n","enum":["default","pill","line"]},"CustomizationSearchStyle":{"type":"string","description":"The style of the search button.\n- `prominent`: large search bar in the middle of the header, with less room for other header items,\n- `subtle`: small search bar in the corner of the header, with more room for other header items.\n","enum":["prominent","subtle"]},"CustomizationLocale":{"type":"string","description":"Language for the UI element","deprecated":true,"enum":["en","fr","es","zh","ja","de","nl","no","pt-br","ru"]},"CustomizationFavicon":{"oneOf":[{"type":"object","properties":{"icon":{"$ref":"#/components/schemas/CustomizationThemedURL"}},"required":["icon"]},{"type":"object","properties":{"emoji":{"$ref":"#/components/schemas/Emoji"}},"required":["emoji"]},{"type":"object","properties":{},"additionalProperties":false}]},"CustomizationThemedURL":{"type":"object","properties":{"light":{"$ref":"#/components/schemas/URL"},"dark":{"$ref":"#/components/schemas/URL"}},"required":["light","dark"]},"Emoji":{"type":"string","maxLength":50,"format":"emoji","description":"Unicode codepoint or character of the emoji"},"CustomizationHeaderPreset":{"type":"string","deprecated":true,"description":"The header preset to use for the site. This is a legacy setting and the site styling theme should be used instead.","enum":["default","bold","contrast","custom","none"]},"ContentRef":{"description":"A relative reference to content in GitBook.","oneOf":[{"$ref":"#/components/schemas/ContentRefFile"},{"$ref":"#/components/schemas/ContentRefURL"},{"$ref":"#/components/schemas/ContentRefPage"},{"$ref":"#/components/schemas/ContentRefAnchor"},{"$ref":"#/components/schemas/ContentRefUser"},{"$ref":"#/components/schemas/ContentRefCollection"},{"$ref":"#/components/schemas/ContentRefSpace"},{"$ref":"#/components/schemas/ContentRefReusableContent"},{"$ref":"#/components/schemas/ContentRefTag"},{"$ref":"#/components/schemas/ContentRefOpenAPI"}]},"ContentRefFile":{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"file":{"type":"string"},"space":{"description":"ID of the space the file is in. The file is considered as in the current space if none is provided.","type":"string"}},"required":["kind","file"]},"ContentRefURL":{"type":"object","properties":{"kind":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["kind","url"]},"ContentRefPage":{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"page":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"}},"required":["kind","page"]},"ContentRefAnchor":{"type":"object","properties":{"kind":{"type":"string","enum":["anchor"]},"anchor":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"},"page":{"description":"ID of the page the anchor is in. The anchor is considered as in the current page if none is provided.","type":"string"}},"required":["kind","anchor"]},"ContentRefUser":{"type":"object","properties":{"kind":{"type":"string","enum":["user"]},"user":{"type":"string"}},"required":["kind","user"]},"ContentRefCollection":{"type":"object","properties":{"kind":{"type":"string","enum":["collection"]},"collection":{"type":"string"}},"required":["kind","collection"]},"ContentRefSpace":{"type":"object","properties":{"kind":{"type":"string","enum":["space"]},"space":{"type":"string"}},"required":["kind","space"]},"ContentRefReusableContent":{"type":"object","properties":{"kind":{"type":"string","enum":["reusable-content"]},"reusableContent":{"type":"string"},"space":{"type":"string","description":"The space in which the reusable content is defined. If undefined, the reusable content is assumed to be in the same space as the content reference."}},"required":["kind","reusableContent"]},"ContentRefTag":{"type":"object","properties":{"kind":{"type":"string","enum":["tag"]},"tag":{"type":"string","description":"The slug of the tag, also used as the ID, and references the tags defined on a revision."},"space":{"type":"string","description":"The space in which the tag is defined. If undefined, the tag is assumed to be in the same space as the content reference."}},"required":["kind","tag"]},"ContentRefOpenAPI":{"type":"object","properties":{"kind":{"type":"string","enum":["openapi"]},"spec":{"type":"string","description":"Slug of the OpenAPI specification"}},"required":["kind","spec"]},"CustomizationHeaderItem":{"type":"object","properties":{"title":{"type":"string"},"localizedTitle":{"description":"Localized overrides for the header item title, keyed by locale.","$ref":"#/components/schemas/LocalizedString"},"style":{"type":"string","enum":["link","button-primary","button-secondary"]},"to":{"oneOf":[{"$ref":"#/components/schemas/ContentRef"},{"type":"null"}]},"links":{"type":"array","items":{"$ref":"#/components/schemas/CustomizationContentLink"}},"condition":{"description":"Conditional expression used to evaluate whether the header item should be shown to the site's visitor.","$ref":"#/components/schemas/Expression"}},"required":["title","links","to"]},"LocalizedString":{"type":"object","description":"Localized string value, keyed by locale. Contains overrides for non-default languages only.","propertyNames":{"$ref":"#/components/schemas/TranslationLanguage"},"additionalProperties":{"type":"string"}},"CustomizationContentLink":{"type":"object","properties":{"title":{"$ref":"#/components/schemas/CustomizationContentLinkTitle"},"localizedTitle":{"description":"Localized overrides for the link title, keyed by locale.","$ref":"#/components/schemas/LocalizedString64"},"to":{"$ref":"#/components/schemas/ContentRef"}},"required":["title","to"]},"CustomizationContentLinkTitle":{"type":"string","maxLength":64},"LocalizedString64":{"type":"object","description":"Localized string value with a 128 character limit, keyed by locale. Contains overrides for non-default languages only.","additionalProperties":{"type":"string","maxLength":64},"propertyNames":{"$ref":"#/components/schemas/TranslationLanguage"}},"Expression":{"type":"string","description":"Expression to evaluate","minLength":0,"maxLength":1024},"CustomizationFooterGroup":{"type":"object","properties":{"title":{"type":"string"},"localizedTitle":{"description":"Localized overrides for the footer group title, keyed by locale.","$ref":"#/components/schemas/LocalizedString"},"links":{"type":"array","items":{"$ref":"#/components/schemas/CustomizationContentLink"}}},"required":["title","links"]},"CustomizationAnnouncement":{"type":"object","properties":{"enabled":{"description":"Whether to show the site's announcement.","type":"boolean"},"message":{"$ref":"#/components/schemas/CustomizationAnnouncementMessage"},"localizedMessage":{"description":"Localized overrides for the announcement message, keyed by locale.","$ref":"#/components/schemas/LocalizedString128"},"link":{"description":"The content or URL the announcement links to when clicked.","$ref":"#/components/schemas/CustomizationContentLink"},"style":{"description":"The style of the announcement. Used to style the banner with the right semantic color and enable/disable features like hiding the banner.","type":"string","enum":["info","warning","danger","success"]}},"required":["enabled","message","style"]},"CustomizationAnnouncementMessage":{"description":"The text content of the announcement.","type":"string","minLength":2,"maxLength":128},"CustomizationDefaultThemeMode":{"type":"string","enum":["light","dark","system"]},"CustomizationAIMode":{"type":"string","enum":["none","search","assistant"]},"CustomizationSuggestedQuestions":{"type":"array","description":"Suggested questions to display at the start of the chosen AI mode.","items":{"$ref":"#/components/schemas/CustomizationSuggestedQuestion"},"maxItems":5},"CustomizationSuggestedQuestion":{"type":"string","minLength":3,"maxLength":64},"CustomizationPageActionType":{"type":"string","description":"Type of a built-in page action that can be displayed in the page actions menu of a published page.","enum":["assistant","external-ai","markdown","mcp","git","pdf"]},"SiteExternalLinksTarget":{"type":"string","description":"How external links should open when clicked.\n- `self`: External links open in the current tab.\n- `blank`: External links open in a new browser tab.\n","enum":["self","blank"]},"SiteSocialAccounts":{"type":"array","description":"The social accounts of the site.","items":{"$ref":"#/components/schemas/SiteSocialAccount"},"maxItems":10},"SiteSocialAccount":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SiteSocialAccountPlatform"},"handle":{"$ref":"#/components/schemas/SiteSocialAccountHandle"},"display":{"type":"object","properties":{"footer":{"type":"boolean","default":true},"header":{"type":"boolean","default":false}},"required":["footer","header"]}},"required":["platform","handle","display"]},"SiteSocialAccountPlatform":{"description":"The platform of the social handle.","type":"string","enum":["twitter","instagram","facebook","linkedin","github","discord","slack","youtube","tiktok","reddit","bluesky","mastodon","threads","medium"]},"SiteSocialAccountHandle":{"description":"A handle on a social platform, without prefixes like the @ symbol.","type":"string","minLength":1,"maxLength":128},"Timestamp":{"type":"string","format":"date-time"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/site-customization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.