Nbconvert configuration for converting a Jupyter notebook into an HTML output with images saved separately, intended to be embedded into a Jekyll site.

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.

If you’re a data scientist, nbconvert is a great tool to add to your tool belt. With nbconvert you can easily turn your Jupyter Notebook into a Python script from the command line. It also allows you to turn your Jupyter notebook into share-friendly formats like.html and.pdf files. How cool is that? A raw cell is defined as content that should be included unmodified in nbconvert output. For example, this cell could include raw LaTeX for nbconvert to pdf via latex, or restructured text for use in Sphinx documentation. The notebook authoring environment does not render raw cells. The only logic in a raw cell is the format metadata field. Any text or code that you write goes in the cell. Cells are the building block of any Jupyter notebook. Cells operate in two modes: command and edit mode, and they are of mainly three types: code, markdown, and Raw NBConvert. The command mode allows you to manipulate cells. That is, the action you perform has to do with the cell as a whole.

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

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

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

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.

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

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

Learning Objectives

After completing this page, you will be able to:

• Create new Code and Markdown cells within Jupyter Notebook.
• Run Code and Markdown cells within Jupyter Notebook to execute Python code and render Markdown text.
• List useful shortcuts for common tasks in Jupyter Notebook.

Work With Python Code and Markdown Cells in Jupyter Notebook

Recall that a Jupyter Notebook file consists of a set of cells that can store text or code.

• Text Cells: Text cells allow you to write and render Markdown syntax. This is where you can describe and document your workflow.
• Code Cells: Code cells allow you to write and run programming code (e.g. Python).

Create New Cells

You can use either the Menu tools or Keyboard Shortcuts to create new cells.

While the default cell type for new cells is Code, you can change the cell type of any existing cell by clicking in the cell and selecting a new cell type (e.g. Markdown) in the cell type menu in the toolbar.

Cell type options include Code, Markdown, Raw NBConvert (for text to remain unmodified by nbconvert), and Heading.

To use the Keyboard Shortcuts, hit the esc key. After that, you can change a cell to Markdown by hitting the m key, or you can change a cell to Code by hitting the y key.

Run Cells

Python Code Cells

You can run any cell in Jupyter Notebook (regardless of whether it contains Code or Markdown) using the Menu tools or Keyboard Shortcuts.

For example, you can add a new Code cell and then run the following Python code (e.g. 3 + 4). Your result, or output, will be displayed below the Code cell that you run.

Markdown Cells

You can run Markdown cells in the same way that you can run code cells. However, when you run a Markdown cell, the text formatted using Markdown syntax will be rendered as stylized text.

This means that headings are larger and bold, bulleted lists have bullets next to them instead of *, and regular text looks normal. No outputs will appear below the Markdown cell.

For example, the Markdown syntax below represents 3 headers. You can double-click in any Markdown cell to see the raw Markdown syntax, which for the cell below would appear like this raw Markdown syntax:

To see the Markdown as stylized text, run the cell. It should look like the text printed below:

This is a subtitle in Markdown

This is a smaller subtitle

This is an even smaller subtitle

Rearrange Cells in a Jupyter Notebook

You can change the order of cells within Jupyter Notebook using the up arrow and down arrow buttons on the menu bar. To do this, click inside the cell that you want to move and then press the desired arrow as many times as you need to move the Cell to the desired location.

Clear Results in Jupyter Notebook

Sometimes, you may want to clear any output results that have been produced. You can do this using the Menu:

This will clear the current cell that you are working in, which you can activate by clicking in a cell.

You can also clear all of the output using the Menu Tools.

Raw Nbconvert Jupiter Fl