Next-level docs with Next.js: Teleport’s new customer acquisition channel

The Teleport team wanted to simplify work for their frontend developers by unifying their docs and website under a single framework that they already knew perfectly. They also needed to provide a top-tier developer experience for their docs and add new dynamic features.

To that end, they needed a serverless hosting solution with built-in GitHub integration, automatic deployment, and high-level security. And Evil Martians made all of this happen, helping them migrate to Next.js, host their solution on Vercel, and build the advanced features for documentation.

This project provided a great chance for our team to put into action our expertise in open source, Next.js, and client frontend projects related to docs.

The previous situation + Teleport’s requirements

For some context, Teleport is an Open Core platform that helps companies secure access to their infrastructure, control all privileges, and access policies from one place. Actually, this is what made them a “unicorn”, according to their latest valuation.

Teleport’s previous solutions were not offering what they needed, and they also had a few important requirements going forward.

Their documentation and website were previously built using MkDocs (for docs) and Hugo (for their website), but they couldn’t provide the necessary features without significant engineering effort:

• MkDocs made it difficult to include dynamic components in the docs or use Git branches to manage different doc versions with automatic deployments.
• Hugo lacked CMS integration, the ability to update content without Markdown, GitHub-based deployment, and support for complex, dynamic pages.

Likewise, they wanted to manage both their website and documentation within a single framework:

• They could reuse UI components without having to re-implement them every time
• It would be easy to maintain a consistent branding style
• They could upgrade their resources without any manual copy-paste work (or without tons of boilerplate code)

Hello, Next.js

With these concerns and requirements, where to go?

Well, starting from a practical angle, it naturally follows that it would be easier for their developers to use familiar tools instead of rushing off into something completely new. Further, using familiar frameworks would also help with component transferability as well as doc-website integration.

And, since the frontend of the Teleport application was originally implemented in React, the developers decided to go with a React-based framework. Ultimately, Next.js fits the bill here!

Why? Next.js is a mature platform with high implementation speed; builders can start coding immediately without the need to spend time configuring settings: it has close to zero set-up time.

It also included several features the Teleport team needed:

• Rendering static/dynamic pages, like client routing and SSR for search engines
• Automatic support for pages
• next/image for image optimizations
• The ability to update page content in production without full site rebuild by using hooks from the CMS to invalidate cached static pages

Vercel Enterprise

The Teleport team is also now using the Enterprise Version of Vercel for hosting since this plan can support the growing number of developers who need to deal with access matters.

Teleport wanted to provide access to the Vercel control panel to a larger number of their engineers, and the ability to add SSO via Okta in the Enterprise version lets them manage accesses and privileges for all team members on a centralized basis.

Most importantly, the Teleport team got a full compliance and security match for their application. The Enterprise plan meets strict security requirements (SOC 2 Type 2), includes GDPR compliance, and has an uptime SLA guarantee. Features like SSO, SCIM, and audit logs were also must-haves and intended as strong incentives to switch to the Enterprise plan.

This new plan also allowed their large engineering team to solve the problem of long build queues in the main repo (which was updated quite often.) Previously, the speed of some builds could take up to 20 minutes, but due to higher deployment speeds and a larger number of concurrent builds in the Enterprise version—this was no more.

New combo, custom solutions

Next.js and its ecosystem allowed the Teleport team to create a solution tailored to their specific needs—those not supported by standard documentation engines.

First, they could build docs for different versions of Teleport using the markdown files in the different branches of the main Teleport repository.

Previously, if the developers needed to store all versions of the docs together in separate folders (and if changes needed to be backported to older versions) this all had to be done by hand.

Storing the docs in the same repository ensures they are always up-to-date and relevant to the current version of the code. In this case, leveraging built-in capabilities from Git and GitHub also helps them immediately understand what has changed across different versions without re-reading the docs and copy-pasting them for each repository version.

Since Vercel supports many different developer workflows with Git, they also could update docs using the pull request flow they’re familiar with: the team could store docs in the main repo and update them together with the app code updates in different branches. After the feature is reviewed in GitHub and merged in the branch/main, the docs site is automatically rebuilt if needed. So, there are no separate update steps for updating the docs site.

Second, this allowed them to introduce new dynamic features into the docs that the prior framework couldn’t provide.

From critical features like shared user variables between pages for code snippets, complex models of automated linking between doc page versions, and custom code blocks for CLI examples where you can copy each command separately—to smaller but helpful ones like automatic rendering of Mermaid.js dynamic charts.

Teleport’s engineers also gained the ability to hide or show different parts of page content depending on the user’s business plan and to reimplement some old liquid tags for backward compatibility.

Finally, since the project team wanted to avoid the need to manually transfer tons of documents written for MkDocs while also editing them in the process, they wanted to maintain the old syntax during migration.

Documentation enhancement with Next.js

So, Evil Martians helped develop a Next.js-based solution that helped Teleport switch to a single engine for their company resources (within a familiar tech stack) that didn’t involve any server management.

Before the migration, docs deployment was a manual process, and docs teams and external contributors did not have a way to preview the versions or collaborate with engineering.

Now, the core app’s development team can easily and independently maintain and edit all resources with React and deploy updates to documentation multiple times per day using familiar and comfortable pull request flows, they can preview versions, lint, and code reviews.

Additionally, they can utilize Vercel Preview Deployments and Preview Comments to review their work.

And there’s more—beyond this, Next.js also helped them build new advanced documentation engine features like AI semantic search and custom components.

Teleport’s website and new docs now drive top traffic and customer acquisition, with hundreds of thousands of views every month.

We have been heavy Next.js users for the last couple of years. Evil Martians is also a partner with Vercel and part of their ecosystem of experts.