Building a Powerful Docs Site for a Front‑End Graphics Engine with Gatsby

When you watch the Vue.js documentary, you realize that the success of an open‑source product depends not only on quality code but also on clear documentation, appealing design, continuous iteration, regular evangelism, and influential backers. This article shares the lessons learned while building the documentation site for the Oasis Engine graphics engine.

Selection

Before the open‑source release we stored documentation on Yuque , which is good for knowledge management but cannot handle complex API docs or custom designs. We needed an independent site.

Most open‑source projects host their docs on GitHub Pages . After researching we evaluated several static site generators:

Jekyll : official GitHub Pages choice but requires Ruby, which is cumbersome on macOS.

VuePress : a Vue‑based framework limited to Markdown data sources.

Dumi : a React‑based framework for component libraries; its dumi‑theme‑mobile is attractive but its demo preview is tightly coupled to components and its default style is rough.

Docsify : a lightweight generator that can parse Markdown at runtime without a build step, offering Gitbook‑like features.

We ultimately chose Docsify for rapid deployment, even though it was a hurried decision.

Implementation Overview

To unify API docs (generated by TypeDoc ), tutorial docs (Markdown), and demos (TypeScript) into a single site with global search, we built a pipeline using Gatsby :

Integration : Use gatsby-source-typedoc to read TypeDoc data and expose it via GraphQL.

Demo Embedding : Create a custom gatsby-remark-oasis plugin that extracts <playground src="..."> tags from Markdown AST, reads the source file, highlights it with Prismjs , and injects the rendered HTML.

Component Conversion : Use gatsby-remark-component-parent2div to turn the custom <playground> tag into a React component.

Page Generation : In gatsby-node.js we query the GraphQL data, parse the JSON from TypeDoc, and programmatically create pages for each API module and demo.

Key code snippets:

export const pageQuery = graphql`
  typedoc(typedocId: { eq: "default" }) {
    internal { content }
  }
`

export default function MyPage({ data: { typedoc } }) {
  const typedocContent = JSON.parse(typedoc?.internal.content);
  // do something with that data...
}

TypeDoc enum definitions (used by the renderer):

export enum Kinds {
  MODULE = 1,
  ENUM = 4,
  CLASS = 128,
  INTERFACE = 256,
  TYPE_ALIAS = 4194304,
  FUNCTION = 64,
  PROPERTY = 1024,
  CONSTRUCTOR = 512,
  ACCESSOR = 262144,
  METHOD = 2048,
  GET_SIGNATURE = 524288,
  SET_SIGNATURE = 1048576,
  PARAMETER = 32768,
  TYPE_PARAMETER = 131072,
}

Generating the list of entry files for TypeDoc:

const glob = require('glob');
const fs = require('fs');

glob(`${EngineRepoPath}/packages/**/src/index.ts`, { realpath: true }, function (er, files) {
  const tsFiles = files.map(file => `"${file}"`);
  fs.writeFile('./scripts/typedoc/tsfiles.js', `module.exports = [${tsFiles.join(',')}];`, function (err) {});
});

Configuring the plugin in gatsby-config.js:

const DTS = require('./scripts/typedoc/tsfiles');
module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-typedoc",
      options: { src: DTS, typedoc: { tsconfig: `${typedocSource}/tsconfig.json` } }
    }
  ]
};

Embedding demos in Markdown is as simple as writing:

<playground src="pbr-helmet.ts"></playground>

The custom plugin replaces this tag with a highlighted code block and an iframe preview, eliminating the need for separate demo pages.

Global Search

To help developers locate information across the massive API surface, we integrated Algolia DocSearch . After obtaining an API key, we added a configuration file to the docsearch-configs repository, specifying URL patterns and HTML selectors for hierarchical indexing.

{
  "start_urls": [{
    "url": "https://oasisengine.cn/(?P<version>.*?)/docs/.+?-cn",
    "variables": { "version": ["0.3"] },
    "tags": ["cn"]
  }],
  "selectors": {
    "lvl0": { "selector": ".docsearch-lvl0", "global": true, "default_value": "Documentation" },
    "lvl1": "article h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5",
    "text": "article p, article li"
  }
}

After deploying the search widget, developers can instantly find API references, tutorial sections, and demo code.

Conclusion

The documentation site for Oasis Engine required unifying diverse data sources, building custom Gatsby plugins, and adding global search. Along the way we learned the power of GraphQL, the flexibility of static site generators, and the importance of a well‑designed documentation experience for front‑end developers.