How to add color to GitHub's README.md file

Question

I have a README.md file for my project underscore-cli, and I want to document the --color flag.

Currently, the only way to do this is with a screenshot (which can be stored in the project repository):

But screenshots aren't text, preventing readers from copy/pasting the command in the screenshot. They're also a pain to create / edit / maintain, and are slower for browsers to load. The modern web uses text styles, not a bunch of rendered images of text.

While some Markdown parsers support inline HTML styling, GitHub doesn't; this doesn't work:

<span style="color: green"> Some green text </span>

This doesn't work:

<font color="green"> Some green text </font>

Solution 1

One way to add color to a README is by utilising a service that provides placeholder images.

For example this Markdown can be used:

- ![#f03c15](https://via.placeholder.com/15/f03c15/f03c15.png) `#f03c15`
- ![#c5f015](https://via.placeholder.com/15/c5f015/c5f015.png) `#c5f015`
- ![#1589F0](https://via.placeholder.com/15/1589F0/1589F0.png) `#1589F0`

To create a list of any colors you like:

• #f03c15
• #c5f015
• #1589F0

Solution 2

You can use the diff language tag to generate some colored text:

```diff
- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@
```

However, it adds it as a new line starting with either - + ! # or starts and ends with @@

This issue was raised in GitHub markup #369, but they haven't made any change in the decision since then (2014).

Solution 3

You cannot color plain text in a GitHub README.md file. You can however add color to code samples with the tags below.

To do this just add tags such as these samples to your README.md file:

```json
   // code for coloring
```
```html
   // code for coloring
```
```js
   // code for coloring
```
```css
   // code for coloring
```
// etc.

No "pre" or "code" tags needed.

This is covered in the GitHub Markdown documentation (about half way down the page, there's an example using Ruby). GitHub uses Linguist to identify and highlight syntax - you can find a full list of supported languages (as well as their markdown keywords) over in the Linguist's YAML file.

Solution 4

Unfortunately, this is currently not possible.

The GitHub Markdown documentation has no mention of 'color', 'CSS', 'HTML', or 'style'.

While some Markdown processors (e.g. the one used in Ghost) allow for HTML, such as <span style="color:orange;">Word up</span>, GitHub's discards any HTML.

If it's imperative that you use color in your readme, your README.md file could simply refer users to a README.html file. The trade-off for this, of course, is accessibility.

Solution 5

As an alternative to rendering a raster image, you can embed an SVG file:

<a><img src="https://dump.cy.md/6c736bfd11ded8cdc5e2bda009a6694a/colortext.svg"/></a>

You can then add color text to the SVG file as usual:

<?xml version="1.0" encoding="utf-8"?>
<svg version="1.1"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="100" height="50"
>
  <text font-size="16" x="10" y="20">
    <tspan fill="red">Hello</tspan>,
    <tspan fill="green">world</tspan>!
  </text>
</svg>

Unfortunately, even though you can select and copy text when you open the .svg file, the text is not selectable when the SVG image is embedded.

Demo: https://gist.github.com/CyberShadow/95621a949b07db295000

View more solutions

Comments

[totallytotallyamazing]

@NielsAbildgaard Thank you! :) The answer is that that you can not color plain text in GitHub .md files at least at this time. I did state that and spent about 4 hours researching it. Anyway Thank you for pointing out my helpful .md code tags, I appreciate it!

[dotMorten]

I couldn't get it working either, but it's weird because the color attribute is whitelisted: github.com/github/markup/tree/master#html-sanitization

[totallytotallyamazing]

@dotMorten not sure but I think you meant to leave your last comment on Scott H 's post just above mine?

[MRodrigues]

I used ´´´´Deprecated´´´´. Worked fine, for adding tags deprecated to docs.

[CodeManX]

It does not discard HTML in general, hr, br, p, b, i and others do work!

[Scott H]

Yeah, unfortunately it doesn't work in Github, as my answer states.

[Sandy Gifford]

If you do forward to a README.html, you may want to keep a copy of it in the repository so you don't lose its commit history. If you're feeling particularly sly, you could even include it in your gh-pages.

[craigmichaelmartin]

You can use the ```diff```` language tag to generate green and red highlighted text.

[Jason Antman]

See the source code of jch/html-pipeline for the actual HTML tags and attributes that GitHub allows.

[Jason Antman]

See the source code of jch/html-pipeline for the actual HTML tags and attributes that GitHub allows.

[totallytotallyamazing]

@ShadSterling "// codes for coloring" is my comment. Simply replace my comment with your code (you want to have color).

[ShadSterling]

Similar to the OP I want to make a particular bit of text a particular color. You offered this code coloring mechanism as an answer for how to do that, but don't show how to make any particular thing appear in any particular color.

[totallytotallyamazing]

@ShadSterling unfortunately specific colors can not be selected. The answer I provided does not state specific color selection as a solution.

[ShadSterling]

... then how is this an answer to the question that was asked?

[totallytotallyamazing]

@ShadSterling I answered the question in my first sentence then suggested a helpful, alternative color solution, "You cannot color plain text in a GitHub README.md file.". I was very grateful to find this info at the time I did, sorry if it doesn't help you.

[ShadSterling]

Syntax coloring is useful, I just don't see how it's an alternative for making a particular bit of text a particular color. I read your answer as ~"you can't really, but you can fake it with this", and I couldn't figure out how exactly to make the faking it work.

[Ziad Akiki]

This works great in Cards within a GitHub project and those can be used to tag the cards and color them

[AlecRust]

@BinarWeb where are you putting this? Will work on GitHub for example which supports images in Markdown.

[Binar Web]

as the question enquired, i wanted to color the text, not to have an image in front of the text

[AlecRust]

What I've described works. You can also put coloured text in the image e.g. https://placehold.it/150/ffffff/ff0000?text=hello

[Tropicalrambler]

Very useful info, helpful when creating web apps in the backend.

[Dave Dopson]

I tried that, and it doesn't seem to work. Can you link to an example?

[bwindels]

Including backquotes, like `#hexhex`

[Jacob Ford]

It also colors text surrounded by @@ in purple (and bold). Codecov takes advantage of this in its GitHub integration bot's comments, for example: github.com/zeit/now/pull/2570#issuecomment-512585770

[moxi]

This should be the accepted answer. Is simple, it doesn't require an external website or HTML.

[Zack]

The question is how to color text, this does not solve it. Also, this color preview is no longer supported on .MD files.

[Dave Dopson]

That's a neat hack! It doesn't solve the syntax-highlighting need that originally caused me to post the question, but it can probably address a variety of other needs.

[Dave Dopson]

I think your answer will be more compelling if you include a clever hack that I saw on the github issue: using text like "-! Warning !-" to incorporate / hide the color-triggering initial character.

[Dave Dopson]

This answer could be even stronger if it outlined an end-to-end pattern: using README.html.md as the source-code, rendered via Ghost to README.html, which is what gets rendered on the Github page. Does README.html show up by default, or does the user have to click-through to access it?

[Dave Dopson]

Update: I tried this, but unfortunately the end-to-end story isn't possible because Github doesn't automatically render the README.html file; it shows up as plain text. This must be why you suggested linking to it. Now I understand your comment about "accessibility" a bit better.

[Dave Dopson]

This got downvoted (by someone else) because Github's markdown module doesn't support that colored span tag, but I like the script for auto-conversion. That would work with the Ghost markdown parser, or if Github ever fixes github.com/github/markup/issues/1440.

[milahu]

here is a demo on github. <span color="red">redtext</span> etc. does work on github. only problem i see: no way to set background color

[Unicornist]

Thanks @DaveDopson 🙌

[jberryman]

@Unicornist FYI, I'm not sure why but circles 2, 3, 4, 6, 7 don't render for me, nor the first 7 squares and a couple of the hearts

[J-D3V]

Your writing a standard HTML tag, that's not gonna work for GitHub...

[Bahman.A]

Is there a color tag for CSV?

[totallytotallyamazing]

@Bahman.A I don't think so. See this StackOverflow

[nmz787]

this is exactly the use case I had, I wanted to highlight the diff in an issue comment where I was providing a quick workaround

[Peter Mortensen]

What is a "placeholder image service" (apart from the obvious)? What purpose does it serve? Can you elaborate a little bit and/or add a (non-naked) link for context (outside that service) in your answer? (But without "Edit:", "Update:", or similar - the question/answer should appear as if it was written today.)

[Peter Mortensen]

What is "Enicode"? Do you have an (authoritative) reference? Can you add it to your answer (named link, not a naked URL)? (But without "Edit:", "Update:", or similar - the question/answer should appear as if it was written today.)

[Peter Mortensen]

An explanation would be in order. E.g., in what environment does the script run - e.g., 'xclip' seems to be highly system dependent? On what system (incl. version) was it tested? Linux/Ubuntu? Please respond by editing (changing) your answer, not here in comments (without "Edit:", "Update:", or similar - the answer should appear as if it was written today).

[Luke Hutchison]

@PeterMortensen Enicode was a typo -- it should have said Unicode, sorry. (Fixed -- I'm pretty sure you don't need an authoritative reference to emoji characters.) What I was saying is that on most platforms, emoji characters (encoded in, e.g., UTF-8) are displayed in color, even in the middle of plain black and white text. So you can add color to your text by using emoji characters.

[Alex Szücs]

🟥🟩🟦 ref: emojipedia.org/large-red-square

[saeedgnu]

Thanks. Here is an example: github.com/ilius/termcolor/blob/master/colors.md

[Mr. Zoidberg]

@AlexSzücs Your solution is much better. Why didn't you post it as an answer?

[Alex Szücs]

@Mr.Zoidberg Because already similar answer exists: stackoverflow.com/a/65174367/10018427

[Suncatcher]

doesn't work in Github issues

[Mr. Zoidberg]

@AlexSzücs Your solution was easier and simplier.

[Sridhar Sarnobat]

Damn, I was hoping Enicode was some kind of extension of Unicode to include more emojis.

[Sridhar Sarnobat]

This is the best solution for me (differentiating between hundreds of microservice repos) as much as I don't want to depend on external services over time.

[jeremie bergeron]

@saeedgnu After some time, the color link seems to disappear.

[jeremie bergeron]

This does not seems to work anymore