-
Notifications
You must be signed in to change notification settings - Fork 595
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[api-documenter] Regression in Table Cells escaping with latest version #4586
Comments
The old table formatting didn't inject Can you share a repro? |
@iclanton It's part of our in our class A {
/**
* :::tip
*
* I am a tip
*
* :::
* /
doSomething(){}
} We use things on top of that to make messages more distinguished when people visit the website Example Tip. The problem is that now you emit I can confirm that Here is a Gist to change the When you run the test I the snapshot should sort of pass (most likely some extra new line will be added) for old version. |
I believe you were relying on an implementation detail here rather than on an intentional API. Looking at where that function comes from, it was introduced in #1183 to HTML-escape some characters that could not be rendered in Github-style markdown tables. I don't think it was meant to be extended to add further functionality on top :( To be honest, I missed that function in my PR, or I would probably completely have removed it.
I don't think that this function was meant to prevent XSS in the first place - it was added because type unions could not be displayed in markdown tables. (#1065). Could you maybe elaborate what attack you are foreseeing here, and how you are relying on that? As for your code above to remove |
Some backgroundThere is a longnstanding issue that API Documenter generates "markdown" yet there is no standardized syntax for Markdown. Of course CommonMark is such a standard, but all real world implementations add additional custom syntaxes, and because CommonMark lacks formalized extensibility, such custom syntaxes will always break the ability to parse true CommonMark correctly. As one example, suppose we introduce :::tip
```
[link](http://example.com)
:::
``` Is This mutual intelligibility is a mild inconvenience for human authors, but a major frustration for automated tools such as API Documenter that need to emit thousands of pages of API docs and have them render correctly. (BTW TSDoc explicitly aims to solve this problem by forbidding custom syntaxes and relying instead on HTML elements for advanced custom syntaxes.) What it meansUntil now, API Documenter has aimed to produce a balanced dialect of markdown syntax that is likely to get rendered correctly by the most popular engines (Jekyll and GitHub at the time). Where it doesn't work, people have implemented various hacks like api-documenter-docusaurus-plugin that try rewrite the incorrect expressions. That is exactly what @Lightning00Blade did, too. PR #4578 will break that delicate equilibrium, so unfortunately we probably shouldn't have merged this PR. The safest move may be to revert it. 😅 A better solutionBut how to solve @phryneas's problem then? What we can do instead is introduce api-documenter.json settings to control the output dialect. In this way API Documenter can be optimized for a known Markdown engine rather than trying to be a "least common denominator." We've been planning this already, since Docusuarus 3 has finally adopted standard MDX (whose syntax is based on JSX not CommonMark and thus really needs its own target profile). This week I'll put together a design proposal. |
@octogonz are you sure that's the core of this issue, though? If I am understanding @Lightning00Blade's report correctly, it's not about that it's breaking markdown generation or that the generated markdown isn't parsable in their dialect anymore. They relied on the fact that there was a Of course, I don't know if my change breaks anything else regarding markdown parsing (I believe it should be more stable for most parsers out there, or I wouldn't have opened the PR), but looking at all the related PRs and issues around the generation of that function, it seems like If |
PS: Before you start targeting different Markdown engines (which would probably end up with a ton of work for you guys, both to write and maintain), one suggestion from me: Roll back my change from #4578 and instead consider either a HTML emitter (or a Markdown AST emitter?). |
Firstly I want to clarify that I know we are using internal APIs, that may brake without notice, the burden is on us to fix them (be it with more overwrites or other patches). Also I have reworked some our TsDocs to be more inline with what the transformer is expecting. And no patching is needed anymore. Keeping the bug open (at least) until the functionality is added back or fully remove, based on solely your decisions. |
Thanks for your contribution @phryneas. I appreciate that you solved some issues in that PR, but unfortunately it comes at a price (for me, at least). The problem is that my Markdown renderer (Marked) doesn't, to my knowledge, allow me to customize the HTML output for elements that are already encoded in HTML rather than Markdown syntax. |
Seems that Material for Mkdocs doesn't like HTML tables either. Markdown syntax introduced in there isn't rendered. You can check a (short living) example here: I'd say same would happen for sites powered by Mkdocs but not 100% sure |
Summary
Then running generation of docs I want to have custom escaping for Table cells.
Repro steps
Create a
SpecialCustomMarkdownEmitter
that extendsCustomMarkdownEmitter
.Provide
getTableEscapedText
with custom escape mechanism:Expected:
The TableCell generated don't include
:::
or text starting with:::
Actual:
The TableCell include the aforementioned things.
Details
This is the Pr that introduced the regression - #4578
Standard questions
Please answer these questions to help us investigate your issue more quickly:
@microsoft/api-documenter
version?node -v
)?The text was updated successfully, but these errors were encountered: