Building a TypeDoc-powered Gatsby Documentation Site
We recently migrated our user-facing documentation to Gatsby and it's still powered by TypeDoc symbols

I help maintain the Excalibur.js web-based game engine. We started Excalibur back in 2011 and it was always written from the ground up in TypeScript. Since Excalibur hasn't yet reached 1.0, all of our documentation has been in the source code. Luckily, early on we started to adopt a tool called Typedoc which could generate a rich documentation site for TypeScript-based projects.

Linking to API Symbols

Using TypeDoc, we could build richer documentation with embedded Markdown documents. It also has a compelling feature to do link to API symbols using a [[symbolName]] or {@link symbolName} syntax. This was awesome because we could write "user-facing" documentation and easily create maintainable links to the raw API symbols.

Since we could separate user-facing documentation into separate .md files, TypeDoc allowed us to use [[include:file.md]] directives to keep our documentation separate from the source code.

This approach has been working well for us in the past years but there were several downsides:

  • The "user" documentation was locked into the TypeDoc site and theme
  • While TypeDoc was customizable, it was still hard to do more complex things like custom components (think MDX) or rendering
  • It just wasn't cohesive--we had a main site and you'd expect to find docs hosted under there. It would take a lot of work to customize the TypeDoc theme enough to make it feel like a natural part of the site.

We needed to do something different and ideally have these user docs hosted within the main site but still maintain the ability to easily link to API docs.

Migrating to Gatsby.js

Awhile back, I converted our site to be statically generated using Gatsby.js and this has proved to be a good decision. Gatsby allows us to customize all the aspects of the site including the way we generate documentation.

Gatsby uses a GraphQL-based sourcing architecture where you can add any kind of "source" of data--this could be Wordpress, the GitHub API, or basically any external piece of data you wanted. These source plugins take the data from one place and transform it into GraphQL nodes that Gatsby can understand and make available to your pages statically. This makes Gatsby incredibly versatile and customizable using a consistent architecture.

Gatsby also has the idea of transformers. Transformers take input, usually an Abstract Syntax Tree (AST) and run it through processors that make changes. For example, there's gatsby-transformer-remark that takes Markdown AST and parses it using Remark.

Using a combination of sources and transformers you can basically transform one source of data into whatever you want as the output.

Creating a TypeDoc Gatsby Source

Don't miss any updates!

No spam and I usually send a newsletter once a quarter with content you won't see on the blog.

About Kamran

I'm a technologist, speaker, and Pluralsight author and I specialize in building full-stack solutions with a focus on modern web technology and cloud native architecture.

Kamran's Pluralsight courses

comments powered by Disqus