Skip to content

Alternative architecture for plugin

Hi, I'm a colleague of Rieks from TNO. There is a wish to support referencing external terms (i.e. contained in a different docusaurus project). There are also some issues with the current implementation of the glossary/terminology plugin.

Currently the plugin does what is essentially a grep+replace of %%term|term%% combinations. It then hardcodes <Term /> react components into the resulting MDX and actually overwrites the source files in the docusaurus project.

This is problematic for a couple of reasons. First of all, only after compiling/parsing a markdown document for terms, you can actually see the result of adding terms to your document. During writing/development, you will only see %%blah|blah%% which does not exactly help with the speed of feedback. You need to commit, parse, check output, rollback during development, which is not an ergonomic process.

I agree with issue #4 that the syntax is also rather obscure.

I think a different approach could remove a lot of current code, and make the whole process of term definition simpler.

  1. Adopt an existing link-like syntax, for instance [my text](%term). This would mean we can use existing markdown parsing capabilities of docusaurus/remark instead of writing our own. Using the existing syntax could be achieved by extending the remark markdown syntax, but it would require some extra work.
  2. Rewrite term insertion code to be a remark plugin. Combined with the step above, this allows to easily visit markdown link nodes and replace them with a Term react component, see the image replacer in docusaurus.
  3. Use a Term component that is only passed the term and a label <Term label="my-term">My text here</Term>. This means we do not need to put information fetch logic into the markdown parser/transformer.
  4. Use react hooks to fetch hover information in Term components. This hook is responsible for mapping my-term to the actual hover text and a link to the term page.

This information would need to come from somewhere. I have not yet investigated the glossary generation all too much. I'll have another look and update this issue once I have a better idea of what would be possible here.