Skip to content

Commit

Permalink
feat: new option "markedOptions" (#1412)
Browse files Browse the repository at this point in the history
* Add markedOptions option
* Init Marked when rendering begin
* Extend basic example with email address in comment
* Add link to github issue
* Refactoring
  • Loading branch information
krisztianb committed Dec 9, 2020
1 parent a4c3d9e commit 2bf6e49
Show file tree
Hide file tree
Showing 50 changed files with 375 additions and 7 deletions.
5 changes: 5 additions & 0 deletions examples/basic/src/markdown.ts
@@ -0,0 +1,5 @@
/**
* This email address should stay unmangled in the rendered output: president@acme.com
* @see https://github.com/TypeStrong/typedoc/issues/1395
*/
export const emailAddressInComment = true;
36 changes: 30 additions & 6 deletions src/lib/output/plugins/MarkedPlugin.ts
Expand Up @@ -93,12 +93,6 @@ export class MarkedPlugin extends ContextAwareRendererComponent {
Handlebars.registerHelper("relativeURL", (url: string) =>
url ? this.getRelativeUrl(url) : url
);

Marked.setOptions({
highlight: (text: any, lang: any) =>
this.getHighlighted(text, lang),
renderer: customMarkedRenderer,
});
}

/**
Expand Down Expand Up @@ -190,6 +184,8 @@ export class MarkedPlugin extends ContextAwareRendererComponent {
protected onBeginRenderer(event: RendererEvent) {
super.onBeginRenderer(event);

Marked.setOptions(this.createMarkedOptions());

delete this.includes;
if (this.includeSource) {
const includes = Path.resolve(this.includeSource);
Expand Down Expand Up @@ -219,6 +215,34 @@ export class MarkedPlugin extends ContextAwareRendererComponent {
}
}

/**
* Creates an object with options that are passed to the markdown parser.
*
* @returns The options object for the markdown parser.
*/
private createMarkedOptions(): Marked.MarkedOptions {
const markedOptions = (this.application.options.getValue(
"markedOptions"
) ?? {}) as Marked.MarkedOptions;

if (
typeof markedOptions === "object" &&
!Array.isArray(markedOptions)
) {
// Set some default values if they are not specified via the TypeDoc option
markedOptions.highlight ??= (text: any, lang: any) =>
this.getHighlighted(text, lang);
markedOptions.renderer ??= customMarkedRenderer;
markedOptions.mangle ??= false; // See https://github.com/TypeStrong/typedoc/issues/1395

return markedOptions;
}

throw new Error(
"The value provided via the 'markedOptions' option must be a non-array object."
);
}

/**
* Triggered when [[MarkedPlugin]] parses a markdown string.
*
Expand Down
3 changes: 2 additions & 1 deletion src/lib/utils/options/declaration.ts
Expand Up @@ -2,7 +2,7 @@ import { CompilerOptions } from "typescript";
import { IgnoredTsOptionKeys } from "./sources/typescript";

/**
* An interface describing all TypeDoc specific options options. Generated from a
* An interface describing all TypeDoc specific options. Generated from a
* map which contains more information about each option for better types when
* defining said options.
*/
Expand Down Expand Up @@ -89,6 +89,7 @@ export interface TypeDocOptionMap {
plugin: string[];
logger: unknown; // string | Function
listInvalidSymbolLinks: boolean;
markedOptions: unknown;
}

/**
Expand Down
6 changes: 6 additions & 0 deletions src/lib/utils/options/sources/typedoc.ts
Expand Up @@ -233,4 +233,10 @@ export function addTypeDocOptions(options: Options) {
"Emits a list of broken symbol [[navigation]] links after documentation generation",
type: ParameterType.Boolean,
});
options.addDeclaration({
name: "markedOptions",
help:
"Specify the options passed to Marked, the Markdown parser used by TypeDoc",
type: ParameterType.Mixed,
});
}
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_access_.privateclass.html
Expand Up @@ -206,6 +206,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_classes_.baseclass.html
Expand Up @@ -473,6 +473,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_classes_.genericclass.html
Expand Up @@ -325,6 +325,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_classes_.internalclass.html
Expand Up @@ -161,6 +161,9 @@ <h4 class="tsd-returns-title">Returns <a href="_classes_.internalclass.html" cla
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -306,6 +306,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_classes_.subclassa.html
Expand Up @@ -595,6 +595,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_classes_.subclassb.html
Expand Up @@ -448,6 +448,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -197,6 +197,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -198,6 +198,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -441,6 +441,9 @@ <h3>union<wbr>And<wbr>Function</h3>
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/classes/_mixin_.base.html
Expand Up @@ -158,6 +158,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">number</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class="current tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -254,6 +254,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Mixin2</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class="current tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -196,6 +196,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -197,6 +197,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/enums/_enumerations_.directions.html
Expand Up @@ -197,6 +197,9 @@ <h3>Top<wbr>Right</h3>
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/enums/_enumerations_.size.html
Expand Up @@ -219,6 +219,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
4 changes: 4 additions & 0 deletions src/test/renderer/specs/globals.html
Expand Up @@ -77,6 +77,7 @@ <h3>Modules</h3>
<li class="tsd-kind-module"><a href="modules/_flattened_.html" class="tsd-kind-icon">&quot;flattened&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_functions_.html" class="tsd-kind-icon">&quot;functions&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_generics_.html" class="tsd-kind-icon">&quot;generics&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_markdown_.html" class="tsd-kind-icon">&quot;markdown&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_mixin_.html" class="tsd-kind-icon">&quot;mixin&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_mod_.html" class="tsd-kind-icon">&quot;mod&quot;</a></li>
<li class="tsd-kind-module"><a href="modules/_mod2_.html" class="tsd-kind-icon">&quot;mod2&quot;</a></li>
Expand Down Expand Up @@ -116,6 +117,9 @@ <h3>Modules</h3>
<li class=" tsd-kind-module">
<a href="modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/index.html
Expand Up @@ -143,6 +143,9 @@ <h2>Repeated Heading</h2>
<li class=" tsd-kind-module">
<a href="modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -208,6 +208,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -159,6 +159,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
Expand Up @@ -249,6 +249,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_generics_.a.html
Expand Up @@ -166,6 +166,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">T</span><
<li class="current tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_generics_.ab.html
Expand Up @@ -231,6 +231,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class="current tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_generics_.abnumber.html
Expand Up @@ -206,6 +206,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class="current tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_generics_.abstring.html
Expand Up @@ -206,6 +206,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class="current tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_generics_.b.html
Expand Up @@ -203,6 +203,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class="current tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_mixin_.mixin1type.html
Expand Up @@ -198,6 +198,9 @@ <h4 class="tsd-returns-title">Returns <a href="_mixin_.mixin1type.html" class="t
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class="current tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/interfaces/_mixin_.mixin2.html
Expand Up @@ -231,6 +231,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Mixin2</s
<li class=" tsd-kind-module">
<a href="../modules/_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="../modules/_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class="current tsd-kind-module">
<a href="../modules/_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/modules/_access_.html
Expand Up @@ -200,6 +200,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down
3 changes: 3 additions & 0 deletions src/test/renderer/specs/modules/_access_.privatemodule.html
Expand Up @@ -139,6 +139,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</spa
<li class=" tsd-kind-module">
<a href="_generics_.html">&quot;generics&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="_markdown_.html">&quot;markdown&quot;</a>
</li>
<li class=" tsd-kind-module">
<a href="_mixin_.html">&quot;mixin&quot;</a>
</li>
Expand Down

0 comments on commit 2bf6e49

Please sign in to comment.