This blog post tells you how to show latex equation on GitHub (not GitHub Page, but .md file like README).

Sometimes we may need to write some equation in README file. This will be easy as the markdown file is rendered to HTML (like on GitHub Page). But when we are viewing a README file directly in a repo, those latex style formulas (like $\sigma$) won’t work (as is raised here and here). Luckily, this is achievable through some external services, to request a image of formula through URL. You may just want a solution, or know the reason behind it. Also a Sublime plug-in to do this on pressing a hotkey.


  1. Write equation in latex style, e.g. \frac{\sigma}{\mu}.
  2. In this site (or either tool for url encoding-decoding), encode your formula. This encode your formula in % followed by two hexadecimal digits, e.g. %5Cfrac%7B%5Csigma%7D%7B%5Cmu%7D for the example in step one.

picture of url encoder site

  1. Prefixing the encoded formula by, e.g. This url will return a picture of the formula you want. More information here.
  2. You can add it as a picture in markdown like ![img](


  • Why we need picture rather than direct latex?

GitHub markdown parsing is performed by the SunDown (ex libUpSkirt) library. For security, it won’t allow javascript to be executed when rendering markdown to HTML. Thus won’t provide equation feature.

  • Why encoding url?

First of all, GitHub uses an open-source project called Camo to provide a proxy for images hosted on GitHub. You will see that once your file is uploaded, the url of the image will change to something like But this mechanism only support encoded url and does not seem to support http redirect (which some service may fail to provide image, like iText2Img).

Sublime plug-in for this

There is no way for a programmer to do these foolish steps by hand! We always try to solve an easy problem by raising a much more difficult problem… If you know nothing about how to write a sublime plug-in, here is a good start. Yet to implement a practicable plug-in is really difficult.

Here I wrote an easy sublime plug-in. It can do those steps above for you automatically just after pressing a hot key.

import sublime, sublime_plugin, urllib

def selections(view, default_to_all=True):
    regions = [r for r in view.sel() if not r.empty()]
    if not regions and default_to_all:
        regions = [sublime.Region(0, view.size())]

    return regions

def quote(view, s):
    return "![equation](" + urllib.parse.quote(s, safe='') + ")"

class LatexPictureCommand(sublime_plugin.TextCommand):
    Main logic
    def run(self, edit):
        view = self.view
        for region in selections(view):
            s = view.substr(region)
            view.replace(edit, region, quote(view, s))

Feel free to add more function to that easy code!