docusaurus

docusaurus copied to clipboard

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] I'm using the latest version of Docusaurus.
• [X] 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.
• [X] I have read the console error message carefully (if applicable).

Description

The "file path" type of link does not seem to function for Pages.

Reproducible demo

https://github.com/ISSOtm/rgbds-www/blob/bf8d9167382a92f3e3db9a9c770f4ea8c78429d4/src/pages/install/linux.md?plain=1#L4

Steps to reproduce

1. Edit the "demo" link from /install to index.md or ./index.md.

Expected behavior

The documentation only mentions that inter-plugin links don't work, but both of those pages are processed by the "pages" plugin; so I'd expect "file path" links to be converted appropriately.

I want to use "file path" links instead of relative URLs, so that I can benefit from all of the upsides listed at the bottom of the page ;P

Actual behavior

The generated link is localhost:3000/install/index.md, not localhost:3000/install (or equivalent).

Your environment

• Public source code: https://github.com/gbdev/rgbds
• Public site URL: https://rgbds.gbdev.io
• Docusaurus version used: 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node v21.6.2
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Arch Linux

Self-service

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

Yes we never added this support. Curious what your use case is? I think most people just use docs anyway, with navigation disabled if necessary. I haven't seen much demand for standalone Markdown pages at all, let alone cross-linking ones.

Our use case is our install instructions; the linked example is the Windows instructions redirecting to Linux for WSL.

Stand-alone pages seem more useful than docs for this purpose, as the install instructions are mostly version-agnostic. And if a new install method becomes available, then there are no duplicates to forget to sync.

I see. Maybe you should use https://docusaurus.io/docs/docs-multi-instance instead? Pages are mostly useful for marketing instead of informative purposes. Nevertheless we should probably implement feature parity for this.

Yes, that would be nice to support relative md paths in pages, but also the blog plugin.

And to allow one plugin to reference files of another. For that we probably need new plugin lifecycle hooks to allow one plugin to resolve a file path to the final url/pathname of another plugin.

Yes, that would be nice to support relative md paths in pages, but also the blog plugin.

Right, I suppose it's only implemented in the docs plugin, then? IMO, an immediate action would be to mention that in the documentation, to reduce astonishment for people like me. (I'll admit, though, that I've been sitting on this for a while... :sweat_smile:)

And to allow one plugin to reference files of another. For that we probably need new plugin lifecycle hooks to allow one plugin to resolve a file path to the final url/pathname of another plugin.

Right; this seems to already be requested in #9117. I think it'd be best to avoid duplicating discussion between issues?

Yes, that would be nice to support relative md paths in pages, but also the blog plugin.

Right, I suppose it's only implemented in the docs plugin, then? IMO, an immediate action would be to mention that in the documentation, to reduce astonishment for people like me. (I'll admit, though, that I've been sitting on this for a while... 😅)

Hmmm, I was wrong, it seems we also implemented it in the blog plugin 😅 so only the page plugin doesn't have it.

If you find a good place to add it to the page docs, don't hesitate to send a PR. Although I'm not sure it's necessary since we want to implement it and nobody apart you complained so far 😅

And to allow one plugin to reference files of another. For that we probably need new plugin lifecycle hooks to allow one plugin to resolve a file path to the final url/pathname of another plugin.

Right; this seems to already be requested in #9117. I think it'd be best to avoid duplicating discussion between issues?

Agree, let's keep https://github.com/facebook/docusaurus/issues/9117 for inter-plugin file path links resolution.