Reduce manually maintained duplication in generated site

Author: Gerrit0

site/options.md

@@ -13,148 +13,43 @@ children:
 Any command line arguments that are passed without a flag will be parsed as entry points.
 Any options passed on the command line will override options set in a configuration file.
 
-<!--
-Updating these lists can be easily done by going to each page and running the
-following JS to copy what they should be to your clipboard. Ideally, someday this
-becomes automated...
-
-copy($$(".tsd-page-navigation > .tsd-accordion-details > a").map(a => [a.textContent, a.href.substring(a.href.lastIndexOf("/") + "/Options.".length).replace(/^./, x => x[0].toLowerCase()).replace(".html", ".md").replace("md:", "")]).map(l => `-   [${l[0]}](options/${l[1]})`).join("\n"))
--->
-
 ## Configuration Options
 
 Options which control what files TypeDoc reads.
 
--   [options](options/configuration.md#options)
--   [tsconfig](options/configuration.md#tsconfig)
--   [compilerOptions](options/configuration.md#compileroptions)
--   [plugin](options/configuration.md#plugin)
+{@listOptions options/configuration.md}
 
 ## Input Options
 
 Options which control how input is converted into a project that can be rendered
 to HTML or JSON.
 
--   [entryPoints](options/input.md#entrypoints)
--   [entryPointStrategy](options/input.md#entrypointstrategy)
--   [packageOptions](options/input.md#packageoptions)
--   [alwaysCreateEntryPointModule](options/input.md#alwayscreateentrypointmodule)
--   [projectDocuments](options/input.md#projectdocuments)
--   [exclude](options/input.md#exclude)
--   [externalPattern](options/input.md#externalpattern)
--   [excludeExternals](options/input.md#excludeexternals)
--   [excludeNotDocumented](options/input.md#excludenotdocumented)
--   [excludeNotDocumentedKinds](options/input.md#excludenotdocumentedkinds)
--   [excludeInternal](options/input.md#excludeinternal)
--   [excludePrivate](options/input.md#excludeprivate)
--   [excludeProtected](options/input.md#excludeprotected)
--   [excludeReferences](options/input.md#excludereferences)
--   [excludeCategories](options/input.md#excludecategories)
--   [maxTypeConversionDepth](options/input.md#maxtypeconversiondepth)
--   [name](options/input.md#name)
--   [includeVersion](options/input.md#includeversion)
--   [disableSources](options/input.md#disablesources)
--   [sourceLinkTemplate](options/input.md#sourcelinktemplate)
--   [gitRevision](options/input.md#gitrevision)
--   [gitRemote](options/input.md#gitremote)
--   [disableGit](options/input.md#disablegit)
--   [readme](options/input.md#readme)
--   [includeHierarchySummary](options/input.md#includehierarchysummary)
+{@listOptions options/input.md}
 
 ## Output Options
 
 Options which control TypeDoc's HTML output.
 
--   [outputs](options/output.md#outputs)
--   [out](options/output.md#out)
--   [html](options/output.md#html)
--   [json](options/output.md#json)
--   [pretty](options/output.md#pretty)
--   [emit](options/output.md#emit)
--   [theme](options/output.md#theme)
--   [lightHighlightTheme](options/output.md#lighthighlighttheme)
--   [darkHighlightTheme](options/output.md#darkhighlighttheme)
--   [highlightLanguages](options/output.md#highlightlanguages)
--   [typePrintWidth](options/output.md#typeprintwidth)
--   [customCss](options/output.md#customcss)
--   [customJs](options/output.md#customjs)
--   [customFooterHtml](options/output.md#customfooterhtml)
--   [customFooterHtmlDisableWrapper](options/output.md#customfooterhtmldisablewrapper)
--   [markdownItOptions](options/output.md#markdownitoptions)
--   [markdownItLoader](options/output.md#markdownitloader)
--   [basePath](options/output.md#basepath)
--   [cname](options/output.md#cname)
--   [favicon](options/output.md#favicon)
--   [sourceLinkExternal](options/output.md#sourcelinkexternal)
--   [markdownLinkExternal](options/output.md#markdownlinkexternal)
--   [lang](options/output.md#lang)
--   [locales](options/output.md#locales)
--   [githubPages](options/output.md#githubpages)
--   [cacheBust](options/output.md#cachebust)
--   [hideGenerator](options/output.md#hidegenerator)
--   [searchInComments](options/output.md#searchincomments)
--   [searchInDocuments](options/output.md#searchindocuments)
--   [cleanOutputDir](options/output.md#cleanoutputdir)
--   [titleLink](options/output.md#titlelink)
--   [navigationLinks](options/output.md#navigationlinks)
--   [sidebarLinks](options/output.md#sidebarlinks)
--   [navigation](options/output.md#navigation)
--   [headings](options/output.md#headings)
--   [sluggerConfiguration](options/output.md#sluggerconfiguration)
--   [navigationLeaves](options/output.md#navigationleaves)
--   [visibilityFilters](options/output.md#visibilityfilters)
--   [searchCategoryBoosts](options/output.md#searchcategoryboosts)
--   [searchGroupBoosts](options/output.md#searchgroupboosts)
--   [hostedBaseUrl](options/output.md#hostedbaseurl)
--   [useHostedBaseUrlForAbsoluteLinks](options/output.md#usehostedbaseurlforabsolutelinks)
--   [useFirstParagraphOfCommentAsSummary](options/output.md#usefirstparagraphofcommentassummary)
+{@listOptions options/output.md}
 
 ## Comment Options
 
 Options which control how TypeDoc parses comments.
 
--   [commentStyle](options/comments.md#commentstyle)
--   [useTsLinkResolution](options/comments.md#usetslinkresolution)
--   [preserveLinkText](options/comments.md#preservelinktext)
--   [jsDocCompatibility](options/comments.md#jsdoccompatibility)
--   [suppressCommentWarningsInDeclarationFiles](options/comments.md#suppresscommentwarningsindeclarationfiles)
--   [blockTags](options/comments.md#blocktags)
--   [inlineTags](options/comments.md#inlinetags)
--   [modifierTags](options/comments.md#modifiertags)
--   [cascadedModifierTags](options/comments.md#cascadedmodifiertags)
--   [excludeTags](options/comments.md#excludetags)
--   [notRenderedTags](options/comments.md#notrenderedtags)
--   [externalSymbolLinkMappings](options/comments.md#externalsymbollinkmappings)
+{@listOptions options/comments.md}
 
 ## Organization Options
 
 Controls how TypeDoc organizes content within a converted project.
 
--   [groupReferencesByType](options/organization.md#groupreferencesbytype)
--   [categorizeByGroup](options/organization.md#categorizebygroup)
--   [defaultCategory](options/organization.md#defaultcategory)
--   [categoryOrder](options/organization.md#categoryorder)
--   [groupOrder](options/organization.md#grouporder)
--   [sort](options/organization.md#sort)
--   [sortEntryPoints](options/organization.md#sortentrypoints)
--   [kindSortOrder](options/organization.md#kindsortorder)
+{@listOptions options/organization.md}
 
 ## Validation Options
 
 Configures the validation performed by TypeDoc on a converted project.
 
--   [validation](options/validation.md#validation)
--   [treatWarningsAsErrors](options/validation.md#treatwarningsaserrors)
--   [treatValidationWarningsAsErrors](options/validation.md#treatvalidationwarningsaserrors)
--   [intentionallyNotExported](options/validation.md#intentionallynotexported)
--   [requiredToBeDocumented](options/validation.md#requiredtobedocumented)
+{@listOptions options/validation.md}
 
 ## Other Options
 
--   [watch](options/other.md#watch)
--   [preserveWatchOutput](options/other.md#preservewatchoutput)
--   [help](options/other.md#help)
--   [version](options/other.md#version)
--   [showConfig](options/other.md#showconfig)
--   [logLevel](options/other.md#loglevel)
--   [skipErrorChecking](options/other.md#skiperrorchecking)
+{@listOptions options/other.md}

site/site-plugin.js

@@ -0,0 +1,89 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Application, Converter, OptionDefaults } from "typedoc";
+/** @import { CommentDisplayPart, FileRegistry, TranslatedString} from "typedoc" */
+
+/** @param {Application} app */
+export function load(app) {
+    app.on(Application.EVENT_BOOTSTRAP_END, () => {
+        app.options.setValue("inlineTags", [
+            ...OptionDefaults.inlineTags,
+            "@listOptions",
+        ]);
+    });
+
+    app.converter.on(Converter.EVENT_CREATE_DOCUMENT, (_ctx, doc) => {
+        // Known we have this as documents always have a file path
+        const fileName = /** @type {string} */ (
+            doc.project.files.getReflectionPath(doc)
+        );
+
+        replaceListOptions(fileName, doc.content, doc.project.files);
+    });
+
+    /**
+     *
+     * @param {string} sourceFile
+     * @param {CommentDisplayPart[]} parts
+     * @param {FileRegistry} files
+     */
+    function replaceListOptions(sourceFile, parts, files) {
+        for (let i = 0; i < parts.length; ++i) {
+            const part = parts[i];
+            if (part.kind === "inline-tag" && part.tag === "@listOptions") {
+                parts.splice(
+                    i,
+                    1,
+                    ...buildListOptions(sourceFile, part.text.trim(), files),
+                );
+            }
+        }
+    }
+
+    /**
+     * @param {string} sourceFile
+     * @param {string} userPath
+     * @param {FileRegistry} files
+     * @returns {CommentDisplayPart[]}
+     */
+    function buildListOptions(sourceFile, userPath, files) {
+        const file = join(dirname(sourceFile), userPath.trim());
+
+        /** @type {string[]} */
+        const headings = [];
+        const content = readFileSync(file, "utf-8");
+        for (const line of content.split("\n")) {
+            if (line.startsWith("## ")) {
+                headings.push(line.substring(3).trim());
+            }
+        }
+
+        /** @type {CommentDisplayPart[]} */
+        const result = [];
+
+        for (const heading of headings) {
+            result.push({ kind: "text", text: `- [${heading}](` });
+            const text = userPath + "#" + heading.toLowerCase();
+            const relPath = files.register(sourceFile, text);
+            if (!relPath) {
+                app.logger.warn(
+                    /** @type {TranslatedString} */ (
+                        `@listOptions specified a file "${text}" which does not exist`
+                    ),
+                );
+                return [];
+            }
+
+            result.push({
+                kind: "relative-link",
+                target: relPath?.target,
+                targetAnchor: relPath?.anchor,
+                text,
+            });
+            result.push({ kind: "text", text: ")\n" });
+        }
+
+        return result;
+    }
+}

site/typedoc.config.jsonc

@@ -7,7 +7,7 @@
     "alwaysCreateEntryPointModule": true,
     "out": "../docs-site",
     "name": "TypeDoc",
-    "plugin": ["./typedoc-plugin-redirect.js"],
+    "plugin": ["./typedoc-plugin-redirect.js", "./site-plugin.js"],
 
     "readme": "index.md",
     "projectDocuments": [

src/lib/converter/converter.ts

@@ -191,6 +191,14 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
     static readonly EVENT_CREATE_DECLARATION =
         ConverterEvents.CREATE_DECLARATION;
 
+    /**
+     * Triggered when the converter has created a document reflection.
+     * The listener will be given `undefined` (for consistency with the
+     * other create events) and a {@link Models.DocumentReflection}.
+     * @event
+     */
+    static readonly EVENT_CREATE_DOCUMENT = ConverterEvents.CREATE_DOCUMENT;
+
     /**
      * Triggered when the converter has created a signature reflection.
      * The listener will be given {@link Context}, {@link Models.SignatureReflection} | {@link Models.ProjectReflection} the declaration,