Documentation should also teach registering anchors in plugin code

[danielspofford]

Documentation should also teach registering anchors in plugin code

[Josh-Cena]

Hi! You cannot use useBrokenLinks in a plugin file. Plugins are run in Node. You can only use it in a theme component. I think we should explain better how to register anchors directly in the plugin.

[danielspofford]

Appreciate your confirmation @Josh-Cena - I figured as much after continuing my efforts.

I think we should explain better how to register anchors directly in the plugin.

If this is possible can you please point me at anything (docs/source examples/whatever) that would shine some light on how I do that? Exactly what I'm after.

[Josh-Cena]

I somewhat suspect that it's impossible, since right now only the rendering code reports back valid anchors. I'll let @slorber answer though; if it's really not achievable, maybe we should have an API. It sounds useful for plugins that create external HTML pages that don't use Docusaurus themes.

[danielspofford]

I suspect that as well.

It sounds useful for plugins that create external HTML pages that don't use Docusaurus themes.

Yeah that is my exact use case. Was trying to work around rohit-gohri/redocusaurus#321.

The problem for me is that:

• In a plugin:
  • I have access to the external HTML page's content (fs.reads in postBuild), and I can get anchors I would like to collect from it, but I cannot tell docusaurus about those anchors as discussed in this issue.
• In a theme component:
  • I can tell docusaurus about anchors (via useBrokenLinks), but I do not have access to the external HTML page's content, so I cannot get anchors I would like to collect from it.

Just to see if it was possible, I tried to: generate the anchors in the plugin, stick them in global data, and then access them from a theme component so that I could useBrokenLinks. But there is an order of operations problem:

• In order for my plugin to generate the anchors, the external HTML must already exist.
• External HTML will only exist from my plugin's POV at time of postBuild.
• setGlobalData is only available at time of contentLoaded, not in postBuild, so I cannot pass the anchors through because by the time I get them, I cannot setGlobalData.

Regardless of the order of operations problem, it feels wrong to me to serialize and pump that data around in that manner. Seems like allowing for that in plugins like you say would be very nice for this use case.