feat: make theme work with default plugins and configuration

CHANGELOG.md

@@ -0,0 +1,5 @@
+## 0.2.0 (2024-08-08)
+
+
+
+

README.md

@@ -1,43 +1,70 @@
-# Theme your TypeDoc like GitHub
+# typedoc-theme-gobstones
 
-[![NPM](https://nodei.co/npm/typedoc-github-theme.png)](https://npmjs.org/package/typedoc-github-theme)
+This a customized theme for [TypeDoc](https://typedoc.org/) used for all the generated documentation throughout the **GobstonesWeb2** project.
+It's based on the default theme used by TypeDoc, with mild improvements in readability and styling, and includes by default several plugins built-in so the user does not require to include them in their configuration. Included plugins are:
+    * [typedoc-plugin-mdn-links](https://github.com/Gerrit0/typedoc-plugin-mdn-links)
+    * [typedoc-plugin-merge-modules](https://github.com/krisztianb/typedoc-plugin-merge-modules)
+    * [typedoc-plugin-remove-references](https://github.com/eyworldwide/typedoc-plugin-remove-references)
+    * [typedoc-plugin-missing-exports](https://github.com/Gerrit0/typedoc-plugin-missing-exports) (With modifications)
 
-This [TypeDoc](https://github.com/TypeStrong/typedoc) theme is designed to provide an elegant and seamless look and feel for your TypeScript documentation on GitHub Pages, inspired by the GitHub design.
+[![Licence](https://img.shields.io/badge/AGPL--3.0_with_additional_terms-olivegreen?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/typedoc-theme-gobstones/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/typedoc-theme-gobstones?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://www.npmjs.com/package/@gobstones/typedoc-theme-gobstones)
 
-## Example
+[![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/typedoc-theme-gobstones?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/typedoc-theme-gobstones)
 
-[![Example](./example.png)](https://killerjulian.github.io/typedoc-github-theme/)
+![GitHub Workflow Tests](https://img.shields.io/github/actions/workflow/status/gobstones/typedoc-theme-gobstones/on-commit-test.yml?style=plastic&label=Tests&logo=github-actions&logoColor=white) ![GitHub Workflow Build](https://img.shields.io/github/actions/workflow/status/gobstones/typedoc-theme-gobstones/on-commit-build.yml?style=plastic&label=Build&logo=github-actions&logoColor=white)
 
-## Usage
+## Install
 
-**Install the package with your favourite package manager:**
+This library is included in the [gobstones-scripts](https://gobstones.github.io/gobstones-scripts) library, and used in the provided TypeDoc configuration by default. If you are using `gobstones-scripts` you don't need to do anything to use this library.
 
-```text
-npm install typedoc-github-theme
-```
+If you want to add this to a project that does not include `gobstones-scripts`, just install by using `npm`.
 
-```text
-pnpm install typedoc-github-theme
+```bash
+npm install @gobstones/typedoc-theme-gobstones
 ```
 
-```text
-yarn add typedoc-github-theme
+### Usage
+
+Again, if you are using `gobstones-scripts` with the default configuration you don't need to do anything. If you want to use in different type of project, or provide your custom configuration, read the following.
+
+Configure your project to use this theme by editing your `typedoc.config.js` file. Add the theme as a plugin, and set the theme to be `gobstones`. Additionally, configure properties for the default theme and plugins so the theme behaves as expected.
+
+```js
+module.exports = {
+    // ...
+    // You default configuration before this point
+    plugin: [
+        // ...
+        // Set up the theme, alongside your other plugins
+        '@gobstones/typedoc-theme-gobstones'
+    ],
+    excludeTags: [
+        // Remove the @internal from the excluded tags
+        "@override",
+        "@virtual",
+        "@satisfies",
+        "@overload",
+    ],
+    visibilityFilters: {
+        // Add @internal as a visibility filter
+        '@internal': false,
+        protected: false,
+        private: false,
+        inherited: false
+    },
+    // Set `gobstones` as the theme
+    theme: 'gobstones',
+    // Configure the merge modules strategy as a module or module-category
+    mergeModulesMergeMode: 'module'
+};
 ```
 
-**Use the theme when generating your documentation:**
-
-```text
-typedoc src/** */ --plugin typedoc-github-theme --theme typedoc-github-theme
-```
-
----
-
-## Author
+You should now be able to run `typedoc` command to get the documentation. If you are using `gobstones-scripts`, just execute `nps start doc` or one of it's related commands as usual.
 
-👤 **KillerJulian <[email protected]>**
+## Testing newer versions of the library
 
-- Github: [@KillerJulian](https://github.com/KillerJulian)
+To develop this library you will need to build the library and publish to a local repository, similar as to how you test `gobstones-scripts`. You may read about [how to setup a verdaccio server in your local environment](https://gobstones.github.io/gobstones-scripts/#md:testing-newer-versions-of-the-library) at the `gobstones-scripts` documentation, and if you have the gobstones-scripts project, you may even run the same server.
 
-## 🤝 Contributing
+## Contributing
 
-Contributions, issues and feature requests are welcome!<br />Feel free to check the [issues page](https://github.com/KillerJulian/typedoc-github-theme/issues). You can also take a look at the [contributing guide](https://github.com/KillerJulian/typedoc-github-theme/blob/master/CONTRIBUTING.md).
+See our [Contributions Guidelines](https://gobstones-github.io/gobstones-guidelines) to contribute.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gobstones/typedoc-theme-gobstones",
   "description": "A simple theme for the Gobstones generated documentation.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "keywords": [
     "Gobstones",
     "typedoc-theme",
@@ -75,5 +75,10 @@
     "typedoc": "~0.26.4",
     "typescript": "^5.5.4",
     "typescript-eslint": "^8.0.1"
+  },
+  "dependencies": {
+    "typedoc-plugin-mdn-links": "^3.2.7",
+    "typedoc-plugin-merge-modules": "^6.0.0",
+    "typedoc-plugin-remove-references": "^0.0.6"
   }
 }

src/GobstonesTheme.tsx

@@ -13,7 +13,15 @@
 import fs from 'fs';
 import path from 'path';
 
-import { DefaultTheme, PageEvent, Reflection, RendererEvent } from 'typedoc';
+import {
+    DeclarationReflection,
+    DefaultTheme,
+    DocumentReflection,
+    PageEvent,
+    Reflection,
+    RendererEvent,
+    SignatureReflection
+} from 'typedoc';
 
 import { GobstonesThemeContext } from './GobstonesThemeContext';
 
@@ -65,4 +73,59 @@ export class GobstonesTheme extends DefaultTheme {
         // theme is going to use.
         return new GobstonesThemeContext(this, pageEvent, this.application.options);
     }
+
+    getReflectionClasses(reflection: DeclarationReflection | DocumentReflection) {
+        function toStyleClass(str: string): string {
+            return str.replace(/(\w)([A-Z])/g, (_m, m1: string, m2: string) => m1 + '-' + m2).toLowerCase();
+        }
+
+        const filters = this.application.options.getValue('visibilityFilters') as Record<string, boolean>;
+
+        const classes: string[] = [];
+
+        // Filter classes should match up with the settings function in
+        // partials/navigation.tsx.
+        for (const key of Object.keys(filters)) {
+            if (key === 'inherited') {
+                if (reflection.flags.isInherited) {
+                    classes.push('tsd-is-inherited');
+                }
+            } else if (key === 'protected') {
+                if (reflection.flags.isProtected) {
+                    classes.push('tsd-is-protected');
+                }
+            } else if (key === 'private') {
+                if (reflection.flags.isPrivate) {
+                    classes.push('tsd-is-private');
+                }
+            } else if (key === 'external') {
+                if (reflection.flags.isExternal) {
+                    classes.push('tsd-is-external');
+                }
+            } else if (key.startsWith('@')) {
+                let firstSignature: SignatureReflection | undefined;
+
+                if (reflection.isDeclaration()) {
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+                    const declRefl = reflection as DeclarationReflection;
+                    firstSignature = declRefl.signatures?.[0];
+                }
+
+                if (key === '@deprecated') {
+                    if (reflection.isDeprecated()) {
+                        classes.push(toStyleClass(`tsd-is-${key.substring(1)}`));
+                    }
+                } else if (
+                    reflection.comment?.hasModifier(key as `@${string}`) ||
+                    reflection.comment?.getTag(key as `@${string}`) ||
+                    (firstSignature && firstSignature.comment?.hasModifier(key as `@${string}`)) ||
+                    (firstSignature && firstSignature.comment?.getTag(key as `@${string}`))
+                ) {
+                    classes.push(toStyleClass(`tsd-is-${key.substring(1)}`));
+                }
+            }
+        }
+
+        return classes.join(' ');
+    }
 }

src/index.tsx

@@ -13,10 +13,21 @@
 import { Application } from 'typedoc';
 
 import { GobstonesTheme } from './GobstonesTheme';
+import { loadPlugin } from './plugins';
+import { MdnLinksPlugin } from './plugins/MdnLinksPlugin';
+import { MergeModulePlugin } from './plugins/MergeModulePlugin';
+import { NotExportedPlugin } from './plugins/NotExportedPlugin';
+import { RemoveReferencesPlugin } from './plugins/RemoveReferencesPlugin';
 
 /**
  * Called by TypeDoc when loading this theme as a plugin
  */
 export function load(app: Application) {
+    // Included plugins
+    loadPlugin(app, NotExportedPlugin);
+    loadPlugin(app, MergeModulePlugin);
+    loadPlugin(app, RemoveReferencesPlugin);
+    loadPlugin(app, MdnLinksPlugin);
+    // Main theme
     app.renderer.defineTheme('gobstones', GobstonesTheme);
 }

src/partials/comments/reflectionFlags.tsx

@@ -12,7 +12,7 @@
  */
 import { JSX, DefaultThemeRenderContext, Reflection } from 'typedoc';
 
-import { join } from '../../lib';
+import { join } from '../lib';
 
 const flagsNotRendered: `@${string}`[] = ['@showCategories', '@showGroups', '@hideCategories', '@hideGroups'];
 
@@ -26,5 +26,7 @@ export function reflectionFlags(context: DefaultThemeRenderContext, props: Refle
         }
     }
 
-    return join(' ', allFlags as unknown as JSX.Element[], (item: JSX.Element) => <code class="tsd-tag">{item}</code>);
+    return join(' ', allFlags as unknown as JSX.Element[], (item: JSX.Element) => (
+        <code class={`tsd-tag tsd-tag-${(item as unknown as string).toLowerCase()}`}>{item}</code>
+    ));
 }

src/partials/index.tsx

@@ -13,7 +13,7 @@
 import { JSX } from 'typedoc';
 import type { DefaultThemeRenderContext, ContainerReflection, ReflectionCategory, ReflectionGroup } from 'typedoc';
 
-import { classNames, renderName } from '../lib';
+import { classNames, renderName } from './lib';
 
 function renderCategory(
     { urlTo, icons, getReflectionClasses, markdown }: DefaultThemeRenderContext,

src/partials/members/member.declaration.tsx

@@ -13,7 +13,7 @@
 import { JSX } from 'typedoc';
 import type { DeclarationReflection, ReflectionType, DefaultThemeRenderContext } from 'typedoc';
 
-import { getKindClass, hasTypeParameters, renderTypeParametersSignature, wbr } from '../../lib';
+import { getKindClass, hasTypeParameters, renderTypeParametersSignature, wbr } from '../lib';
 
 function renderingTypeDeclarationIsUseful(declaration: DeclarationReflection): boolean {
     if (declaration.hasComment()) return true;

src/partials/members/member.getterSetter.tsx

@@ -13,11 +13,11 @@
 import { JSX } from 'typedoc';
 import type { DeclarationReflection, DefaultThemeRenderContext } from 'typedoc';
 
-import { classNames } from '../../lib';
+import { classNames } from '../lib';
 
 export const memberGetterSetter = (context: DefaultThemeRenderContext, props: DeclarationReflection) => (
     <>
-        <ul
+        <div
             class={classNames(
                 {
                     'tsd-signatures': true
@@ -27,26 +27,26 @@ export const memberGetterSetter = (context: DefaultThemeRenderContext, props: De
         >
             {!!props.getSignature && (
                 <>
-                    <li class="tsd-signature" id={props.getSignature.anchor}>
+                    <div class="tsd-signature" id={props.getSignature.anchor}>
                         <span class="tsd-signature-keyword">get</span> {props.name}
                         {context.memberSignatureTitle(props.getSignature, {
                             hideName: true
                         })}
-                    </li>
-                    <li class="tsd-description">{context.memberSignatureBody(props.getSignature)}</li>
+                    </div>
+                    <div class="tsd-description">{context.memberSignatureBody(props.getSignature)}</div>
                 </>
             )}
             {!!props.setSignature && (
                 <>
-                    <li class="tsd-signature" id={props.setSignature.anchor}>
+                    <div class="tsd-signature" id={props.setSignature.anchor}>
                         <span class="tsd-signature-keyword">set</span> {props.name}
                         {context.memberSignatureTitle(props.setSignature, {
                             hideName: true
                         })}
-                    </li>
-                    <li class="tsd-description">{context.memberSignatureBody(props.setSignature)}</li>
+                    </div>
+                    <div class="tsd-description">{context.memberSignatureBody(props.setSignature)}</div>
                 </>
             )}
-        </ul>
+        </div>
     </>
 );

src/partials/members/member.signature.body.tsx

@@ -13,7 +13,7 @@
 /* eslint-disable no-null/no-null */
 import { DefaultThemeRenderContext, ReflectionType, SignatureReflection, JSX } from 'typedoc';
 
-import { hasTypeParameters } from '../../lib';
+import { hasTypeParameters } from '../lib';
 
 export function memberSignatureBody(
     context: DefaultThemeRenderContext,
@@ -24,7 +24,6 @@ export function memberSignatureBody(
 
     return (
         <>
-            {context.reflectionFlags(props)}
             {context.commentSummary(props)}
 
             {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
@@ -34,17 +33,17 @@ export function memberSignatureBody(
                     <h4 class="tsd-parameters-title">{context.i18n.kind_plural_parameter()}</h4>
                     <ul class="tsd-parameter-list">
                         {props.parameters.map((item) => (
-                            <li>
+                            <li class="tsd-parameter-description">
+                                <div class="tsd-parameter-tags">{context.reflectionFlags(item)}</div>
                                 <span>
-                                    {context.reflectionFlags(item)}
                                     {!!item.flags.isRest && <span class="tsd-signature-symbol">...</span>}
                                     <span class="tsd-kind-parameter">{item.name}</span>
                                     {': '}
                                     {context.type(item.type)}
 
                                     {item.defaultValue !== null && (
                                         <span class="tsd-signature-symbol">
-                                            {' = '}
+                                            {item.defaultValue && ' = '}
                                             {item.defaultValue}
                                         </span>
                                     )}

src/partials/members/member.signature.title.tsx

@@ -12,7 +12,7 @@
  */
 import { DefaultThemeRenderContext, ParameterReflection, ReflectionKind, SignatureReflection, JSX } from 'typedoc';
 
-import { getKindClass, join, renderTypeParametersSignature, wbr } from '../../lib';
+import { getKindClass, join, renderTypeParametersSignature, wbr } from '../lib';
 
 function renderParameterWithType(context: DefaultThemeRenderContext, item: ParameterReflection) {
     return (

src/partials/members/member.signatures.tsx

@@ -13,22 +13,22 @@
 import { JSX } from 'typedoc';
 import type { DefaultThemeRenderContext, DeclarationReflection } from 'typedoc';
 
-import { classNames } from '../../lib';
 import { anchorIcon } from '../anchor-icon';
+import { classNames } from '../lib';
 
 export const memberSignatures = (context: DefaultThemeRenderContext, props: DeclarationReflection) => (
     <>
-        <ul class={classNames({ 'tsd-signatures': true }, context.getReflectionClasses(props))}>
+        <div class={classNames({ 'tsd-signatures': true }, context.getReflectionClasses(props))}>
             {props.signatures?.map((item) => (
                 <>
-                    <li class="tsd-signature tsd-anchor-link">
+                    <div class="tsd-signature tsd-anchor-link">
                         <a id={item.anchor} class="tsd-anchor"></a>
                         {context.memberSignatureTitle(item)}
                         {anchorIcon(context, item.anchor)}
-                    </li>
-                    <li class="tsd-description">{context.memberSignatureBody(item)}</li>
+                    </div>
+                    <div class="tsd-description">{context.memberSignatureBody(item)}</div>
                 </>
             ))}
-        </ul>
+        </div>
     </>
 );