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 will need to modify your spec and regenerate. There are certain customizations you can make directly in your docs directory which will not be overwritten, we will cover those below.

Customize SDK Guides

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

These are the following 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. To do this navigate to /content/pages/01-reference/{language}/{guide}/_snippet.mdx.

After generation you should see code that looks like the following.

installation/_snippet.mdx

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

Simply remove the markdown comments and replace this file with your own custom content. It will not be overwritten by the docs generator.

installation/_snippet.mdx

Custom Installation Content

Add a Navbar Link

We also support adding custom navlinks at the top of your SDK docs site. You may use these navlinks to link out to other parts of your website.

To configure custom navlinks add some basic additional 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

Setup Custom Redirects

There may be times where you want to setup current custom redirect patterns as you migrate from an old doc site to your new SDK docs. You can also setup these configurations in your theme.yaml file. We support 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"