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:

    :::coffeescript
    $('.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

    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:

    https://bitbucket.org/afrankvt/draft

    • http://davidchambersdesign.com/ David Chambers

      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

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

  • http://twitter.com/dhmspector David HM Spector

    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.  

    • http://davidchambersdesign.com/ David Chambers

      This is a popular feature request (see https://bitbucket.org/site/master/issue/2288). We would love to provide this, and plan to devote the necessary time to it at some stage.

    • http://davidchambersdesign.com/ David Chambers

      Disqus included the “)” in the issue URL. You’ll need to strip that to view the issue.

  • http://jimeh.me/ Jim Myhrberg

    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”).

    • http://davidchambersdesign.com/ David Chambers

      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.

      [1]: http://freewisdom.org/projects/python-markdown/
      [2]: http://github.github.com/github-flavored-markdown/

  • USB Drive

    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
    post.

    USB
    Drive

  • http://blog.psyrendust.com Larry Gordon

    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

    Is there also a solution for restructuredText readmes?

  • gbmhunter

    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

    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?)