[Discussion] Default Modern Theme + complete / linkable built-in TS lib docs.

[typhonrt]

I'd like to discuss aspects that are worthy of committing back to the default TypeDoc theme from the recent work that I have released that addresses some general issues. I will include a general announcement below about the resources I have released followed up by aspects that could make it back to the default theme.

The big performance gains are ~90% less disk space utilization and ~80% faster doc generation over the default theme.

I also posted a quick overview video of the resources discussed:
https://www.youtube.com/watch?v=P-TUSPbtLQ0

---

I have just released a few projects that might help your TypeDoc related usage; particularly for large project documentation generation w/ TypeDoc. I have created the "Default Modern Theme" / "DMT" and its what I call a "theme augmentation" package that functions by augmenting the output of the default TypeDoc theme instead of entirely replacing it. It saves up to ~90% of disk space utilized and is ~80% faster than generating docs w/ the default theme. I also have a few stylistic additions that make things just a bit nicer and increased a11y support with more to come.

Here are the resources to review:
Typedoc Theme (Default Modern Theme)
https://www.npmjs.com/package/@typhonjs-typedoc/typedoc-theme-dmt

Complete and linkable API docs for the TS built-in library declarations + WebGPU / WebCodecs / WebXR APIs. When you generate docs you can add an additional set of TypeDoc plugins to link to every symbol in the declarations to your project docs.
https://www.npmjs.com/package/@typhonjs-typedoc/ts-lib-docs

Jump right to the hosted TS lib docs for an example of large projects generated w/ the DMT:
DOM + WebGPU / WebCodecs / WebXR,
ES2023,
Web Worker APIs.

The TS lib API docs also cross link every symbol against the MDN browser compatibility package and provide links to MDN and relevant specifications integrated in the API docs.

Check out the README and the configuration descriptions available in the links above.

Background:
The main bottleneck with the TypeDoc default theme especially for large projects is the verbose HTML for the left-hand navigation that linearly grows for each page based on the project size and consumes a massive amount of disk space; see this TypeDoc issue. The DMT caches the left-hand navigation HTML and dynamically creates a shared web component that is utilized across all pages only making a single copy of the navigation HTML. This reduces disk space utilization by up to 90% and also makes doc generation ~80% faster. I also include some style additions and replace the main search index generation using compressed MesssagePack instead of JSON which reduces the search index size by more than 90%.

The TS lib DOM API for instance is over 1.4GB with the standard default TypeDoc theme, but w/ the DMT it is 137MB. Well within the size to host on Github Pages.

Being that these resources are new I did "soft-launch" the TS lib API docs using Github Pages for hosting. If things take off and it becomes a popular global resource for documentation generation / linking I will likely have to find a more permanent host. So just a heads up that possibly sometime in the future the hosting location may need to change.

Feedback:
I'd be glad to hear feedback on how I can improve theses resources! My general plan is to try and upstream as much as possible back to the Typedoc default theme over the coming months and continue to add usability features including better search capabilities for large projects to the DMT.

[typhonrt]

Not everything is suitable for upstreaming to the default TypeDoc theme, but I think there are areas that can be accepted to improve the default theme. Some of the obvious aspects are style changes to clean up the default theme as that may make sense.

Another procedural one that I'd like to see that is very specific is a better way to handle the inline SVG for the various reflection kinds: namespace, function, etc. The SVG elements that display in the default theme per page. Right now the first usage of the SVG for a particular reflection kind has the full element and all successive usages refer to the original embedding. It would be great to either have all SVG / reflection kinds cached on the page or have them as external resources that can be loaded.

A major reason for such a change is that you can not refer to a reflection kind that is not already in the page due to the way that only the SVG for reflection kinds in the current page is available. For instance I plan on continuing to improve the main search index and offer a new "quick search" UI and it would be nice to show the SVG for any reflection kind found in the respective search UI and that may include reflection kinds not presently loaded on the current page, so externally hosting this SVG is useful.

---

Anyway.. There is a lot to potentially discuss. The technique or approach I took w/ the "DMT" I think is relatively unique. I'm going more for augmenting the output of the default theme than purely replacing it. The general hope is that I'll be able to keep things synched w/ the default theme as it continues to change and use the DMT as an advanced prototyping stage to then upstream whatever makes sense.

[Gerrit0]

Very delayed response here on my part, apologies for that! You have built something really cool here. I agree with your assessment that at least some of these changes ought to make it into TypeDoc's default theme, and just finished reworking navigation to be built dynamically. With this change, the DOM library is 185mb with TypeDoc's default theme, and I haven't compressed the search index yet!

