Could use support upgrading our Docusaurus project to v4

[favna]

Hi there,

I tried updating the repository https://github.com/sapphiredev/website to typedoc-plugin-markdown v4 + docusaurus-plugin-typedoc v1 but I'm having issues with the markdown that the plugin outputs. When Docusaurus next picks up the markdown, it gives me rendering errors.

I have created a branch and draft PR with my changes so far here: sapphiredev/website#256

Keep in mind when cloning this repository you have to add --recurse-submodules because the typedoc is generated for various submodules.

The error I am currently getting:

ERROR in ./docs/Documentation/api-framework/classes/Plugin.md
Module build failed (from ./node_modules/@docusaurus/mdx-loader/lib/index.js):
Error: MDX compilation failed for file "F:\sapphiredev\website-main\docs\Documentation\api-framework\classes\Plugin.md"
Cause: Markdown link URL is mandatory in "docs/Documentation/api-framework/classes/Plugin.md" file (title: postInitialization, line: 15).
Details:
Error: Markdown link URL is mandatory in "docs/Documentation/api-framework/classes/Plugin.md" file (title: postInitialization, line: 15).
    at processLinkNode (F:\sapphiredev\website-main\node_modules\@docusaurus\mdx-loader\lib\remark\transformLinks\index.js:121:15)
    at F:\sapphiredev\website-main\node_modules\@docusaurus\mdx-loader\lib\remark\transformLinks\index.js:144:27
    at overload (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit/lib/index.js:311:12)
    at node (link) (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit-parents/lib/index.js:346:27)
    at node (heading) (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit-parents/lib/index.js:363:61)
    at node (root) (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit-parents/lib/index.js:363:61)
    at visitParents (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit-parents/lib/index.js:304:31)
    at visit (file:///F:/sapphiredev/website-main/node_modules/unist-util-visit/lib/index.js:302:3)
    at F:\sapphiredev\website-main\node_modules\@docusaurus\mdx-loader\lib\remark\transformLinks\index.js:143:9
    at Object.mdxLoader (F:\sapphiredev\website-main\node_modules\@docusaurus\mdx-loader\lib\loader.js:130:25)

And another error I get is:

Error: MDX compilation failed for file "F:\sapphiredev\website-main\docs\Documentation\api-framework\interfaces\SapphireClientOptions.mdx"
Cause: Unexpected character `\` (U+005C) in attribute name, expected an attribute name character such as letters, digits, `$`, or `_`; `=` to initialize a value; whitespace before attributes; or the end of the tag
Details:
{
  "column": 87,
  "message": "Unexpected character `\\` (U+005C) in attribute name, expected an attribute name character such as letters, digits, `$`, or `_`; `=` to initialize a value; whitespace before attributes; or the end of the tag",
  "line": 303,
  "name": "303:87",
  "place": {
    "line": 303,
    "column": 87,
    "offset": 7514,
    "_index": 0,
    "_bufferIndex": 84
  },
  "reason": "Unexpected character `\\` (U+005C) in attribute name, expected an attribute name character such as letters, digits, `$`, or `_`; `=` to initialize a value; whitespace before attributes; or the end of the tag",
  "ruleId": "unexpected-character",
  "source": "micromark-extension-mdx-jsx",
  "url": "https://github.com/micromark/micromark-extension-mdx-jsx#unexpected-character-at-expected-expect"
}

The generated markdown for the first error is:

# Class: `abstract` Plugin

## Constructors

### new Plugin()

> **new Plugin**(): [`Plugin`](Plugin.mdx)

#### Returns

[`Plugin`](Plugin.mdx)

## Properties

### [postInitialization]()?

> `static` `optional` **[postInitialization]**: (`this`, `options`) => `void`

#### Parameters

• **this**: [`SapphireClient`](SapphireClient.mdx)\<`boolean`\>

• **options**: [`ClientOptions ↗️`]( https://discord.js.org/docs/packages/discord.js/main/ClientOptions:Interface )

#### Returns

`void`

#### Source

[projects/framework/src/lib/plugins/Plugin.ts:10](https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/src/lib/plugins/Plugin.ts#L10)

***

### [postLogin]()?

> `static` `optional` **[postLogin]**: (`this`, `options`) => [`Awaitable`](../type-aliases/Awaitable.mdx)\<`void`\>

#### Parameters

• **this**: [`SapphireClient`](SapphireClient.mdx)\<`boolean`\>

• **options**: [`ClientOptions ↗️`]( https://discord.js.org/docs/packages/discord.js/main/ClientOptions:Interface )

#### Returns

[`Awaitable`](../type-aliases/Awaitable.mdx)\<`void`\>

#### Source

[projects/framework/src/lib/plugins/Plugin.ts:12](https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/src/lib/plugins/Plugin.ts#L12)

***

### [preGenericsInitialization]()?

> `static` `optional` **[preGenericsInitialization]**: (`this`, `options`) => `void`

#### Parameters

• **this**: [`SapphireClient`](SapphireClient.mdx)\<`boolean`\>

• **options**: [`ClientOptions ↗️`]( https://discord.js.org/docs/packages/discord.js/main/ClientOptions:Interface )

#### Returns

`void`

#### Source

[projects/framework/src/lib/plugins/Plugin.ts:8](https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/src/lib/plugins/Plugin.ts#L8)

***

### [preInitialization]()?

> `static` `optional` **[preInitialization]**: (`this`, `options`) => `void`

#### Parameters

• **this**: [`SapphireClient`](SapphireClient.mdx)\<`boolean`\>

• **options**: [`ClientOptions ↗️`]( https://discord.js.org/docs/packages/discord.js/main/ClientOptions:Interface )

#### Returns

`void`

#### Source

[projects/framework/src/lib/plugins/Plugin.ts:9](https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/src/lib/plugins/Plugin.ts#L9)

***

### [preLogin]()?

> `static` `optional` **[preLogin]**: (`this`, `options`) => [`Awaitable`](../type-aliases/Awaitable.mdx)\<`void`\>

#### Parameters

• **this**: [`SapphireClient`](SapphireClient.mdx)\<`boolean`\>

• **options**: [`ClientOptions ↗️`]( https://discord.js.org/docs/packages/discord.js/main/ClientOptions:Interface )

#### Returns

[`Awaitable`](../type-aliases/Awaitable.mdx)\<`void`\>

#### Source

[projects/framework/src/lib/plugins/Plugin.ts:11](https://github.com/sapphiredev/framework/blob/35b7e1674db4d3430b841494b9066b2f581f4f62/src/lib/plugins/Plugin.ts#L11)

The markdown outputs headers with ### [Text]()? when this should probably just be ### Text, especially considering the TS file that this is for:

import type { Awaitable } from '@sapphire/utilities';
import type { ClientOptions } from 'discord.js';
import type { SapphireClient } from '../SapphireClient';
import { postInitialization, postLogin, preGenericsInitialization, preInitialization, preLogin } from './symbols';

// eslint-disable-next-line @typescript-eslint/no-extraneous-class
export abstract class Plugin {
	public static [preGenericsInitialization]?: (this: SapphireClient, options: ClientOptions) => void;
	public static [preInitialization]?: (this: SapphireClient, options: ClientOptions) => void;
	public static [postInitialization]?: (this: SapphireClient, options: ClientOptions) => void;
	public static [preLogin]?: (this: SapphireClient, options: ClientOptions) => Awaitable<void>;
	public static [postLogin]?: (this: SapphireClient, options: ClientOptions) => Awaitable<void>;
}

All things said, what I'm looking for is support for getting the website to build correctly again but with the updated plugins. I honestly have no idea where to start so I figured I'd start by posting here.

If I manually clear the generated Plugin.mdx file then the website does render, however I also notice a few other annoying bits of the new updated:

1. We get various entries called "index". This appears to happen when the readme option was configured
   
2. This gets even worse for our monorepos:
   
3. Every page inside each of the groups (classes, functions, etc) has a prefix for the page title matching that group, for example classes/Class Something. This is completely unnecessary and makes the sidebar much much harder to read.

To give an idea, this is how I would expect my sidebar to get rendered:

The changes here are:

• No Class: prefix
• No unnecessary escaping of < and >
• The name of the monorepo module right below @sapphire
• No entry @sapphire/plugin-api that's just a list of all the exports (the user already gets this in the sidebar!)
• A custom label for the top level sidebar entry, like was possible in v0.x through sidebar.categoryLabel

[tgreyuk]

Hi @favna,

Thank you for the feedback.

The parsing was due to a bug resolving symbols which is now fixed (typedoc-plugin-markdown@4.0.1).

For the sidebar we no longer recommend an autogenerated sidebar configuration (it was brittle and not easy to customize). We now build out a json sidebar.

Please update your sidebar file and replace the sidebar with this and it should resolve your issues:

[favna]

Thanks very much! This all works perfectly. I went through the most obvious issues now with links that needed changing in our written guide section and I'm gonna go through once more check to check every single link now and once that's done the repo will be updated.

I have so say, big kudos to all the work. The generated docs look MUCH MUCH better now. I especially love that functions, variables, and enums are finally properly documented. The amount of times we've had people ask where to find something like https://sapphirejs.dev/docs/Documentation/api-framework/#events is uncalculable.

[tgreyuk]

Fantastic. Please do continue to raise feedback, ideas for improvements etc.

[tgreyuk]

As code:

{
			type: 'category',
			label: 'Documentation',
			collapsed: true,
			items: [
				{
					type: 'category',
					label: '@sapphire/framework',
					items: require('./docs/Documentation/api-framework/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: '@sapphire/pieces',
					items: require('./docs/Documentation/api-pieces/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: '@sapphire/pieces',
					items: require('./docs/Documentation/api-pieces/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: 'Sapphire Utilities',
					items: require('./docs/Documentation/api-utilities/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: 'Sapphire Plugins',
					items: require('./docs/Documentation/api-plugins/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: '@sapphire/type',
					items: require('./docs/Documentation/api-type/typedoc-sidebar.cjs')
				},
				{
					type: 'category',
					label: '@sapphire/shapeshift',
					items: require('./docs/Documentation/api-shapeshift/typedoc-sidebar.cjs')
				}
			]
		}