Deprecate --customTitleLink and --gaMeasurementId

Closes #20
Drarig29 · Sep 5, 2023 · d0473c8 · d0473c8
1 parent b66b16f
commit d0473c8
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -6,9 +6,12 @@
 
 A [TypeDoc](https://github.com/TypeStrong/typedoc) plugin to add extras to the output documentation.
 
-- It can set a custom top-most title name and/or link.
-- It can find the `<head>` of the documents and append a favicon to it.
-- It can also add date/time of generation after "Generated using TypeDoc" in the footer. (cf. the [example](#example) below)
+It allows you to:
+
+- Set a custom favicon.
+- Add the date/time of generation after "Generated using TypeDoc" in the footer. (cf. the [example](#example) below)
+- Set a custom top-most title name (without changing the package name, like `--name` would do).
+  - For example, you could have `--customTitle "Go back" --titleLink <url-of-your-parent-documentation>`
 - And more... (cf. the list of [arguments](#arguments) below)
 
 **No date/time will be added if `--hideGenerator` is set (because the footer wouldn't exist).**
@@ -45,13 +48,9 @@ The following arguments can be used in addition to the default [TypeDoc argument
   Specify a custom title, for the top-most title only.<br>
   Example: `foo`
 
-- `--customTitleLink`<br>
-  Specify a custom link for the top-most title.<br>
-  Example: `https://parent-docs-site.com`
-
 - `--customDescription`<br>
-  Specify a custom meta description.<br>
-  Example: `A test description`
+  Specify a custom `<meta name="description"` property.<br>
+  Example: `An example description`
 
 - `--favicon`<br>
   Specify the path or URL of the favicon file.<br>
@@ -77,10 +76,6 @@ The following arguments can be used in addition to the default [TypeDoc argument
   Default: `false`<br>
   **Note:** If combined with `--footerDate`, it will append "Jul 29, 2022, 3:44:42 PM GMT+2".
 
-- `--gaMeasurementId`<br>
-  Specify a [Google Analytics](https://support.google.com/analytics/answer/1008080?hl=en&ref_topic=1008079#zippy=%2Cin-this-article%2Cstatic-website) measurement ID to insert in a `gtag.js` snippet.<br>
-  Example: `abc123`<br>
-
 ## Testing
 
 To test this plugin, you can generate TypeDoc documentation for this plugin.

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
     "name": "typedoc-plugin-extras",
     "version": "2.3.3",
-    "description": "A TypeDoc plugin to add extras (favicon, generation date, Google Analytics...) to the output documentation",
+    "description": "A TypeDoc plugin to add extras (favicon, description, generation date...) to the output documentation",
     "main": "./dist/main.js",
     "exports": "./dist/main.js",
     "types": "./dist/main.d.ts",

diff --git a/src/helpers.ts b/src/helpers.ts
@@ -1,4 +1,5 @@
-import { PluginOptions } from "./main";
+import type { Application } from "typedoc";
+import type { PluginOptions } from "./main";
 
 /**
  * Creates a relative path from a host file to a target file which is located in the root.
@@ -91,21 +92,6 @@ export function replaceDescription(html: string, description: string): string {
     );
 }
 
-/**
- * Replaces the top-most title link.
- * @param html HTML string to replace into.
- * @param link The new link to set.
- */
-export function replaceTopMostTitleLink(html: string, link: string): string {
-    return html.replace(/(<a href=")([^"]*)(" class="title">)([^<]*)(<\/a>)/,
-        '$1' + // Start of <a>
-        link +
-        '$3' + // The class
-        '$4' + // The title
-        '$5' // End of <a>
-    );
-}
-
 export const getLastModifiedScript = () => {
     // Use English as the locale because we say "Last modified".
     // The title of the element (shown on hover) contains the locale string with the user's timezone.
@@ -156,21 +142,10 @@ export const getDateTimeScript = (options: PluginOptions) => {
     `;
 };
 
-export const insertGAScriptInHead = (html: string, measurementId: string) => {
-    const script = `<!-- Google tag (gtag.js) -->
-<script async src="https://www.googletagmanager.com/gtag/js?id=${measurementId}"></script>
-<script>
-    window.dataLayer = window.dataLayer || [];
-    function gtag(){dataLayer.push(arguments);}
-    gtag('js', new Date());
-
-    gtag('config', '${measurementId}');
-</script>`
-
-    return html.replace('<head>',
-        '<head>' +
-        '\n' +
-        script +
-        '\n'
-    );
+export const deprecatedOption = (app: Application, { name, inFavorOf }: { name: string, inFavorOf: string }) => {
+    if (app.options.getValue(name)) {
+        const error = Error(`[typedoc-plugin-extras] The \`--${name}\` option is deprecated. Please use \`--${inFavorOf}\` instead.`)
+        delete error.stack
+        throw error
+    }
 }
diff --git a/src/main.ts b/src/main.ts
@@ -7,30 +7,32 @@ import {
     makeRelativeToRoot,
     isUrl,
     replaceTopMostTitle,
-    replaceTopMostTitleLink,
     replaceDescription,
     setupNewlineInFooter,
     getLastModifiedScript,
     getDateTimeScript,
-    insertGAScriptInHead
+    deprecatedOption,
 } from './helpers';
 
 const TYPEDOC_VERSION = Application.VERSION;
 
 export const pluginOptions = (app: Application) => ({
-    options: () => ({
-        outDir: app.options.getValue('out') as string | undefined,
-        hideGenerator: app.options.getValue('hideGenerator') as boolean,
-        favicon: app.options.getValue('favicon') as string | undefined,
-        footerDate: app.options.getValue('footerDate') as boolean,
-        footerTime: app.options.getValue('footerTime') as boolean,
-        footerLastModified: app.options.getValue('footerLastModified') as boolean,
-        footerTypedocVersion: app.options.getValue('footerTypedocVersion') as boolean,
-        customTitle: app.options.getValue('customTitle') as string | undefined,
-        customTitleLink: app.options.getValue('customTitleLink') as string | undefined,
-        customDescription: app.options.getValue('customDescription') as string | undefined,
-        gaMeasurementId: app.options.getValue('gaMeasurementId') as string | undefined,
-    }),
+    options: () => {
+        deprecatedOption(app, { name: 'customTitleLink', inFavorOf: 'titleLink' })
+        deprecatedOption(app, { name: 'gaMeasurementId', inFavorOf: 'gaID' })
+
+        return {
+            outDir: app.options.getValue('out') as string | undefined,
+            hideGenerator: app.options.getValue('hideGenerator') as boolean,
+            favicon: app.options.getValue('favicon') as string | undefined,
+            footerDate: app.options.getValue('footerDate') as boolean,
+            footerTime: app.options.getValue('footerTime') as boolean,
+            footerLastModified: app.options.getValue('footerLastModified') as boolean,
+            footerTypedocVersion: app.options.getValue('footerTypedocVersion') as boolean,
+            customTitle: app.options.getValue('customTitle') as string | undefined,
+            customDescription: app.options.getValue('customDescription') as string | undefined,
+        }
+    },
 });
 
 export type PluginOptionsGetter = ReturnType<typeof pluginOptions>;
@@ -80,22 +82,20 @@ export function load(app: Application) {
     });
 
     app.options.addDeclaration({
-        name: 'customTitleLink',
-        help: 'Extras Plugin: Specify a custom link for the top-most title.',
+        name: 'customDescription',
+        help: 'Extras Plugin: Specify a custom description for the website.',
         type: ParameterType.String,
         defaultValue: undefined
     });
 
     app.options.addDeclaration({
-        name: 'customDescription',
-        help: 'Extras Plugin: Specify a custom description for the website.',
-        type: ParameterType.String,
-        defaultValue: undefined
+        name: 'customTitleLink',
+        help: 'Extras Plugin: deprecated. Will be removed in the next release.',
     });
 
     app.options.addDeclaration({
         name: 'gaMeasurementId',
-        help: 'Extras Plugin: Specify a Google Analytics measurement ID to insert in a gtag.js snippet.'
+        help: 'Extras Plugin: deprecated. Will be removed in the next release.'
     });
 
     const options = pluginOptions(app);
@@ -153,20 +153,10 @@ function onPageRendered(this: PluginOptionsGetter, page: PageEvent) {
         page.contents = replaceTopMostTitle(page.contents, options.customTitle);
     }
 
-    // Set custom title link.
-    if (options.customTitleLink) {
-        page.contents = replaceTopMostTitleLink(page.contents, options.customTitleLink);
-    }
-
     // Set custom description.
     if (options.customDescription) {
         page.contents = replaceDescription(page.contents, options.customDescription);
     }
-
-    // Insert Google Analytics script.
-    if (options.gaMeasurementId) {
-        page.contents = insertGAScriptInHead(page.contents, options.gaMeasurementId);
-    }
 }
 
 function onRenderFinished(this: PluginOptionsGetter) {