How to modify the categories and files titles?

[SalahAdDin]

I'm using this plugin combined with the docusaurus one for building our project documentation.

I managed to customized it to have it enough on the documentation structure we have, but there are still some issues we have to fix:

1. How can we programmatically modify either the files or the side bar to make category titles capitalized and also to put the introduction file at first?
2. How can we remove the category prefix title from the generated files?

My current configuration, i.e., typedoc.config.cjs, is:

const config = {
  name: "API",
  out: "api",
  entryPointStrategy: "expand",
  entryPoints: ["../src"],
  tsconfig: "../tsconfig.json",
  plugin: [
    "typedoc-plugin-merge-modules",
    "typedoc-plugin-missing-exports",
    "typedoc-plugin-markdown",
  ],
  readme: "none",
  excludeExternals: true,
  placeInternalsInOwningModule: true,
  mergeModulesRenameDefaults: true,
  mergeModulesMergeMode: "project",
  outputFileStrategy: "members",
};

And the side bar is:

const sidebars: SidebarsConfig = {
  tutorialSidebar: [{ type: "autogenerated", dirName: "." }],
  API: [
    {
      type: "autogenerated",
      dirName: "api", // 'api' is the 'out' directory
    },
  ],
};

[tgreyuk]

Hello. Auto sidebar configuration is not going to work in next versions. You need to reference the generated sidebar - see https://typedoc-plugin-markdown.org/integrations/docusaurus/guides/sidebar.

[SalahAdDin]

Could you please expand on this (not sure i fully understand).

The config setup for that does not include a typescript version and gives a linting error: 25:7 Error: Unsafe assignment of an any value. @typescript-eslint/no-unsafe-assignment

I had to define the types as follows:

const sidebars: SidebarsConfig = {
  mainSidebar: [{ type: "autogenerated", dirName: "." }],
  typedocSidebar: [
    {
      type: "category",
      label: "API",
      link: {
        type: "doc",
        id: "api/index",
      },
      items: typeDocSideBar as SidebarsConfig,
    },
  ],
};

I found an issue with this solution and it is:

sidebars.ts:3:28 - error TS2307: Cannot find module './docs/api/typedoc-sidebar.cjs' or its corresponding type declarations.

3 import typeDocSideBar from "./docs/api/typedoc-sidebar.cjs";
                             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

That file must exist before running Docusaurus! We don't save the API folder cause it is always autogenerated, but from this issue, it seems we will need to save that file.

[tgreyuk]

I can't actually replicate this behaviour. The sidebar should be built before that code is executed. I don't suppose your repo is public?

[SalahAdDin]

I'm not talking about the Docusaurus sidebar file, but that one generated by this plugin: it needs to exist before running Docusaurus, but only if I want to type import it (and I want to do it to avoid linter issues with require statement); I'm still unable to import it in the right way.

[tgreyuk]

Yes I understand what you are saying. What i am saying is that i can nuke the entire docs folder and start again (with reference is sidebars.ts) and I can't replicate your issue. This repo imports sidebar in the way you describe - https://github.com/tgreyuk/docusaurus-plugin-typedoc-example . Again, in order to understand why it is happening in your use-case it would be good to see your project.

[SalahAdDin]

It could be related to my .eslint.rc config:

"extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/strict-type-checked",
    "plugin:@typescript-eslint/stylistic-type-checked",
    "plugin:storybook/recommended",
    "plugin:sonarjs/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/array-type": [
      "error",
      {
        "default": "generic"
      }
    ],
    "@typescript-eslint/ban-ts-comment": [
      "error",
      {
        "ts-expect-error": "allow-with-description"
      }
    ],
    "@typescript-eslint/consistent-type-definitions": ["error", "type"],
    "@typescript-eslint/explicit-function-return-type": 1,
    "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "typeParameter",
        "format": ["PascalCase"],
        "custom": { "regex": "^T[A-Z]", "match": true }
      }
    ],
    "@typescript-eslint/prefer-ts-expect-error": 2,
    "@typescript-eslint/switch-exhaustiveness-check": 2,
    "import/no-default-export": 2,
    "react/hook-use-state": 2,
    "react/jsx-handler-names": 2
  },

Typescript does not accept to use require on ts files.

My file is a trypescript one:

import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  mainSidebar: [{ type: "autogenerated", dirName: "." }],
  typedocSidebar: [
    {
      type: "category",
      label: "API",
      link: {
        type: "doc",
        id: "api/index",
      },
      // TODO: fix https://github.com/tgreyuk/typedoc-plugin-markdown/discussions/572#discussioncomment-8401341
      // eslint-disable-next-line @typescript-eslint/no-var-requires
      items: require("./docs/api/typedoc-sidebar.cjs") as SidebarsConfig,
    },
  ],
};

export default sidebars;