@davydog187 commented on Wed Mar 04 2020

Feature Request

Similar to Github style markdown, it would be awesome to be able to annotate code in markdown and have the generator make sure it highlighted it.

e.g.

```json
{
  "key": "value
}
```

```elxir
defmodule Hello do
  def world do
    IO.puts("hello")
  end
end
```

I’d love for this to show up syntax highlighted as it would in Github.

{
  "key": "value"
}

defmodule Hello do
  def world do
    IO.puts("hello")
  end
end

I haven’t checked, but I assume that this project already uses prism.js or highlight.js, so it shouldn’t be too hard to add, assuming that the markdown compiler supported it.

I’m definitely interested in helping build this feature, as well as #202

---

@davydog187 commented on Wed Mar 04 2020

Alright, confirmed that this project uses highlight.js

The JSON that’s highlighted in the right sidebar highlights because its in highlight.js format

<code class="hljs json">

And as far as I can tell, the Markdown is generated using https://github.com/searKing/markdown2html-less which generates the above HTML from the markdown snippet:

<pre>
  <code class="language-json">{
    "key": "value"
  }
  </code>
</pre>
<pre>
<code class="language-elxir">
  defmodule Hello do
     def world do
       IO.puts("hello")
     end
  end
</code>
</pre>

So if we could tell the Markdown parser/compiler to convert to this format, theoretically this is straightforward. Right now it seems that asyncapi-generator uses the simplest Markdown 👉 HTML conversion possible.

---

@derberg commented on Thu Mar 05 2020

@davydog187 Hey man, thanks for reporting this issue. Awesome you are ready to work on it. I hope you do not mind but I have some dummy questions so I can understand what is the scope of this issue. I will also state some clarifications:

• HTML templates uses https://www.npmjs.com/package/markdown-it for Markdown -> HTML rendering
• This is the filter that is later used in the template to parse Markdown into HTML https://github.com/asyncapi/generator-filters/blob/master/src/customFilters.js#L7-L15 and as you can see it is applied to descriptions only as specs defines that CommonMark markdown can be used only in descriptions

Are you injecting some code samples in descriptions? Or this elixir sample is just a sample and has nothing to do with the spec? Best would be if you could share some dummy asyncapi doc example and basing on this doc explain what you get and what you want to get.

Sorry for all those questions/clarifications from my side but I want to be sure we are both on the same page so I can help you

---

@davydog187 commented on Thu Mar 05 2020

Thank you for the reply @derberg!

We are using asyncapi at https://simplebet.io to describe our Kafka feed. To describe some of the semantics of our data, its useful to demonstrate how data might change from message to message. To call a few things out, in the introduction description we are using a few JSON examples. e.g.

asyncapi: 2.0.0
info:
  title: Example
  version: '0.0.9'
  description: |
     This is a description of our feed.
    
     ### Example One
     ```json
     {"key": "value"}
    ```

    yada yad

     ### Example Two
     ```json
     {"key": "value"}
    ```

---

@derberg commented on Thu Mar 05 2020

@davydog187 no worries man, happy yo help. Thanks a lot for these details. I think we soon should introduce a section “AsyncAPI in the wild” where we would for sure have to list you! 🚀

Good my questions were not that dumb after all 😄 you do have code snippets in there in descriptions.

If I would start working on this issue I would definitely try to extend https://github.com/asyncapi/generator-filters/blob/master/src/customFilters.js#L7-L15 filter as it is used all over the place whenever description must be rendered. Description content always goes through that filter like here https://github.com/asyncapi/html-template/blob/master/partials/introduction.html. Try to extend the filter, take a look at markdown-it docs, looks like it is possible to add highlighting https://github.com/markdown-it/markdown-it#syntax-highlighting. Also, if you find a better package that supports highlight.js much easier + CommonMark, feel free to suggest it.

I hope that helps, somehow

---

@davydog187 commented on Fri Mar 06 2020

I think it will. I’ll try to take this on as soon as possible. I really appreciate you onboarding me into the project @derberg! I haven’t written JS in over a year, so looking forward to dipping back in!

---

@github-actions[bot] commented on Wed May 13 2020

This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions ❤️