Today, we’re thrilled to announce that we’re open-sourcing our Knock documentation under an MIT license. We’re making this change to empower our community to self-improve our documentation rather than needing to file support tickets and to serve as an example for others on how you might build a documentation site from scratch. Our docs site is available today on GitHub and is accepting contributions now.
Why write our own documentation site?
From day one at Knock, we considered documentation part of our core product. After all, great documentation is one of the fundamental pillars of a great developer experience. With that lens, we knew that using something off the shelf to build our docs would always lead to a compromised experience and lack of flexibility, so we decided to build our own. We’ve included more details below on the technologies we used to do this, but in essence, our docs site renders markdown into static HTML pages.
One of the nice benefits of this being a very simple, static website is that every engineer on the Knock team has contributed extensively to our documentation, given that the learning curve for authoring content is not very steep. As a team, we believe that developer experience is owned by everyone, and having an easy way to introduce and update documentation is one way to ensure this aspect of developer experience is not neglected.
How we built our documentation site
Our docs site has evolved over the past 2 years as we added entire API sections, introduced our CLI, added several new integrations, and introduced dark mode, amongst other improvements. However, even with all these changes, the site's foundation has stayed relatively static. We use the following technologies:
- Next.js
- MDX for authoring content (via
next-mdx-remote) - Tailwind for styling (including
@tailwind/typographyfor all of the base typography styles) - Algolia to power search (via a custom component)
- Vercel for hosting
@vercel/ogfor powering our dynamic open graph images
One of the most challenging aspects of rolling our own documentation experience is introducing multi-language code samples, where we let you change the language you’re using for all samples and then show you relevant code per language. To power that, we opted for a simple approach where we author samples in each language in a JS file and then reference the samples in the component by a key. You can see more in the MultiLangCodeBlock component for the current implementation and an example of how we’re authoring the code samples here.
Future improvements we’d love to make
Like any part of our product, we see our documentation as continuously evolving. We’re happy to have a flexible base to build on to achieve this. In the future we’d love to:
- Add a mobile navigation experience. This is something we punted on, given that mobile is not the most important viewing experience.
- Code-split and dynamically load code samples. Right now we’re just bundling all of the code samples together. Splitting this and serving it dynamically would cut down on the size of each page load.
- Split out our API reference. One problem right now is all of our API reference is served as a single page with anchor links. We really love how Stripe and WorkOS serve each section as its own URL path so it can be deep linked to.
If you’re looking for inspiration for your next documentation site and are considering rolling your own versus leveraging something off the shelf, look at our GitHub and spelunk through our source code as a reference. Or, if you see any errors in any of the documentation we provide today, we’d greatly appreciate a pull request back.