Documentation should also teach registering anchors in plugin code

[danielspofford]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

• I am currently getting warnings from onBrokenLinks/onBrokenAnchors. This is what I am ultimately trying to fix.
• Docusaurus doesn't know about them because they link to content that is generated at build time by another plugin that is incapable of using official Link/etc components that track this automatically.
• Docusaurus docs push me in the direction of https://docusaurus.io/docs/docusaurus-core#useBrokenLinks to handle a scenarios like this.
• Problem is I cannot seem to useBrokenLinks in a plugin. Hopefully I am just doing something wrong, but I am not even sure if I am supposed to be able to use this functionality in a plugin given "Docusarus Client API"; does that mean that functionality cannot be used in plugins?

In any case: is it possible to useBrokenLinks in a plugin? If yes, how/what am I doing wrong? If no, is it possible to solve my problem with a plugin (inform docusaurus of routes that are valid so that it doesn't warn/throw on them with onBrokenLinks/onBrokenAnchors).

Reproducible demo

https://codesandbox.io/p/devbox/jovial-benji-f4599g

Steps to reproduce

1. Add a no-op plugin that tries to import useBrokenLinks like the codesandbox has at src/plugins/foo/index.js.
2. Add the plugins: ['src/plugins/foo'] to docusuarus config.

If using the codesandbox link I provide - the above steps are already done (and are the only changes to the sandbox). The project as-is in there will fail to build.

Expected behavior

I hoped to use useBrokenLinks in a plugin to inform docusaurus about anchors/links that it should consider valid to stop receiving false onBrokenLinks/onBrokenAnchors warnings.

Actual behavior

Docusaurus fails to build - it cannot resolve the import of useBrokenLinks in a plugin.

  [cause]: Error: Docusaurus could not load module at path "myproject/src/src/plugins/foo/index.js"
  Cause: Cannot find module '@docusaurus/useBrokenLinks'

Long form: https://gist.github.com/danielspofford/17993f7c77319d3639d52a8fd9f28fc3.

Your environment

• Public source code: https://codesandbox.io/p/devbox/jovial-benji-f4599g
• Public site URL: https://codesandbox.io/p/devbox/jovial-benji-f4599g
• Docusaurus version used: 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Version 123.0.6312.58 (Official Build) (arm64)
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS 14.3.1

Self-service

• I'd be willing to fix this bug myself.

[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.

[slorber]

@danielspofford it would greatly help me if you provided a minimal repro that reports broken anchors that you would like to solve. This way, I could see how to fix that repro so that those anchors do not get reported anymore.

Your repro just shows an attempt to import a React hook in Node.js code, something that is illegal). I can't act on it, and fix the problem, because the problem is not showcased in the first place. Show me the problem and I'll help fix it. Seeing a runnable sandbox of your setup that actually reports wrong broken anchors is more helpful than explaining things in text form.

[danielspofford]

@slorber here is a minimal repro that reports broken anchors that I would like to solve.

https://codesandbox.io/p/devbox/distracted-cache-7xxfh5

example output

[danielspofford]

@slorber here is an updated minimal repro with latest versions that reports broken anchors on yarn build.

https://codesandbox.io/p/devbox/sharp-gagarin-5jqtrn

Please advise.

[slorber]

@danielspofford if you are using a third-party package such as redocusaurus, it can't be considered a minimal repro.

I can only help you figure out how to fix the problem if the problem is not nested inside an external package. The underlying problem is that Redocusaurus is not collecting rendered anchors, tracked in rohit-gohri/redocusaurus#321.

Until it supports that, you can disable the broken anchor's checker.

---

Eventually we could extend the broken anchor checker with additional options to give you the flexibility to ignore Redocusaurus broken links, until it supports this.

For example:

onBrokenAnchors: (brokenAnchors) => {
  // do whatever you want with them, throw, filter or ignore
},

[brunomartinspro]

@danielspofford if you are using a third-party package such as redocusaurus, it can't be considered a minimal repro.

I can only help you figure out how to fix the problem if the problem is not nested inside an external package. The underlying problem is that Redocusaurus is not collecting rendered anchors, tracked in rohit-gohri/redocusaurus#321.

Until it supports that, you can disable the broken anchor's checker.

Eventually we could extend the broken anchor checker with additional options to give you the flexibility to ignore Redocusaurus broken links, until it supports this.

For example:

onBrokenAnchors: (brokenAnchors) => {
// do whatever you want with them, throw, filter or ignore
},

@slorber @Josh-Cena this would be the best solution possible for multiple use cases, is there a current available solution like this?
I'm currently using the Link component for redocusaurus URL fragments, but i also get a broken link when running the docusaurus build command.

Usage

Component.tsx

import Link from '@docusaurus/Link';
import useBrokenLinks from '@docusaurus/useBrokenLinks';
...
     const CustomButton: React.FC<Props> = ({ link }: Props) => {
    
          if(link.startsWith("/apis") && link.includes("#")) {
            useBrokenLinks().collectLink(link);
          }

          return (
              <Link to={link}>Example</Link>
          );
    };
...

But i still get:

- Broken anchor on source page path = /apis/:
   -> linking to /apis/payment-gateway/#tag/Transaction/operation/ProcessPayment
   -> linking to /apis/user-management/#tag/Profiles/paths/~1users~1{userId}~1settings~1privacy~1update/post