Skip to content
This repository has been archived by the owner on Nov 13, 2022. It is now read-only.

Latest commit

 

History

History
81 lines (59 loc) · 6.86 KB

README.md

File metadata and controls

81 lines (59 loc) · 6.86 KB
Raw

Auto-convert Jupyter Notebooks To Posts

fastpages will automatically convert Jupyter Notebooks saved into this directory as blog posts!. In addition to automatic conversion, there are some additional benefits that fastpages provides:

  • Preserves the interactivity of charts and graphs from visualization libraries like Altair.
  • Allows you to use features of nbdev to customize blog posts, such as:
    • Hiding cells by placing the comment #hide at the top of any cell. (To hide only the input to a cell use the hide input jupyter extension).
    • Add jekyll warnings, important or note banners with appropriate block quotes by using special markdown syntax defined here.
    • Displaying formatted documentation for classes, functions, and enums by calling show_doc.
    • Define the Title, Summary and other metadata for your blog post via a special markdown cell at the beginning of your notebook. See the Usage section below for more details.
    • There may be more applicable provided by nbdev, which is under active development. Check the nbdev docs, particularly the export2html section, for a complete list of features that may be useful.
  • Notebooks are exported to HTML in a lightweight manner to allow you to customize CSS and styling. CSS can optionally be modified in /assets/main.scss.

Setup

TODO

Usage

  1. Create a Jupyter Notebook with the contents of your blog post.

  2. Create a markdown cell at the beginning of your notebook with the following contents:

    # Title
> Awesome summary
- toc: False
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2
    • Replace Title, with your desired title, and Awesome summary with your desired summary.
    • fast_template will automatically generate a table of contents for you based on markdown headers! You can toggle this feature on or off by setting toc: to either True or False.
    • Additional metadata is optional and allows you to set custom front matter.

  3. Save your notebook with the naming convention YYYY-MM-DD-*.ipynb into the /_notebooks folder of this repo. For example 2020-01-28-My-First-Post.ipynb. This naming convention is required by Jekyll to render your blog post.

    • Be careful to name your file correctly! It is easy to forget the last dash in YYYY-MM-DD-. Furthermore, the character immediately following the dash should only be an alphabetical letter. Examples of valid filenames are:

      2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynb

    • If you fail to name your file correctly, fast_template will automatically attempt to fix the problem by prepending the last modified date of your notebook to your generated blog post in /_posts, however, it is recommended that you name your files properly yourself for more transparency.

  4. Commit and push your notebook to GitHub. Furthermore, the automatic conversion only occurs when a push is made to the master branch.

    • See How Does it Work? for more details and with instructions on customizing this behavior.

How Does it Work?

The Jupyter to blog conversion process is powered by nbdev, which has utilities to convert notebooks to webpages, including integrations with GitHub Pages.

A GitHub Action calls nbdev when changes to files are detected in the /_notebooks directory of your repo and converts Jupyter notebook files into blog posts. These blog posts are placed into the /_posts directory (via a commit and push) which is used by GitHub Pages to render your blog posts. This GitHub Action an be customized by modifying the /.github/workflows/nb2post.yaml in your repo.

Some important notes about nb2post.yaml:

...
  push:
    branches:
      - master 
    paths:
      - '_notebooks/*.ipynb'

This defines what will trigger the workflow, in this case, anytime files in the /_notebooks directory with a file name matching *.ipynb are pushed to the master branch.

...
    if: contains(join(github.event.commits.*.message), '/sync')

TODO: Instructions on option BOOL_SAVE_MARKDOWN

Additional Resources

  • 4 Part Series On Blogging With GitHub Pages: provides more context of the benefits and motivations behind fast_template, as well as different modalities for blogging: markdown, Jupyter Notebooks, Word docs, etc.
  • Blogging with Jupyter Notebooks: part of the aforementioned 4-part series, which includes instructions on how to blog with Jupyter Notebooks without using automation or GitHub Actions.
  • Altair Tutorial: an excellent tutorial by Jeffrey Heer of the Altair visualization library, which includes the ability to create interactive data visualizations in Jupyter. Interactive visualizations created with Altair will remain interactive when converted to a blog post via the mechanisms described in this README!
  • The official Jekyll Tutorial: A gentle introduction to Jekyll, which will provide you with tools on how to customize your blog.
  • Repository of Useful Jekyll Snippets, by mdo: a useful cookbook for accomplishing common tasks when creating a blog with Jekyll.
  • Primer Components: fast_template comes preloaded with this CSS library, which allows you to easily insert components such as buttons, timelines and more with HTML into your blog posts. This is optional and for advanced users who want to add custom elements to their site. Note: alerts are are provided natively in fast_template through markdown shortcuts that are documented here.