Rebuilding Teleport's docs on Next.js and Vercel

Teleport, an open-core platform for secure infrastructure access, wanted its website and documentation to feel like a single, cohesive product. The previous setup—split across MkDocs and Hugo—made dynamic components and versioned docs difficult to manage, and developers had little visibility into docs changes before they went live. Working with the consultancy Evil Martians, the team migrated the entire stack to Next.js on Vercel, consolidating both properties under one React-based framework.

From the start, the requirements were clear: CMS integration for straightforward content updates, support for complex dynamic pages, and automated deployments via GitHub. All three were hard to deliver with the old static-site tools. Hosting on Vercel added the missing pieces—serverless infrastructure that grows Preview deployments on demand and integrates directly with GitHub for production updates—while meeting GDPR and SOC 2 Type II compliance needs.

Building a custom docs layer

By moving everything to Next.js, Teleport could centralize development and keep brand assets consistent across public pages and product documentation. Out-of-the-box features like client-side routing, server-side rendering, automatic SEO, and next/image optimization improved site performance and user experience. The big win, however, was a custom documentation system that addressed three specific problem areas:

  • Versioning: Docs for multiple Teleport versions are generated from Markdown files in different repository branches, which simplifies backporting and keeps docs aligned with code changes.
  • Migration ease: The new setup still accepts old MkDocs syntax, so the team didn't have to manually transfer and edit a massive number of existing documents.
  • Dynamic features: New capabilities include shared user variables in code snippets, automatic linking between doc versions, custom code blocks, and Mermaid.js charts.

The content system also takes advantage of CMS hooks, allowing certain pages to update in real time without triggering a full site rebuild.

Faster builds and clearer collaboration

Infrastructure improvements translated into sharp operational gains. Teleport saw build times drop by more than 60%, while the platform supported 3x more concurrent builds. Developers can now deploy different parts of the application without waiting in queue—a necessity for a team that ships multiple times a day.

The workflow gains were equally significant. Prior to Vercel, deploying docs was a manual process that gave teleport's docs team and external contributors no way to preview work or collaborate with engineering. Now every change gets an automatic preview environment, and vetted team members can deploy to production without ceremony. Security also became simpler: Vercel's Firewall and DDoS mitigation protect the digital assets, and SAML single sign-on via Okta restricts changes to authorized engineers only.

The result is a documentation portal that Teleport treats as a genuine acquisition channel. With the old stack, frequent content refreshes and cross-team collaboration were heavy lifts; with the Next.js and Vercel platform, they're routine.

“Vercel-based Teleport docs and website are a huge success. Our engineers deploy multiple times per day without thinking about it, while always having the ability to preview their work. Before Vercel, deployment of docs was a manual process. Our docs teams and external contributors did not have a way to preview or collaborate with engineering. Vercel unlocked all those workflows and collaboration points for us. We could not be happier.”