diff --git a/CHANGELOG.md b/CHANGELOG.md index 498af2f..8438aa2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.1.0] - 2022-10-26 +### Changes +- Option value `inIncludedFiles` now also applies to all included markdown files. + ## [2.0.0] - 2022-07-09 ### Breaking Changes - Support changed to TypeDoc versions 0.23.x due to a breaking change in TypeDoc's API. @@ -14,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [1.0.0] - 2022-04-07 First release -[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-text/compare/v2.0.0...HEAD +[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-text/compare/v2.1.0...HEAD +[2.1.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v2.1.0 [2.0.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v2.0.0 [1.0.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v1.0.0 diff --git a/README.md b/README.md index ef0d9a0..6f63d9e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,8 @@ This is a plugin for [TypeDoc](https://github.com/TypeStrong/typedoc) that repla This includes: - Text in code comments -- Text in the README +- Text in the main README +- Text in [included markdown files](https://typedoc.org/guides/options/#includes) You can specify matching patterns and the text they should be replaced with. @@ -15,10 +16,9 @@ This can be useful for: - Creating links from ticket IDs (eg: replace "GH-12345" with a link to https://github.com/your-name/the-repo/issues/12345) - Creating links from author names (eg: link "Your Name" to your GitHub or corporate profile page) -- Replacing internal URLs with external ones +- Replacing internal URLs (domains) with external ones - Replacing custom placeholders with anything you like (eg: images) -- Remove or replace text in your README.md file that is included by TypeDoc -- Remove URLs or other text +- Removing URLs or other text from your documentation - etc. ## Installation @@ -64,7 +64,7 @@ Explanation: | --------------------- | ----------------------------------------------------------------------------- | | **inCodeCommentText** | Specifies if the plugin should replace in the text of comments (not including the text of tags like the description of parameters for a method) in your code. (optional - defaults to `true`) | | **inCodeCommentTags** | Specifies if the plugin should replace in the text of tags (like the description of parameters for a method) in your code comments. (optional - defaults to `true`) | -| **inIncludedFiles** | Specifies if the plugin should replace in your README file. (optional - defaults to `true`) | +| **inIncludedFiles** | Specifies if the plugin should replace in included markdown files (this includes the main README). (optional - defaults to `true`) | | **replacements** | The search patterns and texts they should be replaced with. (`pattern` is the search Regex, `flags` are the optional Regex flags that default to `g` and `replace` is the inserted text) | ## Bugs diff --git a/package.json b/package.json index e41b6e4..64862ac 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "typedoc-plugin-replace-text", - "version": "2.0.0", + "version": "2.1.0", "description": "Plugin for TypeDoc that replaces text in the documentation", "author": { "name": "Krisztián Balla", diff --git a/src/plugin.ts b/src/plugin.ts index e9ae2d9..f6678b8 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -1,4 +1,4 @@ -import { Application, CommentDisplayPart, Context, Converter } from "typedoc"; +import { Application, CommentDisplayPart, Context, Converter, MarkdownEvent } from "typedoc"; import { PluginOptions } from "./plugin_options"; /** @@ -10,8 +10,7 @@ import { PluginOptions } from "./plugin_options"; * * # How does it do it? * - * The plugin scans through all comments of all reflections and uses the replacment patterns specified - * by the user to replace texts. + * The plugin scans through all comments of all reflections and uses the replacment patterns specified by the user. */ export class Plugin { /** The options of this plugin. */ @@ -32,48 +31,63 @@ export class Plugin { * @param typedoc The TypeDoc application. */ private subscribeToApplicationEvents(typedoc: Readonly): void { - typedoc.converter.on(Converter.EVENT_BEGIN, (c: Readonly) => this.onConverterBegin(c)); - typedoc.converter.on(Converter.EVENT_RESOLVE_BEGIN, (c: Readonly) => this.onConverterResolveBegin(c)); + typedoc.converter.on(Converter.EVENT_BEGIN, (c: Readonly) => this.onTypeDocConverterBegin(c)); + typedoc.converter.on(Converter.EVENT_RESOLVE_BEGIN, (c: Readonly) => + this.onTypeDocConverterResolveBegin(c), + ); + + // The priority makes sure that our event handler is called before TypeDoc converts the markdown content + typedoc.renderer.on(MarkdownEvent.PARSE, (e: MarkdownEvent) => this.onTypeDocMarkdownParse(e), typedoc, 100); } /** - * Triggered when the converter begins converting a project. - * @param context Describes the current state the converter is in. + * Triggered when the TypeDoc converter begins converting a project. + * @param context Describes the current state the TypeDoc converter is in. */ - public onConverterBegin(context: Readonly): void { - this.options.readValuesFromApplication(context.converter.owner); + public onTypeDocConverterBegin(context: Readonly): void { + this.options.readValuesFromTypeDocApplication(context.converter.owner); } /** * Triggered when the TypeDoc converter begins resolving a project. - * @param context Describes the current state the converter is in. + * @param context Describes the current state the TypeDoc converter is in. */ - public onConverterResolveBegin(context: Readonly): void { + public onTypeDocConverterResolveBegin(context: Readonly): void { if (!this.hasSomethingTodo) { return; } const project = context.project; - if (this.options.replaceInIncludedFiles && project.readme) { - this.applyReplacementsTo(project.readme); - } - // go through all the reflections' comments for (const key in project.reflections) { const reflection = project.reflections[key]; if (reflection.comment) { if (this.options.replaceInCodeCommentText) { - this.applyReplacementsTo(reflection.comment.summary); + this.applyReplacementsToCommentParts(reflection.comment.summary); } if (this.options.replaceInCodeCommentTags) { - reflection.comment.blockTags.forEach((tag) => this.applyReplacementsTo(tag.content)); + reflection.comment.blockTags.forEach((tag) => this.applyReplacementsToCommentParts(tag.content)); } } } } + /** + * Triggered when the TypeDoc renderer parses a Markdown file. + * @param event Markdown parsing event information. + */ + public onTypeDocMarkdownParse(event: MarkdownEvent): void { + if (!this.hasSomethingTodo) { + return; + } + + if (this.options.replaceInIncludedFiles) { + event.parsedText = this.applyReplacementsToString(event.parsedText); + } + } + /** * Checks if the plugin is configured in a way that it has something to do. * @returns True, if the plugin has something to do, otherwise false. @@ -91,9 +105,22 @@ export class Plugin { * Applies the replacements to the given text parts. * @param parts The text parts on which to apply the replacements. */ - private applyReplacementsTo(parts: CommentDisplayPart[]): void { + private applyReplacementsToCommentParts(parts: CommentDisplayPart[]): void { parts.forEach((part) => { - this.options.replacements.forEach((r) => (part.text = part.text.replace(r.regex, r.replace))); + part.text = this.applyReplacementsToString(part.text); }); } + + /** + * Applies the replacements to the given string. + * @param str The string on which to apply the replacements. + * @returns The string with the replacements applied to it. + */ + private applyReplacementsToString(str: string): string { + let result = str; + + this.options.replacements.forEach((r) => (result = result.replace(r.regex, r.replace))); + + return result; + } } diff --git a/src/plugin_options.ts b/src/plugin_options.ts index 38a9458..f265d5f 100644 --- a/src/plugin_options.ts +++ b/src/plugin_options.ts @@ -86,7 +86,7 @@ export class PluginOptions { * Reads the values of the plugin options from the application options. * @param typedoc The TypeDoc application. */ - public readValuesFromApplication(typedoc: Readonly): void { + public readValuesFromTypeDocApplication(typedoc: Readonly): void { // Yes, this type assertion sucks, but there's something wrong with the Type Definitions of TypeDoc const config = typedoc.options.getValue("replaceText") as unknown as PluginConfig | undefined;