search

diffbot / docs

Diffbot Documentation Suite
5 stars 18 forks source link

KG Ontology as Markdown Files #111

Closed jeromechoo closed 3 years ago

jeromechoo commented 3 years ago

The current ontology is sourced from ThothEntities, built into tables with jQuery, and then iframed into docs.diffbot.com.

This presents a few issues:

  1. Algolia search does not work for the ontology. Making it confusing to users.
  2. The multi-layered complexity presents issues when it comes to keeping documentation fresh and updated.
  3. Front-end load times are very slow (while processing the JSON into the DOM)

This solution aims to solve the above by:

  1. Building semantic markdown files for the ontology.
  2. Decoupling front-end and back-end for the ontology. Programmatically generated markdown files now host the front-end, while the backend (JSON ontology) continues to be updated by the respective maintainers
  3. Since the ontology is rendered as static markdown files, there is no performance hit

There are instructions to build in ./website/generateOntology.js and appended to the README.

jeromechoo commented 3 years ago

I don't know what our CD pipeline looks like right now, but it would be ideal if we could just add node generateOntology in there somewhere so we don't have to worry about fresh ontology again :)