Move from marked to markdown-it

Marked has served TypeDoc well for many years, but with Marked 7.0.4, it
is possible for Marked plugins to prevent parsing from being done in a sync
method, which either means that TypeDoc has to render all text to markdown
outside of the normal rendering flow, or refactor that rendering flow to support
async work within random JSX element construction.

markdown-it is also a fully featured markdown parser which has avoided async
code, making it a better fit for TypeDoc. It also makes it ridiculously easy to add
additional rendering capability via plugins.

.config/typedoc.json

@@ -44,5 +44,10 @@
         "includeGroups": false
     },
     "includeVersion": true,
-    "logLevel": "Verbose"
+    "logLevel": "Verbose",
+    "externalSymbolLinkMappings": {
+        "@types/markdown-it": {
+            "MarkdownIt": "https://markdown-it.github.io/markdown-it/#MarkdownIt"
+        }
+    }
 }

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Breaking Changes
 
+-   Drop support for Node 16.
+-   Moved from `marked` to `markdown-it` for parsing as marked has moved to an async model which supporting would significantly complicate TypeDoc's rendering code.
+    This means that any projects setting `markedOptions` needs to be updated to use `markdownItOptions`.
+    Unlike `marked@4`, `markdown-it` pushes lots of functionality to plugins. To use plugins, a JavaScript config file must be used with the `markdownItLoader` option.
 -   Removed deprecated `navigation.fullTree` option.
 -   API: `MapOptionDeclaration.mapError` has been removed.
 -   API: Deprecated `BindOption` decorator has been removed.

example/README.md

@@ -23,7 +23,7 @@ This project shows off some of TypeDoc's features:
 
 -   Built-in support for various TypeScript language constructs
 -   Markdown in doc comments
--   Syntax highligting in code blocks
+-   Syntax highlighting in code blocks
 
 ## Index of Examples
 

example/src/showcase.ts

@@ -2,7 +2,7 @@
  * # Markdown Showcase
  *
  * All comments are parsed as **Markdown**. TypeDoc uses the
- * [Marked](https://github.com/markedjs/marked) markdown parser to _convert
+ * [markdown-it](https://github.com/markdown-it/markdown-it) markdown parser to _convert
  * comments to HTML_.
  *
  * ## Symbol References

package.json

@@ -21,11 +21,11 @@
     "url": "https://github.com/TypeStrong/TypeDoc/issues"
   },
   "engines": {
-    "node": ">= 16"
+    "node": ">= 18"
   },
   "dependencies": {
     "lunr": "^2.3.9",
-    "marked": "^4.3.0",
+    "markdown-it": "^14.1.0",
     "minimatch": "^9.0.4",
     "shiki": "^0.14.7"
   },
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@types/lunr": "^2.3.7",
-    "@types/marked": "^4.0.8",
+    "@types/markdown-it": "^14.0.1",
     "@types/mocha": "^10.0.6",
     "@types/node": "16",
     "@typescript-eslint/eslint-plugin": "^7.7.1",

src/lib/internationalization/translatable.ts

@@ -122,6 +122,7 @@ export const translatable = {
     could_not_empty_output_directory_0: `Could not empty the output directory {0}`,
     could_not_create_output_directory_0: `Could not create the output directory {0}`,
     theme_0_is_not_defined_available_are_1: `The theme '{0}' is not defined. The available themes are: {1}`,
+    custom_theme_does_not_define_getSlugger: `Custom theme does not define a getSlugger(reflection) method, but tries to render markdown`,
 
     // entry points
     no_entry_points_provided:
@@ -218,8 +219,10 @@ export const translatable = {
     help_darkHighlightTheme:
         "Specify the code highlighting theme in dark mode.",
     help_customCss: "Path to a custom CSS file to for the theme to import.",
-    help_markedOptions:
-        "Specify the options passed to Marked, the Markdown parser used by TypeDoc.",
+    help_markdownItOptions:
+        "Specify the options passed to markdown-it, the Markdown parser used by TypeDoc.",
+    help_markdownItLoader:
+        "Specify a callback to be called when loading the markdown-it instance. Will be passed the instance of the parser which TypeDoc will use.",
     help_maxTypeConversionDepth:
         "Set the maximum depth of types to be converted.",
     help_name:
@@ -346,6 +349,7 @@ export const translatable = {
     sitemap_must_start_with_http:
         "sitemapBaseUrl must start with http:// or https://",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object.",
+    option_0_must_be_a_function: "The '{0}' option must be a function.",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values.`,
     visibility_filters_only_include_0: `visibilityFilters can only include the following non-@ keys: {0}`,
     visibility_filters_must_be_booleans: `All values of visibilityFilters must be booleans.`,

src/lib/models/comments/comment.ts

@@ -122,12 +122,14 @@ export class Comment {
 
     /**
      * Helper function to convert an array of comment display parts into markdown suitable for
-     * passing into Marked. `urlTo` will be used to resolve urls to any reflections linked to with
-     * `@link` tags.
+     * passing into markdown-it.
+     * @param urlTo - Used to resolve urls to any reflections linked to with `@link` tags..
+     * @param useHtml - If set, will produce `<a>` links which can be colored according to the reflection type they are pointed at.
      */
     static displayPartsToMarkdown(
         parts: readonly CommentDisplayPart[],
         urlTo: (ref: Reflection) => string,
+        useHtml: boolean,
     ) {
         const result: string[] = [];
 
@@ -158,19 +160,30 @@ export class Comment {
                                         part.target.kind,
                                     );
                                 }
-                                const text =
-                                    part.tag === "@linkcode"
-                                        ? `<code>${part.text}</code>`
-                                        : part.text;
-                                result.push(
-                                    url
-                                        ? `<a href="${url}"${
-                                              kindClass
-                                                  ? ` class="${kindClass}"`
-                                                  : ""
-                                          }>${text}</a>`
-                                        : part.text,
-                                );
+
+                                if (useHtml) {
+                                    const text =
+                                        part.tag === "@linkcode"
+                                            ? `<code>${part.text}</code>`
+                                            : part.text;
+                                    result.push(
+                                        url
+                                            ? `<a href="${url}"${
+                                                  kindClass
+                                                      ? ` class="${kindClass}"`
+                                                      : ""
+                                              }>${text}</a>`
+                                            : part.text,
+                                    );
+                                } else {
+                                    const text =
+                                        part.tag === "@linkcode"
+                                            ? "`" + part.text + "`"
+                                            : part.text;
+                                    result.push(
+                                        url ? `[${text}](${url})` : text,
+                                    );
+                                }
                             } else {
                                 result.push(part.text);
                             }