Intra-page hash links to sections are incompatible with Docusaurus 3.4

[allista]

What package is the bug related to?

typedoc-plugin-markdown

Describe the issue

The plugin generates links to sections in the same document using hash fragments assuming that corresponding IDs are generated by markdown renderer. But there's no way to configure the format of those IDs.

In particular, when the generated markdown is integrated into a docusaurus site, the generated IDs do not match in case a section title contains spaces: docusaurus replaces spaces with -, while the plugin removes the spaces completely.

Docusaurus does not have any means to configure this as well

Example

Generated title and link for a type definition with multiple generic type parameters are as follows:

### MyType\<C, D\>

[`MyType`](README.md#mytypecd)

But docusaurus renders the following (class is ommited):

<h3 id="mytypec-d">MyType&lt;C, D&gt;<a class="hash-link" aria-label="Direct link to MyType<C, D>" title="Direct link to MyType<C, D>" href="/my-lib#mytypec-d">​</a></h3>

TypeDoc configuration

module.exports = {
  name: 'Libraries',
  $schema: 'https://typedoc.org/schema.json',
  // Otherwise the docs will be generated for library types,
  // if those are extended.
  excludeExternals: true,
  // This output directory is also defined in
  // turbo.json: "//#typedoc".outputs[]
  // for caching purposes.
  out: 'docusaurus/docs/Libraries',
  // We do not want to include any top-level readme
  // for the Libraries section.
  readme: 'none',
  // entryDocument: '.no-readme',
  // docusaurus generates TOC for us
  hidePageHeader: true,
  hideBreadcrumbs: true,
  // Each package has its own subsection.
  entryPointStrategy: 'packages',
  plugin: [
    // Generates markdown rather than HTML
    // for docusaurus to consume.
    'typedoc-plugin-markdown',
  ],
  // Custom configurations to restore the flat structure
  outputFileStrategy: 'modules',
  excludeScopesInPaths: true,
  membersWithOwnFile: [],
  mergeReadme: true,
  parametersFormat: 'table',
};

Expected behavior

Expect to either out-of-the-box compatibility with docusaurus or means to configure hash-fragment links structure.

[tgreyuk]

@allista thanks will review this. In the meantime setting "useHTMLAnchors" to "true" should provide a workaround. (This should write anchors to page in expected format).

[allista]

Thanks, this helps. But messes scrolling into view a bit: with an anchor added just above a title, the title itself is always not visible -- scrolled just one "line" too much.

[tgreyuk]

Should be fixed properly in typedoc-plugin-markdown@4.2.2