Altair: Support markdown in descriptions

[jaydenseric]

Is your feature request related to a problem? Please describe.
Other clients such as GraphiQL and GraphQL Playground render description markdown, which is incredibly useful for documenting code (using backticks) or linking to further documentation.

Describe the solution you'd like
Markdown content in field and value descriptions should render as HTML in the documentation explorer.

Describe alternatives you've considered
N/A.

Additional context
Altair:

GraphQL Playground:

[ceefour]

How do I enable this? I'm using 2.3.3 and I still get plain text, not Markdown. See below (compared to GraphiQL):

I do something wrong, or is it regression?

[imolorhe]

I don't think it is a regression. Most likely the markdown parser used in Altair doesn't parse the lists as expected. Other markdown syntaxes (like tilde for code) works. You can create an issue for the list syntax and I'll look into it further.

[ceefour]

Not just the list syntax. Even newlines don't work. i.e. this:

B

becomes A B in Altair, instead of the proper "A" and "B" as two paragraphs.

[imolorhe]

Can you verify that other things like code highlight, headings, links work? It might be an issue with the newline (cr lf)

Are you on Windows?

[ceefour]

@imolorhe Yes I am on Windows 10 1903.

No Markdown works, not even bold. See comparison of test description GraphiQL (top) vs Altair (bottom):

As you can see Altair simply renders the description as plain text, markdown markup untouched.

[imolorhe]

Thanks for that. I'll look into it thoroughly now.

[imolorhe]

@ceefour I'm struggling to figure out what the issue is here. I was able to verify that the descriptions are parsed as markdown (see screenshot below). The only assumption I can make now is that there is something specifically wrong with the implementation for windows machines. Could you also try to use the browser extensions, and see if the problem persists there? Also try navigating back and forth in the docs to see if it is a problem of getting the updated description from the new schema.

[ceefour]

Test results:

• Chrome extension on Windows 10 1903

• Web page on Chrome on Windows 10 1903

• Firefox extension on Windows 10 1903

I'm willing to help by, e.g. turn on debugging flags, etc. if you let me know to do so.

[imolorhe]

@ceefour If you are still willing to help debug this, you can clone the repo locally and try running the app locally. We use https://www.npmjs.com/package/ngx-markdown to convert to markdown.

You can see the usage of the markdown library here:

https://github.com/imolorhe/altair/blob/7f04783c814cbeb4e7da80a1575399b5bd5a4c8e/src/app/components/doc-viewer/doc-viewer-type/doc-viewer-type.component.html#L10

https://github.com/imolorhe/altair/blob/7f04783c814cbeb4e7da80a1575399b5bd5a4c8e/src/app/components/doc-viewer/doc-viewer-field/doc-viewer-field.component.html#L8

npm

ngx-markdown

Angular library that uses marked to parse markdown to html combined with Prism.js for synthax highlights

[jodinathan]

it is not working on my mac either

[ceefour]

thanks @jodinathan. Nice to know this isn't isolated

[imolorhe]

@jodinathan @ceefour Is it possible to host the GraphQL server with the description issue somewhere I can access it? Or perhaps a link to a repo where I can try to reproduce this issue. Unless I can reproduce it, there's no way I would know what I need to do to fix it for you guys.

[jodinathan]

@jodinathan @ceefour Is it possible to host the GraphQL server with the description issue somewhere I can access it? Or perhaps a link to a repo where I can try to reproduce this issue. Unless I can reproduce it, there's no way I would know what I need to do to fix it for you guys.

this is the result of clicking the "reload docs" button. I guess you can force altair to load this instead of a server call

introspection.txt.zip

[imolorhe]

Thanks @jodinathan. That was helpful. I figured out the issue. The markdown rendering isn't being applied to all the description spots (not being applied to type fields and implementations). The reason I couldn't reproduce it is I was testing with a custom type which would have its description displayed when viewing it, but that wouldn't be the case for primitive types.

I've now fixed this and it should be available in the next version 🙂

Ps: You can export the SDL for the schema from the dropdown menu in the docs. It's easier to use than the data dump of the introspection 😉Also that's what it is there for 😄