Incidentally, this required that I require all icons be embedded in each page. I looked at having them in an external page, but unfortunately this seems to make it impossible to style them properly for theme changes, so with 0.25.1, they'll all be there!

[typhonrt]

No worries on the delay. I'm just ramping up for my next OSS dev cycle Oct-Dec. Definitely appreciate the nod on what I created. The ts-lib-docs effort certainly was a soft launch as I don't have a whole lot of reach in getting the word out about the OSS tooling I release. I posted on the TS Reddit and that contributed to the initial push of ~50 installs, but overall its not visible to the TS / JS community using TypeDoc. I also need to adjust the keywords in the NPM package to get picked up by the TypeDoc website.

I'll definitely spend some time w/ the latest TypeDoc release soon to see any changes and start to evaluate what can be upstreamed from the DMT / theme effort as well.

Incidentally, this required that I require all icons be embedded in each page.

For some of the features I have in the DMT theme I had to do some shuffling of the icon definitions. If all of the icons are present on the page in a separate reference section that can work too.

I think I'll have more input in the second half of October, so definitely would like to circle around and see what is possible to upstream in that general timeframe.

[typhonrt]

@Gerrit0 I spent a lot of time on this one ~160 hours and really honed a lot of things I'd like to upstream into the default theme as it makes sense. Beside the detailed navigation index work one area that I spent a lot of time on is accessibility / keyboard navigation as well as honing styles / CSS to make keyboard navigation more intelligible. Let's continue the discussion as I'm open to actually contribute / upstream what makes sense to do so.

---

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. 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.

[Gerrit0]

Accessibility and keyboard navigation improvements would be very much appreciated! I am rarely working in the frontend with the exception of this project, so know that I tend to miss things.

The nested navigation by splitting on / in module names is something I've been considering doing for a while too -- just haven't gotten around to implementing it yet. I also want TypeDoc's implementation to turn color/colord into one dropdown in yoru example page, since there's only one item under that entry. I'm not entirely sure it's useful to have as an option -- all of the feedback I've seen regarding that nesting behavior has indicated people want the full structure.

[typhonrt]

Yeah.. Let's try and find a way to actually upstream various aspects of the DMT that are applicable. I'm definitely willing to become a direct contributor. Styles / CSS is relatively low hanging fruit for sure along with potential template modifications. There aren't too many in this category, but a few places that extend flexibility / use of flex box wrapping elements, etc.

Re: navigation index changes. I certainly have the code worked out for modifying the current navigation index generated to provide nesting. There is an option dmtNavModuleDepth that controls at what depth concatenation starts. You can test things out presently by setting dmtNavModuleDepth to 1, 2, 3, etc. This will concatenate paths at that given depth; set it to 0 and the output is the same as the default theme / full paths.

There presently isn't an "auto-concatenate" option to concatenate singular paths like color/colord IE the example you gave from my framework docs presented; that should be an extra option though as it's rather specific. It's definitely possible without too much extra work though; I might take a look at it now.

The only "major" config related HTML structural change w/ the latest DMT is that sidebarLinks and navigationLinks are placed in the navigation sidebar. Full text links in the top header bar doesn't work as well for different screen sizes. I have introduced "icon links" for the header bar. dmtLinksService provides ~5 well used services that have icons ready to go and is easier to configure. Another option dmtLinksIcon allow for user supplied icon links.

---

The main angle of upstream consideration is potentially switching over to a compile time library / framework. I have a preference for Svelte / use it currently in the DMT. It really does give a bit of extra polish over the homegrown "light component" wrappers IE: src/lib/output/themes/default/assets/typedoc/Component.ts and friends. You may have some strong opinions in this regard. I am also not entirely clear how many other 3rd party themes may use this lightweight API for anything front end.

Regarding the navigation index. In the DMT I make it into a data structure that is stateful and queryable. There are a lot of things that the current default theme implementation misses in this regard. Try loading any URL with a hash fragment for an internal symbol to a given page. The default theme doesn't correctly select the navigation element in this case, etc. So lots of little things are a bit disconnected in the current default theme. The DMT will run a couple of queries with and without the hash fragment to find the correct page / NavigationElement entry to select, etc.

With the forthcoming 0.2.0 DMT release (pre-release now) I have things really optimized in terms of theme / Svelte component bundle file sizes. With the new navigation index I was able to really slim things down as the big workaround of the initial release 0.1.0 / TypeDoc 0.24.x is no longer necessary.

