Add Custom Content to Your Docs

Generated Content

Most of the content of an SDK docs site is fully generated from the OpenAPI spec.

To modify anything that appears under the resources section of docs, you need to edit your spec and regenerate. Some customizations you can make directly in your docs directory and they will not be overwritten – these are detailed below.

Customize SDK Guides

The guides section of SDK docs features several different pieces of content that you can disable or override.

These are the guides that are available, depending on your OpenAPI spec and the gen.yaml configurations to disable them. For more information on configuring your gen.yaml file, see gen.yaml reference.

GuideDisable Config
InstallationdisableInstallationSection
PaginationdisablePaginationSection
Global ParametersdisableGlobalParametersSection
Custom Http ClientdisableCustomClientSection
Security OptionsdisableSecurityOptionsSection
SDK ErrorsdisableSDKErrorsSection
RetriesdisableRetriesSection
Server OptionsdisableServerOptionsSection

You can also manually override the content for each of these sections. Navigate to /content/pages/01-reference/{language}/{guide}/_snippet.mdx to edit sections.

Following generation, you should see code that looks like the following.

installation/_snippet.mdx

{/* Start Typescript Installation */}
### NPM
npm add ts-url
{/* End Typescript Installation */}

Remove the markdown comments and replace this file with your custom content. The docs generator will not overwrite this custom content.

installation/_snippet.mdx

Custom Installation Content

Add a Navbar Link

Speakeasy supports adding custom navlinks at the top of your SDK docs site that you can use to link out to other parts of your website.

To configure custom navlinks, add some basic extra configuration to your theme.yaml file.

theme.yaml

title: Speakeasy Bar SDK Docs
primaryColor:
dark: rgb(251, 227, 50)
light: rgb(22, 21, 14)
logo:
dark: /logo-dark.png
light: /logo-light.png
link: https://www.speakeasyapi.dev/
favicon: /favicon.png
codeTheme: material-darker
navLinks:
custom:
title: Custom Link
href: https://www.speakeasyapi.dev/docs/intro/
new_window: true # opens a new window on-click

Set Up Custom Redirects

You may want to set up current custom redirect patterns, for example, if you're migrating from an old docs site to your new SDK docs.

Set up custom redirect patterns in the theme.yaml file. Speakeasy supports both absolute paths and wildcard paths at the middle and end of the URL.

theme.yaml

title: Speakeasy Bar SDK Docs
primaryColor:
dark: rgb(251, 227, 50)
light: rgb(22, 21, 14)
logo:
dark: /logo-dark.png
light: /logo-light.png
link: https://www.speakeasyapi.dev/
favicon: /favicon.png
codeTheme: material-darker
redirects:
- from: "/old/myOp"
to: "/curl/my_op"
- from: "/old/myOp/*"
to: "/curl/my_op/*"
- from: "/*/myOp"
to: "/curl/my_op"