Find a way to link to category generated-index

slorber commented 2 years ago

Have you read the Contributing Guidelines on issues?

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

Motivation

For docs, we recommend using relative file paths:

For our new category index feature, there is no .md file to link to so we must use regular links.

Problem:

Using an absolute link would not play well with versioning: [Guides](/docs/next/category/guides).
Using a relative link would not play well with changing the trailingSlash setting: [Guides](./category/guides).

This is particularly annoying for our own website, as we use different settings for dogfooding on dev/deployPreview/prod. It is not easy to find a good workaround so that our site could be deployed on every env without reporting broken links 😅 (see workaround https://github.com/facebook/docusaurus/pull/5830/commits/ac44531f61eb53818cf1dd6e30a585a8526ea288)

It may be annoying for our users too.

We should probably find a way to link more easily to a category, but not sure how this should be done 🤷‍♂️

Self-service

[ ] I'd be willing to do some initial work on this proposal myself.

Josh-Cena commented 2 years ago

What about a new useVersionedLink API?

Firstly, I don't think generated category indexes will be linked to very often anyways, so we probably don't need special sugar for this.

Then, the issue is only about how we can programmatically get the link to a doc plugin route, versioned. We have a similar need when we implemented the remark plugin to generate our API documentation: the link currently always links to the current version because the remark plugin is unaware of the version context.

My idea is just a useVersionedLink(url: string, pluginId?: string): string that returns /docs/2.0.0-beta.13/installation from installation. This way, we can do the same thing for all links:

// The plugin baseUrl & version baseUrl will both be prepended
<a href={useVersionedLink('/category/guides')}>Guides</a>

slorber commented 2 years ago

Firstly, I don't think generated category indexes will be linked to very often anyways, so we probably don't need special sugar for this.

🤷‍♂️ I don't know, this makes sense to me to link to them and we already had the case for our own website. We'll see as category indexes grow in usage, for now relative links can be good enough for most users.

useVersionedLink is something related to docs only, and can't really be in core.

Also, I'm not sure we want to require users to use MDX/hooks to handle this use case inside markdown files.

Maybe we could have a docs-only remark plugin and allow to just write [Guides](/category/guides)

If we know that /docs/version/category/guides exist, we rewrite to that absolute path?

🤷‍♂️ that seems quite intuitive to me, but we can as well have a new protocol: [Guides](docs:///category/guides)

Also, I'd find it interesting if our Link was a theme component. This would allow users to implement their own linking specific behaviors at runtime.

Josh-Cena commented 2 years ago

useVersionedLink is something related to docs only, and can't really be in core.

Our docs plugin exports a lot of version-related hooks. This one is no special.

Maybe we could have a docs-only remark plugin and allow to just write [Guides](/category/guides)

We do have a linkifier that transforms file paths to URLs. Maybe we can just use a sugar to indicate category indexes? (like docs:///category/guides but overall I don't like these magic protocols and would just go for an artificial syntax like *category*/guides. Still a bad example but that's the point)

slorber commented 2 years ago

Our docs plugin exports a lot of version-related hooks. This one is no special.

Exposed in a not very elegant way BTW, not sure theming is the best for that. Maybe we should find a better solution like exposing these with https://nodejs.org/api/packages.html#package-entry-points

Note those hooks are not publicly documented for the moment (neither is global data).

The one you are suggesting is meant to be used by end-users so it's not exactly the same.

I don't like magic protocols either but I don't really know how else to do without this.

We also should think about users that will want to opt-out of MDX, and offer them a way to link to category index using plain MD GFM syntax

yoavniran commented 1 year ago

For Uploady's doc site I wanted to link from navbar to an auto-generated category index and realized it wasn't possible. 😢

Luckily, found this issue and the useful comment along with docs explaining how to work around the limitation.

But it definitely feels messy and over-doing something that should have been builtin and declarative.

Sorry if too simplistic, but I was just expecting to have the option to specify a doc ID (in my sidebars.js) to the auto-generated index that I could link to.

gimmebytes commented 1 year ago

I just started out using docusaurus for an internal documentation hub and stumbled over the exact same issue. While writing the outline, I will just use hardcoded links (yikes) but, it would be awesome to just reference docs from the generated index via md, without any magic tricks, as @yoavniran mentioned.

facebook / docusaurus