a1ip / fastpages

An easy to use blogging platform that supports Jupyter Notebooks.

Welcome To fastpages

An easy to use blogging platform, with support for Jupyter notebooks, Word docs, and Markdown.

fastpages uses GitHub Actions to simplify the process of of creating Jekyll blog posts on GitHub Pages from a variety of input formats.

fastpages contain special features for Jupyter Notebooks, such as:

• Interactive visualizations made with Altair remain interactive.
• Ability to hide cells (input, output or both).
• Ability to have collapsable code cells that are either open or closed by default.
• Embed Twitter cards and YouTube videos.
• Ability to add Colab and View on GitHub badges automatically.
• Include banners such as warnings, tooltips, etc.
• Define the Title, Summary and other metadata for your blog post via a special markdown cell.
• The notebook to blog conversion is powered 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 for notebooks.

See the this section below for more details on how to configure these features.

See the demo site

---

• Welcome To fastpages
  • Setup Instructions
  • Writing Blog Posts With Jupyter
    • Configure Title & Summary
    • Table of Contents
    • Colab & GitHub Badges
    • Enabling Comments
    • Hide Input/Output Cells
    • Collapsable Code Cells
    • Embedded Twitter and YouTube Content
    • Automatically Convert Notebooks To Blog Posts
  • Writing Blog Posts With Markdown
  • Writing Blog Posts With Microsoft Word
  • Using The GitHub Action & Your Own Custom Blog
    • Optional Inputs
• Contributing To Fastpages
• FAQ
• Acknowledgements

Setup Instructions

1. Click the button to create a copy of this repo in your account.

2. GitHub Actions will automatically open a PR on your new repository ~ 30 seconds after setting it up from the template. Follow the instructions in that PR to continue.

Writing Blog Posts With Jupyter

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

# Title
> Awesome summary
- toc: false
- branch: master
- badges: true
- comments: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2

Additional metadata is optional and allows you to set custom front matter.

Configure Title & Summary

• Replace Title, with your desired title, and Awesome summary with your desired summary.

Table of Contents

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

Colab & GitHub Badges

• The branch field is used to optionally render a link your notebook to Colab and GitHub in your blog post post. It'll default to master if you don't specify it in the notebook.
• If you do not want to show Colab / GitHub badges on your blog post (perhaps because your repo is private and the links would be broken) set badges to false. This defaults to true

Enabling Comments

Blog posting is powered by Utterances, an open-source and ad-free way of implementing comments. All comments are stored in issues on your blog's GitHub repo. You can turn this on setting comments to true. This defaults to false.

To enable comments with Utterances you will need to do the following:

• Make sure the repo is public, otherwise your readers will not be able to view the issues/comments.
• Make sure the utterances app is installed on the repo, otherwise users will not be able to post comments.
• If your repo is a fork, navigate to it's settings tab and confirm the issues feature is turned on.

Hide Input/Output Cells

Place the comment #hide at the beginning of a code cell and it wil hide both the input and the output of that cell. If you only want to hide just the input or the output, use the hide input Jupyter Extension

Collapsable Code Cells

You may want to have code code be hidden from view under a collapsed element that the user can expand, rather than completely hiding the code from the reader.

• To include code in a collapsable cell that is collapsed by default, place the comment #collapse at the top of the code cell.
• To include code in a collapsable cell that is open by default, place the comment #collapse_show or #collapse-show at the top of the code cell.

Embedded Twitter and YouTube Content

In a markdown cell in your notebook, use the following markdown shortcuts to embed Twitter cards and YouTube Videos.

> youtube: https://youtu.be/your-link
> twitter: https://twitter.com/some-link

Automatically Convert Notebooks To Blog Posts

1. Save your notebook with the naming convention YYYY-MM-DD-*. into the /_notebooks or /_word folder of this repo, respectively. 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, fastpages will automatically attempt to fix the problem by prepending the last modified date of your file to your generated blog post, however, it is recommended that you name your files properly yourself for more transparency.

2. Commit and push your file(s) to GitHub in your repository's master branch.

3. GitHub will automatically convert your files to blog posts. It will take ~5 minutes for the conversion process to take place. You can click on the Actions tab of your repo to view the logs of this process. There will be two workflows that are triggered with each push you make to your master branch: (1) "CI" and (2) "GH Pages Status". Both workflows must complete with a green checkmark for your latest commit before your site is updated.

4. If you wish, you can preview how your blog will look locally before commiting to GitHub. If you wish to do so, please see the development guide.

Writing Blog Posts With Markdown

If you are writing your blog post in markdown, save your .md file into the /_posts folder with the same naming convention (YYYY-MM-DD-*.md) specified for notebooks.

Writing Blog Posts With Microsoft Word

Save your Microsoft Word documents into the /_word folder with the same naming convention (YYYY-MM-DD-*.docx) specified for notebooks.

Using The GitHub Action & Your Own Custom Blog

The fastpages action allows you to convert notebooks from /_notebooks and word documents from /_word directories in your repo into Jekyll compliant blog post markdown files located in /_posts. Note: This directory structure is currently inflexible for this Action, as it is designed to be used with Jekyll.

If you already have sufficient familiarity with Jekyll and wish to use this automation in your own theme, you can use this GitHub Action by referencing fastai/fastpages@master as follows:

...

uses: fastai/fastpages@master

...

An illustrative example of what a complete workflow may look like:

jobs:
  build-site:
    runs-on: ubuntu-latest
    ...

    - name: convert notebooks and word docs to posts
      uses: fastai/fastpages@master

    ...

    - name: Jekyll build
      uses: docker://jekyll/jekyll
      with:
        args: jekyll build

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v2
      if: github.event_name == 'push'
      env:
        ACTIONS_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
        PUBLISH_BRANCH: gh-pages
        PUBLISH_DIR: ./_site

Note that this Action does not have any required inputs, and has no output variables.

Optional Inputs

• BOOL_SAVE_MARKDOWN: Either 'true' or 'false'. Whether or not to commit converted markdown files from notebooks and word documents into the _posts directory in your repo. This is useful for debugging. default: false
• SSH_DEPLOY_KEY: a ssh deploy key is required if BOOL_SAVE_MARKDOWN = 'true'

See the API spec for this action in action.yml

Detailed instructions on how to customize this blog are beyond the scope of this README. ( We invite someone from the community to contribute a blog post on how to do this in this repo! )

Contributing To Fastpages

Please see the development guide.

FAQ

• Q: Where are the markdown files in _posts/ that are generated from my Jupyter notebooks or word documents? A: The GitHub Actions workflow in this repo converts your notebook and word documents to markdown on the fly before building your site, but never commits these intermediate markdown files to this repo. This is in order to save you from the annoyance of your local environment being constantly out of sync with your repository. You can optionally see these intermediate markdown files by setting the BOOL_SAVE_MARKDOWN and SSH_DEPLOY_KEY inputs to the fastpages action in your .github/workflows/ci.yaml file as follows:

    ...

    - name: convert notebooks and word docs to posts
      uses: fastai/fastpages@master
      with:
        BOOL_SAVE_MARKDOWN: true
        SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}

    ...

• Q: Can I use fastpages for Jekyll docs sites or for things that are not Jekyll blog posts? A: At the moment, fastpages is a highly opinionated solution that works only for Jekyll blog posts. If you want to write documentation for your module or library with Jupyter notebooks, we suggest you use fastai/nbdev which is expressly built for this purpose.

Acknowledgements

• Nate Gadzhibalaev: We ported his excellent work on #14 from fast_template to this repo, which enabled many features.
• All the contributors to nbdev, which powers many of the features in this repo.