Markdown plugin inserts unnecessary escape characters

[Zamiell]

Hello, and thanks for the plugin.

What typedoc-plugin-markdown currently does

In the Markdown format, underscores are used to denote italics and bold. Thus, this plugin zealously escapes them at every opportunity.

For example, if you have an enum member called FALLING_ACCELERATION, then the resulting Markdown section generated by this plugin would look like this:

### FALLING\_ACCELERATION

However, in this case, the escape characters are not needed, as the Markdown parser is smart enough to know that this is a single word denoting a string literal. So, typedoc-plugin-markdown is inserting the backslash for no reason.

But having some extra escape characters in the Markdown output does not hurt anything. Or does it?

Why it is bad

Escape characters cause MDX to split a word into multiple text nodes. This kind of thing breaks indexing services (e.g. Algolia and Typesense). In other words, it becomes impossible to search for "FALLING_ACCELERATION".

See this issue on the Docusaurus repo for more info.

So, I propose typedoc-plugin-markdown should be smarter about inserting escape characters, and only insert them when absolutely necessary.

Solutions

As you probably know, Prettier is the most popular formatter right now. If you run Prettier on the Markdown files that typedoc-plugin-markdown generates, it is able to identify any useless escape characters and automatically remove them. Right now, this is the method that I am using to work around this issue.

A maximally lazy solution might involve pulling in Prettier as a dependency of this project, and then using Prettier to format the resulting Markdown output that this plugin generates.

(This would also have the benefit of cleaning up the output and making it more standards-compliant.)

Another option is to have Prettier as a peer dependency, and then automatically format with Prettier if it happens to be installed in the current project.

[tgreyuk]

Fair point - the escape should be smarter and thanks for suggestions. Ideally would like to come up with something that doesn't rely on prettier but would need to identify all the use cases first. The aim would be to align with what Prettier does - i'd need to investigate further.

[tgreyuk]

Actually on reflection having looked at this - I like the idea of utilising prettier as an optional peer dependency with a 'usePrettier' option (or maybe like you say just do it automatically if prettier is installed) . Users could then utilise all the other formatting features in addition to the character escaping.

[Zamiell]

Sounds good to me. But I think that instead of having a "usePrettier" option, it should just be the default. Doing that would prevent people from falling into this trap, which wastes an enormous amount of time. I would even go one step further, and if the plugin cannot find Prettier locally installed, it should explicitly warn the user like this:

WARNING: Prettier was not detected, so the outputted Markdown files will not be formatted and may have unnecessary escape characters, which may mess up parsers (such as MDX) and search engine indexers (such as DocSearch).

[tgreyuk]

~Just an FYI this is now built into the next pre-release version. Decided to just go with Prettier as a peer dependency. Have added a paragraph to the Readme https://github.com/tgreyuk/typedoc-plugin-markdown/tree/next/packages/typedoc-plugin-markdown#usage /~

[tgreyuk]

Sorry its been a while on this one :) In the end I decided to pass this onto another plugin I created typedoc-plugin-remark.

Example output: https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/examples/09-remark-example#prettier

Config: https://github.com/typedoc2md/typedoc-plugin-markdown-examples/blob/main/examples/09-remark-example/typedoc.json

Marking the issue as closed but happy to discuss further if this is still of interest.