docusaurus-plugin-typedoc - Ability to do something in between Markdown conversion and final build

[Zamiell]

Hello, and thanks for the excellent plugin.

I don't like some of the things that the plugin is doing, such as naming the root page to "Readme". Specifically, I would prefer it to be named "Introduction".

"No problem", I thought to myself. So I opened up the "docs/api/index.md" file, and changed sidebar_label: "Readme" to sidebar_label: "Introduction".

However, doing this has no effect - the final HTML website is already generated by Docusaurus, so none of the changes that I make to the Markdown files will matter. And if I run npm run build again, it will blow away my changes, because it recreates the Markdown files from scratch from the TypeScript code.

So, I would like this plugin to expose a way to do changes to the Markdown files after they are generated, but before Docusaurus proceeds to convert them into HTML.

Brainstorming: Perhaps the plugin should have an additional option alongside out, tsconfig, readme, and so on. It could be called "afterMarkdownGeneration", or something along those lines. It would take a reference to a function, and then that function would be synchronously called after all of the Markdown files are generated.

[tgreyuk]

Thank you for this.

On the specific point about the readme sidebar label, although not documented can actually already be achieved by adding sidebar.readmeLabel to the plugin options ie:

 sidebar: {
          readmeLabel: 'Introduction',
        },

I take your point about further customisation to the output, TypeDoc already exposes events to achieve the same thing that can be used with custom plugins. I have been also been working on refactoring the code and making it easier to customise and override the Docusaurus theme but not quite there yet.

[Zamiell]

Tom, thanks for the quick reply.

On the specific point about the readme sidebar label, although not documented can actually already be achieved by adding sidebar.readmeLabel to the plugin options

Thanks. I'll try that. Can we document that please? I can submit a PR if you want.

I take your point about further customisation to the output, TypeDoc already exposes events to achieve the same thing that can be used with custom plugins. I have been also been working on refactoring the code and making it easier to customise and override the Docusaurus theme but not quite there yet.

Aye, there are actually many modifications that I want to make to the output, not just the name of the readme. =(

Related: Docusaurus exposes an option called sidebarItemsGenerator that is useful here. (I wanted to customize the sidebar.) But frustratingly, if you specify a specific sidebar label in the sidebarItemsGenerator callback, it won't work, because this plugin also generates a sidebar label in the frontmatter, and the YAML frontmatter "wins".

So, I'm stuck and not sure how to proceed here, I think I might just need to fork the library. I'm also considering just using typedoc-plugin-markdown directly, and then writing a script to modify the Markdown files. Can you give a list of all the things that docusaurus-plugin-typedoc actually does? From comparing the output between "raw" typedoc-plugin-markdown and docusarurus-plugin-typedoc, I see that it is:

1. generating frontmatter (which affects the sidebar)
2. arbitrarily removing the first line, which is the "path" to the Markdown file
3. fixing the title to be more plain
4. arbitrarily removing the table of contents (which presumably isn't needed with Docusaurus because its on the right hand side)

Besides this, I'm curious if there's any other magic that it is doing?

[tgreyuk]

Related: Docusaurus exposes an option called sidebarItemsGenerator that is useful here. (I wanted to customize the sidebar.) But frustratingly, if you specify a specific sidebar label in the sidebarItemsGenerator callback, it won't work, because this plugin also generates a sidebar label in the frontmatter, and the YAML frontmatter "wins".

So another thing you can do ( sorry undocumented again :( ) is to pass sidebar.autoConfiguration=false to the options. This will omit all sidebar related yaml items and also the category.yml files.

 sidebar: {
          autoConfiguration: false,
        },

I will update the readme.

Besides this, I'm curious if there's any other magic that it is doing?

Not really - it is a pretty simple wrapper, the main thing as you say is adding yaml to the pages and setting up default options for docusaurus (removing breadcrumbs, page title etc). As I say the aim is to do make it very easy to customise the theme in the same way as the html theme works.

[Zamiell]

As a small update on this, I ended up deciding to use typedoc-plugin-markdown directly, and then writing a script to modify the Markdown files in an arbitrary way.

In case anyone wants to do something similar, here is my horrible, terrible code: https://github.com/IsaacScript/isaacscript/blob/main/packages/docs/scripts/fixIsaacScriptCommon.ts

I did a small writeup as a summary of the situation:

// Like many open source projects, we use Docusaurus to generate a really nice looking webpage that
// contains hand-written documentation. Additionally, we want to leverage TypeDoc for automatic API
// documentation generation. However, TypeDoc generates a webpage that looks entirely different from
// how the Docusaurus site looks. (And it looks much worse.) In order to get the best end-user
// experience, we want to combine the manually-written documentation together with the
// auto-generated documentation so that everything is in one place.

// The normal way to accomplish this is to use `docusaurus-plugin-typedoc`. Since it is a Docusaurus
// plugin, it invokes TypeDoc for you under the hood, and converts the normal TypeDoc website into
// Markdown using `typedoc-plugin-markdown`. This helpfully abstracts some of the complexity away.

// Unfortunately, by default, the resulting webpage from `docusaurus-plugin-typedoc` is
// unsatisfactory, with all of the modules in the same directory, and other imperfections.

// To work around this problem, we can invoke TypeDoc ourselves using `typedoc-plugin-markdown`.
// Then, we can use a script to manually mutate the Markdown files in specific ways. (This is the
// point of the following script.) After that, we feed the "fixed" Markdown content to Docusaurus,
// alongside the non-auto-generated documentation, generating the entire site at once.

// One disadvantage of this method is that since we are manually moving the paths, all of the links
// will break. Thus, we must also manually adjust all of the links.

// In order for this script to work correctly, several options must be used to configure TypeDoc and
// `typedoc-plugin-markdown`; see "typedoc.json".

Some day, it would be fantastic for the plugin to support some of this stuff directly via configuration options, or by reading JSDoc tags in the actual source code.

[tgreyuk]

https://www.typedoc-plugin-markdown.org/docs/customizing-output