plugin-pages: menus are always expanded

[FlorianCassayre]

The plugin-pages does not appear to work correctly on simple non-monorepositories.

Following the example shown on this page:

pages: [
  { title: 'Getting started', source: 'getting-started.md', children: [
    { title: 'Configuration', source: 'configuration.md' },
  ] },
  { title: 'Additional resources', childrenDir: 'additional-resources', children: [
    { title: 'Some cool docs', source: 'some-cool-docs.md' },
  ] },
],

I obtain the following tree structure:

I observe that:

• The menus are always expanded, regardless the currently selected page
• The second menu is represented by an attribute-less <a>...</a> tag

I tested other combinations of parameters but couldn't make it work correctly. I haven't tested on a mono-repository but by looking at the configuration of this very repository and seeing the result I'm assuming it works correctly in that case.

[GerkinDev]

This is the expected behavior for now. If you have any suggestions, feel free to turn this into a feature request.

It seems related to #89.

[FlorianCassayre]

I understand; this just seems very odd to me (moreover an anchor must always come with a href attribute).

This is what I am expecting as a user (ignoring the section Additional resources);
when I am on neither getting-started.md nor configuration.md (the Getting started menu is collapsed):

when I am on page getting-started.md:

when I am on page configuration.md:

It seems that the above mentioned PR is related to what I am trying to achieve. However I have difficulties understanding why the layout is by default different depending on whether it is a mono-repository or a normal repository.

[StoneCypher]

plugin-pages works as expected on jssm, which is not a monorepo.

https://github.com/StoneCypher/jssm/blob/main/typedoc-options.js

All folders above the currently selected one are bold black, except the topmost Exports, which is written by typedoc, not the plugin

The current page is also bold blue

When you put two more things in Getting Started and then click the middle one, it'll be visible what's happening

[FlorianCassayre]

Thanks for the response. I updated my comment to clarify that in the first case the menu was collapsed.

I looked at the documentation of jssm: I am getting the same result and it is not what I am willing to achieve. I am aware that Exports is a typedoc-specific section, and I would like this plugin to reproduce that same layout but with pages.

The now outdated typedoc pages plugin could do something like that (see example).

Page Organization is collapsed:

Page Organization is expanded:

[GerkinDev]

Well, not really: see the configuration section, which is a menu only, and its children are always expanded.

Anyway. I can add a top-level option alwaysExpandPageChildren & a per-page option expandChildren. The per-page option would override the global setting alwaysExpandPageChildren.
Another possibility would be to use actual expandable sections, you could expand/collapse via an arrow on the side.

I'm open to suggestions. Maybe this could also cover what @StoneCypher wants to do via its blind PR

[StoneCypher]

@FlorianCassayre - we have similar wants, but what I wrote doesn't do that.

I wrote something else here that basically repeated what GerkinDev said, because I saw this in an old window that hadn't updated with his comment yet. As such, now that I've seen it, I deleted it, because it added nothing to the conversation and was me saying "I'll do what he just said he'll do!"

The difference between what mine does and what you want is that mine won't show the other pages under any circumstances, only the one you're currently on

Mine is for making an example directory that contains hundreds of examples. I don't want that list unfolding ever.

[FlorianCassayre]

@GerkinDev's suggestion seems to go in that direction: a configurable option would be very nice to have. I think what bugs me the most is the indentation of the pages menu compared to the Exports category, despite not being related. Also it would make sense to put the pages block above all the rest or at least to be able to control it; currently it seems to be sorted as if this block was named Pages (for instance it would appear below a typedoc group named Modules but above one named Parsing).
I'm aware that's a lot to ask, and perhaps my vision of what this plugin should do differs from the author's.

Anyway, as an illustration here is what I could achieve in the past with the other (outdated) pages plugin: https://docs.arbre.app/read-gedcom/
Everything under API is generated by typedoc, the rest is controlled by the pages. Ignore the expand/collapse feature for now as it is not used here (although supported by that plugin).

[GerkinDev]

Hey, updates here. I'm currently working on the support of typedoc ^0.23.0, and took the time to dig a bit around those issues.

About the attribute-less <a> tag and the sometimes unexpected behavior in some cases, please take note that with the default typedoc theme, the plugin does its best to be handled exactly how standard typedoc types would, typically namespace. Thus, the rendering process used is here: https://github.com/TypeStrong/typedoc/blob/513a91e3e6df03ab5a38e3fd0cbfb8efc737c4ca/src/lib/output/themes/default/partials/navigation.tsx#L86-L130. For this reason, I cannot replace statically href-less a tags with other kind of tags, nor add properly collapsible sections.

If you are not satisfied by this behavior, the plugins in this repo drafts an API to render the plugin correctly in a custom theme.
I've planned to do a clone of the typedoc default theme with support of this monorepo plugins. I don't know when I will have the time to do it.

In the meantime, I'm working on a fallback option that replaces/alter the navigation tree in the browser via Javascript. I think it's the best I can do without purely replacing the theme.

[FlorianCassayre]

Thanks a lot for the updates & pointers, I understand better now. I don't know much about the internals of Typedoc yet but now that you're talking about it I think the other pages plugin used to be registered as a theme, which is probably why it could achieve all of these behaviors (as opposed to a "regular" plugin). Thus my request is likely out of the scope of this plugin; I will dig into the API on my side.

[GerkinDev]

To implement a theme compatible with this plugin, you should implement the IPagesPluginTheme interface in your custom theme.
I cannot guarantee that the interface is flexible enough for every use case. It is untested & unused for now.

While you should indeed implement the IPagesPluginTheme, I must admit that I've simply skipped the custom theme support for now, as you can see here:

typedoc-plugins/packages/plugin-pages/src/theme-plugins/index.ts

Lines 15 to 24 in 5ec724b

	if( !isPagesPluginTheme( theme ) ){
	if( theme instanceof DefaultTheme ){
	new DefaultPagesJavascriptIndexPlugin( plugin ).initialize();
	return new DefaultTreeBuilder( theme, plugin );
	} else {
	throw new Error( 'Unhandled theme not compatible nor extending the default theme.' );
	}
	} else {
	throw new Error( 'Not implemented' );
	}

I will do my best to take some time to wire custom themes with the plugin. If you want to give a hand, you're absolutely welcome

---

Btw you're absolutely right, ancestors of this plugin were themes, because typedoc did not had yet a clear distinction between themes & plugins. I chose to extend typedoc as much as I can without altering it, with virtual compatibility with any other custom themes, and it induced a couple of rather inconvenient design decisions as mentioned in #84 . I don't want this plugin to mask features of typedoc, as it moves pretty quickly and it is quite unstable.

[GerkinDev]

Hello there!
Typedoc 0.23.8 is now properly supported with plugins in range ~0.23.x.
This new release includes a pretty big refactor, along with a proper support for custom themes. Yet, I didn't had the time to implement a demo and properly test (unit & e2e) the interface between plugins & themes.

For now, I'm still stabilizing the implementation & tooling, but I'll add the options we talked about pretty soon, along with JS code for collapsible menus.
I think it's the next real task in my to-do list for this project, just after some CI tweaks to reduce costs & improve speed.