I think it is good to have a comparison w/ the DMT regarding polish / final fit and finish as a way to show where the default theme can go. Since it is an augmentation of the default theme output vs a replacement the DMT provides a bit of a clearer picture on where things can potentially be improved.

---

Ooo.. I also have something spicy incoming shortly for an automatic CLI for doc generation from package.json exports / configuration. I'll make a post on that issue when it's out.

[Gerrit0]

You may have some strong opinions in this regard

I am not a frontend enjoyer, I have really only one hard rule for the default theme.

The site shall work without JavaScript. It might not be perfect (search, filter, full navigation tree), but it will at least be readable. Frontend frameworks seem to all be of the "render everything" opinion rather than being built for progressive enhancement.

A second goal is that adjusting something in the theme should not require understanding a massive framework. Everything I've used (Svelte isn't on that list) has always had annoying edge cases to fall into that end up compounding the DOM's weirdness...

[typhonrt]

I am not a frontend enjoyer, I have really only one hard rule for the default theme. The site shall work without JavaScript. It might not be perfect (search, filter, full navigation tree), but it will at least be readable. Frontend frameworks seem to all be of the "render everything" opinion rather than being built for progressive enhancement.

So, I got everything working again w/ no script loading for the DMT.

I'm sure you have noticed with the default theme the visual flash and inconsistent state of the UI as the additional default theme JS is loaded. This is very noticeable w/ the "settings" / "on this page" accordions depending on state (if they are closed) and the navigation tree will flash and readjust as the default theme JS loads which can be very jarring depending on the state and how large the navigation tree is.

The same will happen w/ loading Svelte components in regard to enhancement just after the initial page loads. To get around this visual glitch I add additional style rules to head to make body not visible and flip that state after the Svelte component bundle fully loads. This ensures that both main.js and the loaded Svelte components set state of the UI before showing which is far less distracting.

I have made the adjustment so that there is an additional noscript style rule added that will do this reversal when JS is turned off in the browser. So, if you tried things w/ Javascript disabled and you get a blank screen this is why and it is nothing to do w/ Svelte, but is the workaround I put in place to reduce visual artifacts of changing the UI state after initial page load. The DMT 0.2.0-next.5 release will have this solved for no script usage.

So the DMT loads fine without Javascript enabled. The same minimal HTML navigation tree output by the default theme is what you get.

---

On to your second point. Just like the bespoke loading of JS w/ the default theme "lightweight component" API my usage of Svelte is exactly the same where I just target the navigation index and search components. It just uses Svelte instead of the bespoke mechanism of the default theme. Folks that want to modify the default theme will have to understand your bespoke API regardless, so it's not a standard per se. I think it would be a minor nightmare to reproduce the UX / interactivity and accessibility support that the Svelte navigation component brings to the table with the default theme "lightweight component" API. Using Svelte doesn't mean the whole page is rendered w/ Svelte. It is surgical in implementation and the nice thing about Svelte being a "compile-time" library / framework is that a single all contained bundle is produced for loading; IE no additional runtime to load (Vue / React, etc.).

Do you know of any themes that continue to use the "lightweight component" API that you built for the default theme? My guess is that most replace those aspects with other tech or don't touch it at all.

I think a good way to evaluate the DMT is whether one feels the UX and features improve on the default theme regardless of the underlying tech.

[Gerrit0]

I haven't kept track of what themes people have built besides making sure appropriately tagged ones show up on https://typedoc.org/guides/themes/

Some thoughts, in no particular order, I haven't played with it much on desktop yet:

