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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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
  }
}

OK

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
curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
  }
}

OK

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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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
  }
}

OK

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
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Site space customization removed

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
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
  }
}

OK

Was this helpful?