The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

Site customization

Customize the look and feel of your docs site.

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

Attributes
titlestring · min: 2 · max: 128optional

Title to use for the published site. If not defined, it'll fallback to the default content title.

stylingobjectrequired
internationalizationobjectrequired
faviconone ofrequired
headerobjectrequired
footerobjectrequired
announcementobjectoptional
themesobjectrequired

Customization options for the dark/light theme modes.

pdfobjectrequired
feedbackobjectrequired
aiSearchobjectrequired
aiobjectoptional
advancedCustomizationobjectrequired
gitobjectrequired
paginationobjectrequired
trademarkobjectrequired
privacyPolicyobjectrequired
socialPreviewobjectrequired
insightsobjectrequired

The SiteCustomizationSettings object

{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

Get a site customization settings

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
unmaskedbooleanoptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Default: false
Responses
application/json
objectoptional
get
GET /v1/orgs/{organizationId}/sites/{siteId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

Update a site customization settings

put
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
titlestring · min: 2 · max: 128optional

Title to use for the published site. If not defined, it'll fallback to the default content title.

stylingobjectrequired
internationalizationobjectrequired
faviconone ofrequired
headerobjectrequired
footerobjectrequired
announcementobjectoptional
themesobjectrequired

Customization options for the dark/light theme modes.

pdfobjectrequired
feedbackobjectrequired
aiSearchobjectrequired
aiobjectoptional
advancedCustomizationobjectrequired
gitobjectrequired
paginationobjectrequired
trademarkobjectrequired
privacyPolicyobjectrequired
socialPreviewobjectrequired
insightsobjectrequired
Responses
application/json
objectoptional
put
PUT /v1/orgs/{organizationId}/sites/{siteId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1540

{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

Get a site space customization settings

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Query parameters
unmaskedbooleanoptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Default: false
Responses
application/json
objectoptional
get
GET /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

Delete a site space customization settings

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Responses
delete
DELETE /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No Content

Override a site space customization settings

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Body

The settings that overrides the site customization settings.

titleone ofoptional

Title to use for the published site variant. If not defined, the title will not be changed. If set to null, the title will be unset and will fallback to the content title.

Title of the site

stylingobjectoptional
internationalizationobjectoptional
faviconone ofoptional

The favicon to use. Set to null to reset the override.

announcementobjectoptional
headerobjectoptional
footerobjectoptional
themesobjectoptional
pdfobjectoptional
feedbackobjectoptional
aiSearchobjectoptional
gitobjectoptional
paginationobjectoptional
trademarkobjectoptional
privacyPolicyobjectoptional
socialPreviewobjectoptional
Responses
application/json
objectoptional
patch
PATCH /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1512

{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  }
}
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

Was this helpful?