Sharing Information With Jupyter Notebooks: A Data Scientist's Struggle

fastpages.md

1. Sally creates this notebook which contain interactive visualizations. She saves the notebook to GitHub.

2. Sally wants to share this report with her colleagues on twitter, preferrably as a blog post. However, she cannot share her notebook via a GitHub link due of the following issues:

   • GitHub doesn't support rendering her interactive visualizations, even when all the code is client side, like the case with Vega-Lite or Altair. (That is why you don't see any visualizations in this notebook on GitHub!)
   • There is no place for colleague to comment on the notebook or provide feedback easily.
   • Sally wants to hide / show code to make the document easier to read, and remove extreanous information. It is impossible to do this without copying her notebook and creating an alternate version.
   • Sally needs the ability to hide/show code in collapsable cells in certain cases where she wants it initially hidden from view but readily acessible.
   • When Sally provides link to her notebook on Social media, she wants preview card to render a title and an image she chooses, to maximize exposure and communicate effectively.
   • She needs to embed youtube videos with part of her previous lectures on the subject.

3. In order to do this, Sally decides to convert her notebook herself to an HTML page and host that on GitHub Pages. In order to make this work, she has to go through the follow steps:

Initial Setup

• Install jupyter plugins that allow her to selectively hide cells.
• Learn how ot use a static site generator, like Jekyll
• Install and configure a static site generator in a way that is compatible with notebooks.
• Install at least 5 third party plugins that can help with setting seo optimization like twitter cards and preview images.
• Install a converter tool, nbconvert that allows her to export her notebook into another format like html.
• Install nbdev, a tool that gives Sally shortcuts for creating metadata in her notebook with markdown.
• Learn how to use Jinja templating so that she can apply necessary customization the export of her notebooks to HTML.
• Learn how to use Liquid templating that will allow her to "glue" aspects of the notebook to the static site.
• Write templating code that will export the notebook in HTML with associated markup that is compliant for the static site generator.
• Write code that can accomplish the following, using HTML, css and templating languages:
  • Collapsalbe code cells
  • Embedded youtube videos
  • Automated table of content creation
  • Many other aspects that are required in setting up a blog
• Signup with a third party service to enable comments on her blog posts.

Everytime She Wants To Publish A Blog Post

• Start a notebook server to author the content
• Manually runs a conversion script to convert ipynb files to HTML.
• Manually copy image files into a different folder in her repo
• Manually correct links to image files in her repo

Enter Fastpages

• A Platform powered by Actions & GitHub Pages with a 2-step setup process.
• Create posts containing code, outputs of code (which can be interactive), formatted text, etc directly from Jupyter Notebooks; Notebook posts support features such as:
  • Interactive visualizations made with Altair remain interactive.
  • Hide or show cell input and output.
  • Collapsable code cells that are either open or closed by default.
  • Define the Title, Summary and other metadata via a special markdown cells
  • Ability to add links to Colab and GitHub automatically.
• Create posts, including formatting and images, directly from Microsoft Word documents.
• Create and edit Markdown posts entirely online using GitHub's built-in markdown editor.
• Embed Twitter cards and YouTube videos.
• Categorization of blog posts by user-supplied tags for discoverability.