Gatsby plugins

APIdocs implementation consists of the following Gatsby plugins:

• @carrotsearch/gatsby-theme-apidocs: a Gatsby theme that implements APIdocs user interface, including navigation menus, search box, logo and footer customization options. The theme also imports all the required plugins described below.

• @carrotsearch/gatsby-transformer-html: a Gatsby transformer plugin for authoring content in HTML.

  One functional area of the plugin is enriching raw HTML content by:

  • rewriting local links to point to the generated Gatsby pages,

  • adding section anchor links,

  • processing linked images into multi-resolution responsive img tags,

  • applying Prism.js highlighting to code blocks,

  • embedding code examples from external files,

  • adding synthetic identifiers to paragraph to make it possible to link to them from content search results.

  Another functional area of the plugin is extracting paragraph-sized text snippets from the page, so that they can be indexed in a client-side in the client-side text search implemented by the gatsby-plugin-content-search plugin

  The enriched HTML and lists of extracted text snippets are available in Gatsby's GraphQL model for use by other plugins.

• @carrotsearch/gatsby-plugin-content-search: a Gatsby plugin that takes all the text snippets extracted by the HTML transformer plugin and builds a fuzzysortindex for them. Based on that index, a client-side Sublime-like searches can be applied to all the content in your documentation site.

• @carrotsearch/gatsby-plugin-relativize: a Gatsby plugin that post-processes the output to remove the dependency on absolute URLs. The post-processed site should work when deployed at any URL prefix.

Additionally, the @carrotsearch/gatsby-theme-apidocs theme uses the following plugins:

• gatsby-source-filesystem,
• gatsby-plugin-react-helmet,
• gatsby-plugin-dark-mode,
• gatsby-plugin-offline,
• gatsby-plugin-catch-links.

Why not Markdown?

The majority of Gatsby plugins seems to be centered around Markdown, we also tried it for the initial prototypes of APIdocs. While Markdown has many advantages, such as concise syntax, we found it hard to use for more complex technical documentation:

• Missing features. We wanted to be able to output HTML with arbitrary CSS classes. This is possible through a plugin, but makes the syntax ugly. There is no standard Markdown support for definition lists. This could probably be patched by adding more ugly syntax.

• Post-processing. To implement client-side search, we'd have to post-process the HTML generated by Markdown. We felt that if we decide to post-process things, we'd rather post-process simple semantic HTML source content rather than Markdown-generated HTML.

• Previewing source content. HTML files can be previewed directly in the browser, IDE support for advanced editing and refactoring is probably better for HTML too.