• I like the buttons to expand/collapse the nav tree, and the keyboard shortcuts docs
• the guide lines in the nav tree are really helpful in deeply nested hierarchies
• the search box zooms me into the page when on iOS
• links to members within the page result in the member being partially scrolled behind the title bar (default theme tries to handle this, doesn't do it great)
• There are a lot of boxes in the theme now, which feels rather overwhelming when looking at functions which accept callbacks, it feels kind of like TypeDoc's current styling has been half-replaced. I'm far from a UI expert, but one thing I've internalized is avoiding unnecessary change -- is there a reason to have all these extra visible layers? https://typhonjs-fvtt-lib.github.io/api-docs/types/svelte_store.StartStopNotifier.html
• It would be nice for the animation to default to off for anyone who has their computer set to reduce motion. Personally, I almost never want motion.
• I often can't easily see the bottom inch or so of the screen due to it being hidden behind the safari navigation bar, even when scrolling down. With the default theme, safari is able to tell you're scrolling and collapse the nav bar.
• The custom icons are still clipped behind the search on very small screens, they should probably show up on the sidebar
• The guide lines in the navigation are hard to see in dark mode
• The keyboard shortcuts feel strange to me - likely due to just not being used to them... however few shortcuts I use commonly include Alt. Are these based on some common set from something? GitHub and StackOverflow both went for a go to X, gX style, TypeDoc's only current shortcut is / to open search from Less/Vim...

[typhonrt]

So the latest DMT is out 0.2.0-next.10. Quite likely it may be the final beta before the next official release. I have just released @typhonjs-typedoc/typedoc-pkg which uses the DMT, and provides a CLI / robust way to automatically generate docs from package.json with correct export name / module path replacement. typedoc-pkg is zero configuration yet also has various extended options to easily automate documentation generation for well configured packages.

The major performance win in the latest DMT release is that the SVG icons cache is stored as an external file and the per page cache is removed which saves 15KB per page which really can add up with large documentation projects (20-30%) of file space.
If I can in ~40 lines of code augment the output of the default theme then it should be relatively easy to make the default theme reference an external SVG file.

---

Responses to the previous post:

I definitely want to reiterate that the DMT is not in a final state in respect to potential upstreaming nor would it potentially just be adopted. It is an attempt to deliver maximum value w/ minimal structural changes. A few things that you listed would require more involved structural changes that is more appropriate in the theme replacement category than augmentation. The DMT is more of a guide of where significant updates can occur with the default theme.

I am more than willing to work on a full upstream effort to incorporate these changes in the default theme.

Some thoughts, in no particular order, I haven't played with it much on desktop yet:

• the search box zooms me into the page when on iOS

Definitely a Safari / iOS thing. I increased the font-size to 16px which should stop this default behavior on iOS. I gather the default theme does the same as there is no font-size set.

• links to members within the page result in the member being partially scrolled behind the title bar (default theme tries to handle this, doesn't do it great)

If you can provide a bit more information / screen shot that can help in this case. It is not clear exactly what you are referring to.

• There are a lot of boxes in the theme now, which feels rather overwhelming when looking at functions which accept callbacks, it feels kind of like TypeDoc's current styling has been half-replaced. I'm far from a UI expert, but one thing I've internalized is avoiding unnecessary change -- is there a reason to have all these extra visible layers? https://typhonjs-fvtt-lib.github.io/api-docs/types/svelte_store.StartStopNotifier.html

Just like the navigation guide lines the additional parameter list overlaid borders / background shows depth so you can easily tell which parameter list is being viewed quickly. Granted this is a subjective change, but the grouping / borders helps quite a bit when scrolling through large files with lots of methods.

• It would be nice for the animation to default to off for anyone who has their computer set to reduce motion. Personally, I almost never want motion.

This is now enabled. Clear local storage and you'll see that the animation setting will take the OS reduce motion setting initially.

• I often can't easily see the bottom inch or so of the screen due to it being hidden behind the safari navigation bar, even when scrolling down. With the default theme, safari is able to tell you're scrolling and collapse the nav bar.

Yeah... The change is that the main content div is now scrollable versus the whole page. This does favor the desktop display in this case, but this change also significantly improves the left hand navigation which is a bit "wonky" w/ the default theme; not being pejorative there. You can also on mobile devices flick up / down the docs title bar to hide the mobile browser URL bar.

• The custom icons are still clipped behind the search on very small screens, they should probably show up on the sidebar

This is one of those augmentation vs replacement issues. The main problem with the default theme is the absolute positioning of the search button and overflow mobile menu. In a more replacement oriented solution the search and mobile overflow buttons would be part of a flex box in the title bar.

If you really want to ensure folks w/ less than ~420px wide devices have no problems then a custom icon fly-out Svelte component is the best solution. IE once there is not enough space for all the icons they are condensed down into a fly-out overflow menu. Again that really would only come into play with folks reading documentation on their smartwatch.. :O

Presently the navigationLinks of the default theme completely overlap the document title when the browser width is reduced.

• The guide lines in the navigation are hard to see in dark mode

I made the default brighter. A CSS variable is available to change it further.

• The keyboard shortcuts feel strange to me - likely due to just not being used to them... however few shortcuts I use commonly include Alt. Are these based on some common set from something? GitHub and StackOverflow both went for a go to X, gX style, TypeDoc's only current shortcut is / to open search from Less/Vim...

Alt / Option is chosen for the activation because it doesn't conflict with browser shortcuts which use Ctrl / Meta. While some of the shortcuts are "go to X" oriented holding down Alt while opening / closing navigation folders is not. This is pretty subjective and I'd want to receive feedback from actual keyboard bound users. They exist for accessibility reasons. I'm not opposed to switching the to the gX style.

[Gerrit0]

I have just released @typhonjs-typedoc/typedoc-pkg

Neat! The exports handling sounds like exactly what I want to include in TypeDoc someday.

The major performance win in the latest DMT release is that the SVG icons cache is stored as an external file and the per page cache is removed which saves 15KB per page which really can add up with large documentation projects (20-30%) of file space.
If I can in ~40 lines of code augment the output of the default theme then it should be relatively easy to make the default theme reference an external SVG file.

I've wanted to do this for a while, didn't realize it was so easy to do! Going to steal that right now..
Edit: Ick. Turns out this only works if serving from a web server. If loading a local file browsers block it... I really don't want to lose that, I use local files very heavily during development... but it's a pretty major savings... going to think about this one.

I gather the default theme does the same as there is no font-size set.

Surprisingly, it doesn't... frontend is a mystery to me. Potentially due to the font-size on body?

If you can provide a bit more information / screen shot that can help in this case. It is not clear exactly what you are referring to.

This appears to be another safari specific thing, I can't reproduce on desktop - visiting https://typhonjs-fvtt-lib.github.io/api-docs/classes/_runtime_util.Hashing.html#hashCode results in this:

(Icons inside the circles are consistently off center as shown in the image as well, same for the dropdown expand/collapse)

Image

This is now enabled. Clear local storage and you'll see that the animation setting will take the OS reduce motion setting initially.

👍 very nice

Just like the navigation guide lines the additional parameter list overlaid borders / background shows depth so you can easily tell which parameter list is being viewed quickly. Granted this is a subjective change, but the grouping / borders helps quite a bit when scrolling through large files with lots of methods.

Having played with it some more, I'm coming around to this change, it still feels a bit noisy when dealing with callbacks, but for the majority of members, I definitely like it.

Yeah... The change is that the main content div is now scrollable versus the whole page. This does favor the desktop display in this case, but this change also significantly improves the left hand navigation which is a bit "wonky" w/ the default theme; not being pejorative there. You can also on mobile devices flick up / down the docs title bar to hide the mobile browser URL bar.

Very unfortunate if that's a necessary change... It's fine on most pages, until I get to one where there's just enough content to hide content behind the navigation bar (ComponentProps on my phone), then the page gets quite wonky.

What wonk are you referring to in the default theme? I thought I'd brute forced my way through all the issues there.

If you really want to ensure folks w/ less than ~420px wide devices have no problems then a custom icon fly-out Svelte component is the best solution. IE once there is not enough space for all the icons they are condensed down into a fly-out overflow menu. Again that really would only come into play with folks reading documentation on their smartwatch.. :O

My non-massive phone is 375px wide according to Firefox devtools, it's not too uncommon for me to use it for a quick reference if talking to someone on Discord. Definitely agree that the default theme does no better, and in many ways worse.

I made the default brighter. A CSS variable is available to change it further.

Much easier to see 👍

Alt / Option is chosen for the activation because it doesn't conflict with browser shortcuts which use Ctrl / Meta. While some of the shortcuts are "go to X" oriented holding down Alt while opening / closing navigation folders is not. This is pretty subjective and I'd want to receive feedback from actual keyboard bound users. They exist for accessibility reasons. I'm not opposed to switching the to the gX style.

Definitely makes sense. Having played with it a bit more, I don't mind the alt based shortcuts, though it isn't really true to say that because it uses Alt, it won't conflict - Alt+T+I opens Firefox's Page Information dialog.

Esc should definitely close the search bar. I especially like Alt+C, though it makes me wonder if the "reflection summary" interface block on pages like this one should have an anchor to skip them.

---

Now, the elephant:

TypeDoc's default theme really hasn't changed structurally in any significant way since I started working on it ~6 years ago. The two biggest changes were moving from handlebars to JSX (which didn't actually change the output structure, just made it much easier to detect type errors) and a styling rework which made browsing on mobile much better, and fixed a lot of accessibility problems. Is it time for that to change?

You're clearly passionate about making docs better, which is awesome. If you think it is time that TypeDoc's default theme was rebuilt, and want to lead that effort, I'd be happy to add you as a contributor and provide what help I can, we'd definitely want to do this as a part of a minor release.