Providing access from mobile phones to notebooks shared on GitHub

If you are sharing something on GitHub, chances are you doing so to collaborate with others or to be helpful. It's hard to achieve either if people cannot accesss what you publish.

In 2017, mobile Internet traffic had a share of 52.64% of global traffic. More importantly though, there are places around the world where the only reliable mean for accessing the Internet is mobile. It would be particularly unkind leaving people out based on geography.

Luckily for us, the solution(s) are very simple. I present two simple ways to fix this problem below:

Linking from README.md to nbviewer

  1. Create a README.md in the root of your repospitory
  2. Push to github
  3. List the notebooks you would like to make available as HTML pages in your readme
  4. Look up the URL to notebooks on github, for example: https://github.com/radekosmulski/python_shorts/blob/master/debugging_inside_jupyter_notebooks.ipynb

  5. Construct a URL that will open your notebook in nbviewer:

    <http://nbviewer.jupyter.org/github/><everything from url in #4 after https://github.com/>

    For example: http://nbviewer.jupyter.org/github/radekosmulski/python_shorts/blob/master/caching_expensive_calculations.ipynb

  6. Link to the URL from your README.md using markdown

Serving your HTML via GithubPages

  1. Create a README.md in the root of your repospitory
  2. Create docs directory in the root of your repository

  3. Convert notebooks to HTML using jupyter nbconvert:

    jupyter nbconvert --to html --output-dir docs *.ipynb

  4. Push to github
  5. On github, go to settings of your repository > GitHub Pages > Source and select master branch / docs folder and save
  6. Note the URL your site will be published at, for example: https://radekosmulski.github.io/python_shorts/

  7. In your readme, link to

    <site URL><name of HTML file>

    For example: https://radekosmulski.github.io/python_shorts/debugging_inside_jupyter_notebooks.html

In your text file, the following will create a link [link text](URL)