What is Markdown? Markdown is a human readable syntax (also referred to as a markup language) for formatting text documents.Markdown can be used to produce nicely formatted documents including PDFs and web pages. When you format text using Markdown in a document, it is similar to using the format tools (e.g. Bold, heading 1, heading 2) in a word processing tool like Microsoft Word or Google. What is Markdown? Colab has two types of cells: text and code. Text cells are formatted using a simple markup language called Markdown. To see the Markdown source, double-click a text cell, showing both the Markdown source and the rendered version. Above the Markdown.

  1. Ipynb Markdown Table
  2. Jupyter Notebook Markdown Commands
  3. Ipython Notebook Markdown

Info to help convert the Jupyter notebooks we use in class into blog posts for your github blog. Manual conversion instructions are given for one-off posts, as well as detials to make a bash alias to automate the conversion process, move the files, and update your blog in one fell swoop.

Ipython notebook markdown bullets

Manual instructions

Run the following command in terminal to convert the file named notebook.ipynb from Jupyter notebook format to a markdown file suitable for your Jekyll blog. Note this must be run in the terminal inside the directory that includes the file you intend to convert.

That command will run the translation utility provided by Jupyter and create two new items:

  • notebook.md is a new file containing the markdown for your new blog post
  • notebook_files is a new folder containing all the images for your new blog post

Move the notebook.md file to your blog’s _posts folder and rename it to include the date and title for your post. You will also want to make sure the first few lines contain the appropriate front matter (YAML block in Jekyll parlance). You will also need to change any image links to point to your blog’s image folder. Read below to see my tool for automating most of these tasks.

Move the notebook_files folder to your blog’s “images” folder (this is also automated in my tool below).

Add these files to the git repository and commit. Then push the repo up to the server. Congratulations, your updated site should be live within a few minutes!

Automated instructions

Once you have installed the tool below, the instructions for uploading a notebook as a new post on your blog are:
  • Run new_post notebook.ipynb (where notebook.ipynb is the name of the file you wish to convert and post)
  • Start impatiently refreshing your blog page to see the new post appear.
Please note that certain items in the notebook file may not come through to the final blog post:
  • LaTeX equations will not be interpreted properly
  • Manually inserted images will need to be fixed by hand
  • YAML metadata (e.g. title, date, category, etc.) will only work properly if the first cell type is set to Raw NBConvert
Things my new_post function does:
  • Convert to markdown
  • Fix inline plot image addresses
  • Move post file and images folder to appropriate area of blog directory
  • Add and commit new post files to git repo
  • Push repo changes to server

Ipynb Markdown Table

There are currently no sanity checks in place in this function, so please take care to understand how it works before you run it, and be careful what you use it on. I have made an example post

Ipynb

Automation setup

This process is very similar to the tool I created in the first week of the class. Basically we are adding a shortcut to our .bash_profile script that the CLI loads everytime we open a new terminal window. I call my shortcut new_post but you can change this to whatever command you want to type when you post a notebook to your blog. The installation is easy, just copy and paste the code below into your ~/.bash_profile file (you can use the command subl ~/.bash_profile to open this file in Sublime Text directly from the CLI). Do note that you will need to change the info on the first few lines to reflect how your personal computer is setup.

Setup pretty tables

Latex in google colab

Jupyter Notebook Markdown Commands

When you set up your system for translating the blog posts, you will need to add some CSS code to your html template file to tell Jekyll to format the Pandas DataFrame tables appropraitely. Below is the relevant section of my <username>.github.io/_layouts/default.html file that has the CSS code included at the end of the <head> section. You should edit the your defualts file to be similar.

Markdown

Here is a quick overview of the features in the added CSS code. You can change any of these settings to suit your fancy.

Ipython Notebook Markdown

  • Set the table size to be the full width and 240px tall
  • Enable scroll bars for accessing larger tables
  • Set the font to Arial size 13, and align it to the center of each cell
  • Make the table headers (both column and row) bold
  • Give each cell 4px of padding
  • Highlight the row your mouse hovers over in light blue (#b8d1f3)