Port and update Wikilink Docusaurus plugin

[seanmakesgames]

description

integrate the wikilink docusaurus plugin into our wiki
requires a preprocessing step which lists out pages as available for the plugin

tests?

• unit tests

implementation?

• remark, rehype plugin, and/or docusaurus plugin

how to validate?

• PR review of tests and manual testing of linking samples

dependencies?

• Upgrade Docusaurus from ^2.4.3 to ^3.0.0 #34

[tukib]

Had a shot at this, but I got stuck trying to access the list of pages within a custom remark plugin (which wrapped remark-wiki-link). We could crawl files but this isn't ideal as plugin-content-docs definitely keeps context of these.

One solution I can think is to wrap plugin-content-docs so we can pass in the page list / sitemap, but I'd like to check with others before continuing as it does seem over the top. Another could be to have react components responsible for this, but it wouldn't be my first pick.

[danswann]

Wrapping plugin-content-docs is probably the most runtime-efficient solution, since it has already walked the /docs directory and parsed the frontmatter, but I think it is also by far the least maintainable.

While I agree that crawling the /docs directory again ourselves isn't ideal, I don't see adding a little bit of build time as a horrible problem, especially if it's done with asynchronous code.

Instead of stuffing all the functionality into a wrapper around the remark plugin, I'd recommend looking into creating our own Docusaurus plugin to load all the data using their existing lifecycle infrastructure (loadContent(), contentLoaded(), and getPathsToWatch() to make it only re-run on the dev server when changes have been made to files in /docs). Then we'd be able to process the data we need and pass it straight to the vanilla remark-wiki-link.

It might also be possible (if undocumented) to get access to other Docusaurus plugins' context from within a different plugin. Might be worth looking at some of their bundled presets, like docusaurus-preset-classic to see if there is any useful interop between all the plugins that preset comes with.

I'm not sure I understand how you'd implement this in React components without sending a whole map of link text -> URL to the client, at which point we'd still have to figure out how to make that map.