Speakeasy offers two ways of serving your docs site: static generation and server-side rendering. Both options produce similar results, and switching between them is trivial, so it's up to you to decide which one you prefer. If you're unsure, static generation is probably the way to go.

Static Generation

SSG (static site generation) is a popular way of rendering docs sites and the default option for Speakeasy.

To statically generate your docs, the static option should be set to true in your docs gen.yaml file. As this is the default option, you don't need to do anything if you haven't changed this setting.

Although Speakeasy generates the docs statically, you still need to run a lightweight server to handle some of the routing complexities of the single-page design of Speakeasy docs sites.

Speakeasy will generate a server.go file in your docs directory. Run the file with go run server.go, and Speakeasy will serve the statically generated HTML files.

Speakeasy also provides a Dockerfile for your convenience. Host the Dockerfile as a Docker image, just like any other.

Be sure to run pnpm run next:build && pnpm run export before running the Go server or building a Docker image.

Server-Side Rendering

Server-side rendering (SSR) is another popular way of rendering docs sites and is a good option if you prefer to work with Next servers directly.

If you would like to host a Next server with Vercel (opens in a new tab), Netlify (opens in a new tab), or some similar tool, ensure that the static option is set to false in your docs gen.yaml file.

References for Hosting a Docker Image