Docusaurus V3 plugin - Add fragments to header (H2, H3, ...) links

[dezlitz]

Problem Description

Docusaurus automatically adds id props to all header tags except for H1. Currently the plugin picks up each header as a section but only puts the file path in the url without a fragment.

Proposed Solution

The plugin could be modified to automatically add a fragment to all header sections (except for H1). The fragment is calculated from the header text:

Before you start -> #before-you-start

Also special characters are removed:

1. Setup -> #1-setup

Alternatives

No response

Additional Context

The function that needs to be modified is this one:

https://github.com/askorama/orama/blob/main/packages/plugin-docusaurus-v3/src/index.ts#L251-L274

If there are no objections to the proposed solution I am happy to create a PR.

[dezlitz]

Need to support explicit ids also: ### Hello World {#my-explicit-id}

This is how docusaurus does it: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-utils/src/markdownUtils.ts

So I'm thinking:

• Extract the explicit ID if it exists then strip it from the title.
• If no explicit ID, use the same slugify function to generate it.

[dezlitz]

Here is my first attempt: 456fb63fa4bba79972298ff2aecccfd8b138a286

It adds the fragments but for some reason when you click on the search result it doesn't jump down to the fragment id.

Edit: I think this is because I am in dev mode docusaurus start therefore the initial page load doesn't have the id rendered yet. Fragments should be fine in prod mode docusaurus serve but unfortunately when I search I get Not found network errors when i run in prod mode as I am running the Orama OSS version. If you are using Orama Cloud mode it should work correctly but I haven't tested it.

Need to work out how to hijack the search function when working in OSS mode so it loads the index in browser instead of making a network call.

[dezlitz]

Okay after more investigation it looks like when using docusaurus start it works in browser as expected with no network calls, however when using docusaurus serve it starts trying to hit the remote server again. Most likely a configuration issue somewhere.

Edit: Found a fix for the frontend component as well.

[micheleriva]

That should be fixed by #755