Syntax highlighting for Markdown READMEs

By on February 16, 2012

I love Markdown. I also love a well-written README… especially if it features ASCII art!

It’s no surprise, then, that all my READMEs on Bitbucket are written in Markdown (I favour the .text extension, but .md, .mkdn, and .markdown all work too). One thing I’ve wanted for a while is syntax highlighting of code blocks in READMEs. As of today, Bitbucket supports this feature, via Python-Markdown’s CodeHilite extension. Now, one can prefix a code block with :::javascript or :::python or whatever:

    $('.label').each ->
      label = $ this
      label.css backgroundColor: sexyhex label.text()

Which produces something like:

Highlighted CoffeeScript

Others won’t have had a chance to update their READMEs, so I’ll shamelessly plug a few projects which take advantage of this feature:

As developers, writing documentation is not necessarily one of our passions. But we all appreciate a good README when we come across one. Hopefully this small improvement will encourage some of us to give our neglected READMEs some love and attention.


  • Andy Frank
    Posted February 17, 2012 at 12:34 am | Permalink

    Awesome – this will be nice.  I know the ink is barely dry on the Fantom syntax highlighting 😉 – but tried this (using :::fantom) on my readme and didn’t take:

    • Posted February 17, 2012 at 12:45 am | Permalink

      That’s odd. I tried the “hello, world” example from the Fantom website and Pygments highlighted it correctly. When I used the code block from your README it was not highlighted. Perhaps there’s a bug in the Fantom lexer?

      • Andy Frank
        Posted February 17, 2012 at 1:01 am | Permalink

        Hmm that could definitely be true – I’ll dig in more.  Thanks!

  • Posted February 17, 2012 at 7:32 pm | Permalink

    Why does markdown get processed only for README files?  I write all my project and design notes in markdown, but if I am browsing the source files of one of my projects (i.e., NOT the README at the top of the project) in bitbucket it shows me the raw markdown, rather than the rendered file.  

  • Posted March 12, 2012 at 12:39 am | Permalink

    Any specific reason for why you’re using a “:::lang” header-style language definition rather than using fenced code blocks? The reason I’m asking is cause myself and many others already have a lot of markdown using GitHub’s fenced code-blocks style (““`lang”).

    • Posted June 13, 2012 at 8:34 pm | Permalink

      Here’s a late response: We use [Python-Markdown][1] to render Markdown files. Python-Markdown uses the “:::lang” style. It would be nice to support [GFM][2] rather than or as well as Python-Markdown; this *may* happen at some point in the future.


  • USB Drive
    Posted May 23, 2012 at 10:01 pm | Permalink

    This post is one of
    the best in all.I belief
    in this site. All the user in this site was posting
    their notice about the post so great.So i posted this comment to discus their


  • Posted June 12, 2012 at 2:58 pm | Permalink

    I noticed that no one answered Jim’s question about GitHub’s fenced code-block style and if or when it will be supported. I just signed up for a team account and we are porting over about 50 projects. Would hate to go back into all of those markdown files to have to update them to support your syntax highlighting style.

  • Guest
    Posted July 14, 2012 at 4:36 pm | Permalink

    Is there also a solution for restructuredText readmes?

  • gbmhunter
    Posted May 27, 2013 at 6:12 pm | Permalink

    I like the ability to syntax highlight! Only negative is that it doesn’t work with GitHub, and you get the additional language code showing up in the README as text.

  • Mike
    Posted June 7, 2013 at 3:30 pm | Permalink

    And restructuredText?? I wouldn’t mind using markdown, but because I keep my docs in Sphinx format it means I need to use restructuredText. Should be doable without much trouble.
    (Why can’t I login with my BB account?)

  • Tony Rawlins
    Posted September 22, 2015 at 7:48 pm | Permalink

    Does it support syntax highlighting of Java code?

  • Luiz Filipe
    Posted February 24, 2016 at 7:08 am | Permalink

    It is possible use this for C# code?