Allow specifying a custom heading id (anchor link) for '#' headings

[novusnota]

Current situation

Mintlify generates heading IDs automatically, based on the heading text. For example, ### Hello World will have ID hello-world, and the links to that heading anchor would look like [](/current/page/url#hello-world).

Generated IDs have some limitations:

• The ID might not look good or be too verbose.
• One might want to change or translate the text without updating the existing ID

A limitation of the first point can be illustrated by, say, a reference page that can describe a number of operation codes and uses a lot of headings on it. Each of the headings might look like ## Number: Brief description.

In that situation, it would be best to make each anchor link be a simple number, while still allowing the heading to have additional descriptions. Like, that the anchor links would be #12 or #42, but not #12-brief-description-1 or #42-brief-description-2.

Proposed solution

Popular documentation tools allow for a special Markdown syntax that lets one set an explicit heading id. Here's an example:

### Hello World {#my-explicit-id}

There, heading and table of contents on the side would still display "Hello World", while the actual anchor link to that heading would be #my-explicit-id.

Prior art

Documentation tools or frameworks that use the more common {#heading-id} syntax:

• Docusaurus (called "explicit heading IDs")
• Starlight (Astro)

Documentation tools or frameworks that use the less common [#heading-id] syntax:

• Nextra (Next.js theme)

[mdrxy]

+1