Rendering of CommonMark does not produce expected output

[marcortw]

Describe the bug

When I create an output of the streetlights example, I don't get anymore nicely rendered output as it used to be. I thought it had something to do with a missing main.css file (see this PR), but fixing this locally didn't do the trick.

How to Reproduce

Create a new repo and npm install @asyncapi/[email protected]
Create a minimal example like this:

const path = require("path");
const Generator = require("@asyncapi/generator");
const generator = new Generator("@asyncapi/html-template",path.resolve(__dirname, "example"),{ forceWrite: true });

(async () => {
  try {
    await generator.generateFromURL(
      "https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml"
    );
    console.log("Done!");
  } catch (e) {
    console.error(e);
  }
})();

This produces output like this:

Expected behavior

I used to get output like this (this worked until @asyncapi/[email protected] but not anymore afterwards):

Notice the bullet items which come from this CommonMark formatted section in the spec:

  description: |
    The Smartylighting Streetlights API allows you to remotely manage the city lights.

    ### Check out its awesome features:

    * Turn a specific streetlight on/off 🌃
    * Dim a specific streetlight 😎
    * Receive real-time information about environmental lighting conditions 📈

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[Theiaz]

This could be caused by tailwind and its CSS reset, which may omit styling with bullet points. I will investigate this.

[Theiaz]

Seems like Tailwind uses list-style-type: none as default (see here).

Question now is, if no bullet points are a desired behaviour or we do want to display bullet points. I think we want to display them, so I'm creating a PR soon.

[derberg]

yeap, we definitely should support rendering on the bullet points

[derberg]

@Theiaz shouldn't this be enough ?

    corePlugins: {
      // ...

     listStyleType: false,
    }

[Theiaz]

I don't think that this will work, cause it deactivate classes for styling lists. You can not use any class from here anymore. I had a quick look at the code and it seems like this problem could not be solved that easily. If you add styliing manually (for example with li {list-style-type: disc} in main.css), other parts of UI would also be affected

We need to styline the markdown section separatly:

// introduction.html
...
  <div class="markdown">
    {{ asyncapi.info().description() | markdown2html | safe }}
  </div>

Maybe the simplest solution could be something like .markdown li { list-style-type: disc;}, but I need to investigate it a little bit more. I will dig into it on friday.

[marcortw]

Thanks in advance @Theiaz and @derberg and let me know if I can be of any help. For those who come by here: I am currently getting my bullet items back by defining a specific version like this:

const generator = new Generator("@asyncapi/[email protected]",path.resolve(__dirname, "example"),{ forceWrite: true });

[Theiaz]

FInally I had some time and found the issue. Tailwind changed its default styling for list items. Due to the migration from v0.x to v2.x this needs to be applied. I did not noticed it, because it only affects the markdown part and in my test file there has not been one.

To fix this issue list styles are applied for markdown nodes.

.markdown :is(ol, ul) {
  padding-inline-start: 40px;
  list-style-type: disc;
}

Additionally I've fixed a little color issue.

Related Pull Request

[asyncapi-bot]

🎉 This issue has been resolved in version 0.17.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[chatne]

The fix was done solely on main.css which is not included in the index.html when singleFile param is false. Therefore changes are not present and markdown lists do not render.

Weirdly enough the fix seems to have been done to tailwind.min.css in commit df9c9c7 but this commit is not included in the release.

In package.json there is a script for tailwind css generation. If this is used why include main.css in the index.html at all?

[chatne]

Looks like v0.17.1 was tagged incorrectly: v0.17.1...master

[dweber019]

Late to the game but at least the current playground version doesn't support other styling of commonmark either.
E.g. bold and the list goes on

Im writing AsyncAPI for our governance in a bigger enterprise and to have styling in any description field according to commonmark is crucial.

[derberg]

@dweber019 can you provide more details on this in a separate issue, where you want to use markdown and where it is not supported. Some screenshots and example spec would help a lot