Improve nesting for navigation

[viveleroi]

Search Terms

navigation nesting collapse tree

Problem

The navigation gets really long for us because everything is listed as a root item rather than nested like a tree.

Suggested Solution

I'd rather mirror the file tree it's reading from... components would be a parent node than when expanded, shows everything inside it, etc. Then, a user would see all root categories immediately:

Components
Hooks
Stores
Utils

[Gerrit0]

There is a theme which does this - https://www.npmjs.com/package/typedoc-theme-hierarchy

With the navigation changes made in 0.25.1, this is more feasible to include in typedoc itself, but I've always struggled to understand why some people run TypeDoc this way rather than pointing it at the library entrypoint, where documentation matches the structure directly importable from the library (surely your users don't have to import lib/components/forms/inputs/date/date?!)

[viveleroi]

This is entirely for our development team working within our private application. Nothing is published as a library, it's effectively a monorepo.

We can't use an entry point because there isn't one. Our app is made up of modules and they're loaded via dynamic imports based on a config and routing because modules vary by client. So when I point typedoc at main.tsx it sees some config files, some layout files, and only one exported App component. It's effectively useless.

[Gerrit0]

Huh, and it's actually useful? I'd have expected it to just be easier to navigate within an IDE... I'll take a look at what it'll take to do this this weekend

[viveleroi]

Outside of the spammy navigation the information is useful, yes. Partly because we can share these generated docs, our written dev docs, and Storybook with developers who are not yet authorized to work on the app and can't see the source. But in some cases it does a better job than an IDE - it excludes internal components/types we don't need junior developers seeing and getting overwhelmed by, and it sometimes does a better job showing all available component props especially in cases where we inherit prop types from a third party.

[viveleroi]

That theme plugin you recommended works well and looks good too. I think we'll use that, thanks.

[GitMurf]

Huh, and it's actually useful? I'd have expected it to just be easier to navigate within an IDE... I'll take a look at what it'll take to do this this weekend

Just as an FYI @Gerrit0, I have the EXACT same use case as @viveleroi. In the opposite way of it surprising you that docs on internal modules/functions/classes could be useful (as opposed to just the IDE) I am equally as surprised that there is not really a good tool/solution for this :) And I think TypeDoc has all the piping in place to be the solution for many many developers and teams. Hence how popular your awesome missing exports https://github.com/Gerrit0/typedoc-plugin-missing-exports plugin has been :)

As @viveleroi alluded to, we have a TON of stakeholders that want to understand the application and even provide feedback on business logic but have no business being inside an IDE (and would get lost in one). These docs are perfect for them to be able to review and comment on things like our data schema / types. Also having the search is very nice compared to getting overwhelmed inside an IDE.

I cannot tell you how amazing your project here is and really hope you can support some of the needs for more internal focused docs as it is a real problem in the industry and think it is a great opportunity for TypeDoc to become even stronger and more popular :)

Thanks for all your hard work!

[Plopsi]

Typedoc is an awesome tool @Gerrit0 is developing, but the navigation gets a bit overwhelming on larger scale projects.

@viveleroi and @GitMurf comprehensed it very nicely :) - Not everything is just a library, it's quite often to have a seperate code-documentation for bigger projects. The documentation works well, but navigating in the project gets hard without a "foldered" navigation

I guess it would alone be helpful to just have nestable '@group' and/or '@category' options like '@group my.nested.group', which then is nesting in the navigation.

The plugin is nice, but produces a ~8GB ouput as it puts the navigation into every page (anyone though every about putting the actual doc-pages into an iframe and let the navigation reside in the index.html?) - in comparison of around 120MB with pure typedoc.

• Plopsi

[Gerrit0]

I've been experimenting with changes to how pages are generated, and I think the navigation fits well into this, will be a part of 0.26, which may still be 6 months away

[citkane]

I developed a theme a while back for typedoc that efficiently presents hierarchically:
https://citkane.github.io/typedoc-theme-yaf/dev/

I stopped developing at the switch to typedoc 0.24 because my logic was too fragile for the changes to the API.
Basically:

• all pages are stored as .json data fragments (instead of html) and loaded on demand
• all rendering logic is in the frontend, which is built with native web components
• the menu data is only loaded once

You may (or may not) get some ideas from it.

[Plopsi]

@citkane whooo nice... i like it, the grouping/categorizing is just missing :) - i guess then it would fit exactly - except that i don't like the design ;D - I like the show hidden feature....

• Plopsi

[typhonrt]

@viveleroi and others...

I have just released the next beta of my "Default Modern Theme" (DMT) augmentation for the default TypeDoc theme. This takes full advantage of the new navigation index capability of TypeDoc 0.25.1+. The original DMT release in July spurred the creation of the navigation index for TypeDoc 0.25.x. The latest DMT release is fully ready to go, but I just want to get a little feedback before releasing 0.2.0, so if anyone has the gumption to try it out I'd be glad to get feedback (open an issue on the DMT repo).

package.json:

{
   "devDependencies": {
      "@typhonjs-typedoc/typedoc-theme-dmt": "^0.2.0-next.1",
      "typedoc": "^0.25.0"
   }
}

typedoc.json:

{
  "plugin": [
    "@typhonjs-typedoc/typedoc-theme-dmt"
  ],

  "theme": "default-modern",
}

---

My main OSS project is putting out a large framework for Svelte. The API docs covers three NPM packages. My framework uses many sub-path exports so without the full navigation tree of the DMT there is like ~65+ modules represented in the default TypeDoc navigation index; a situation similar to what @viveleroi brought up w/ their effort. The latest DMT vastly improves navigation across the API docs and understandability as well.

You can check out the generated docs for this framework here w/ the latest DMT for an example:
https://typhonjs-fvtt-lib.github.io/api-docs/

The DMT by default creates a full tree for "modules" that are otherwise concatenated in the default navigation index. You have control over the navigation index though and can decide at which depth concatenation starts.

The theme option dmtNavModuleDepth controls at which depth module path concatenation occurs. If you set that to 0 then there is no path concatenation and the output is just like the default theme. Set it to 1 then there is one level before concatenation occurs. You don't have to set this option though as a full navigation tree is generated by default.

There are many other neat features of the DMT and I'll be expanding on documentation and put out a video tutorial in the coming weeks.