Speakeasy offers two ways of serving your docsite: 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 docsites and is the default option for Speakeasy.

In order to generate your docs statically, simply ensure that the static option is set to true in your docs gen.yaml file. This is the default option, so you don't need to do anything if you haven't changed it.

Although the docs are generated statically, you will still need to run a lightweight server in order to handle some of the routing complexities incurred by the single page design of our docsites. A file called server.go will be generated in your docs directory. It can be run with go run server.go and will simply serve the statically generated HTML files. We also provide a Dockerfile for your convenience. You can host this as a Docker image just like any other. Make sure to run pnpm run next:build && pnpm run export before running the go server or building a Docker image.

Server-Side Rendering

SSR (server-side rendering) is another popular way of rendering docsites and is a good option if you have a preference for working with Next servers directly.

Simply ensure that the static option is set to false in your docs gen.yaml file 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.

References on Hosting a Docker Image