Add information about required CSS to the README

[IncPlusPlus]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

While trying to use this package, I noticed that none of the expected GitHub styling was being applied to my markdown. I thought that the issue potentially was some styling inherited from the fact that my app uses Material UI. After doing some inspecting of my rendered markdown versus the example from the react-markdown repo, I realized I hadn't even checked if there was any CSS that the example was using. There was! I'm still a novice in terms of web development and had assumed that this package would manage the styling. While the HTML was ready for styling, there was no CSS to apply to it and I spent a long amount of time just to figure that out.

Naturally, after already figuring this out, I encounter this helpful comment and this note from the remark-rehype repo. Such is life, I suppose. 😅

Solution

To make this package a little more accessible, I'd like to propose adding a small section to the README.md which makes it clear that this package produces HTML that is ready for styling but requires user-provided CSS to do so. This would use language similar to that in the rehype-katex README's CSS section. I'd happily make a pull request to make this happen.

Alternatives

If adding this info directly to the README.md is undesirable and the maintainers feel it exceeds the scope of the document or makes it longer than necessary, a troubleshooting document could be made with common pitfalls, like the one I fell in, and their solutions.

[wooorm]

This package doesn’t handle HTML. Did you see https://github.com/remarkjs/remark-rehype#css

[IncPlusPlus]

Right. This package is merely responsible for adding GFM support to remark-rehype, which is what actually transforms the syntax tree into HTML. However, features this package adds, like support for GitHub's tables syntax, will show up without so much as borders when rendered without the right CSS to complement it. I figured it couldn't hurt to mention it in the REAMDE.

[wooorm]

Somewhat, yes! More correct terminology would be:

• remark-gfm adds support for GFM to markdown (in the remark/unified ecosystem)
• remark-rehype turns a markdown syntax tree into an HTML syntax tree

---

This would use language similar to that in the rehype-katex README's CSS section.
(from your OG post)

The thing is, that package requires CSS for visual users. It’s an HTML project whose result would otherwise be unreadable garbage. It’s a package that’s meant for browsers.

This plugin has nothing to do with CSS. Markdown has nothing to do with CSS. It doesn’t need browsers. Even when used with remark-rehype, without CSS, the final result is still usable.

This plugin doesn’t have “results” to style. No HTML. No browsers. So I’m not sure how to word this section you propose while being true, useful, but without sounding passive aggressive:

## CSS

Markdown has nothing to do with CSS.

Or:

## HTML & CSS

This package deals with markdown syntax.
It has nothing to do with how markdown is turned into HTML or how that shows up
in browsers.

What wording were you thinking of?

[wooorm]

done!