🆕 📝 This article is updated regularly with new information as it is discovered.

Introduction

fastpages will automatically convert Jupyter Notebooks saved into the _notebooks directory as blog posts!

You must save your notebook with the naming convention YYYY-MM-DD-*.ipynb. Otherwise the file's modification time is used, but that is not something you should rely on.

See Writing Blog Posts With Jupyter for more details on special markup features.

Things to Consider

  • Isolate the title, subtitle, and metadata into their own cell (the first one).
  • Always quote your title and sub-title. Also quote any categories that are not purely alpha-numerical-with-hyphens.
  • Add author information to your pages, so the Atom feed has it – Adding authors to your Jekyll site.
  • Categories are hierarchical and become part of the final URL – so give them a reasonable order (from generic to specific), have a consistent scheme for the site as a whole, and do not change them after publishing, otherwise you'll break people's links.
  • For dual-use images (referenced in notebook contents and metadata), place the image in the _notebooks folder (or a sub-folder), use the relative path there in your notebook, and prefix that path for the image: attribute with images/copied_from_nb/.
  • Categories must be listed in a bracketed list – you cannot make it multi-line.
  • Do not use today's date in filenames if you plan to publish soonish – timezone differences to the build machines will possibly make your article disappear from the generated index. (fixed in template)
  • This is a bit subjective, but I recommend to get yourself a local installation of JupyterHub and use that exclusively as your “fastpages IDE” – that means just ignore plain markdown files and do everything with notebooks.

How-Tos

Updating the fastpages Template

To get changes from upstream, check out your own copy of the template project.

To catch up for the first time, find the Initial commit in your blog repository, then make sure there are no commits after the time of that commit in the template. If there are, find the last commit before that date (the last one you already have), and use its SHA for a range «sha»..HEAD in the update procedure that follows, starting with the git diff.

Now to catch up, when you git pull --ff-only in the template, there is a line starting with Updating and a SHA range. Call git diff «sha-range» >/tmp/fastpages.patch.

Change to your blog repository workdir (make sure you have a clean workdir with no pending changes) and apply that patch: patch -N -p1 </tmp/fastpages.patch. Look out for patch rejects and resolve any conflicts. Finally commit the template changes, ideally mentioning the SHA range in the commit message for record-keeping (example).

Instead of using patch, you can also open a branch for upstream changes, git pull --ff-only upstream/master any updates into that branch, and then git merge that branch into master. This way, git does all the house-keeping and memorizing of SHAs.

Troubleshooting

Article is not in the Index

See above hint regarding dates in the (near) future, and timezone differences between localhost and the cloud.

Index Entry is Missing Most Fields

When an entry appears mostly empty, there is some metadata problem: missing quotes, improper YAML syntax, etc.

Backtrack your changes in the git history, and never change metadata in bulk, so you can isolate the problem. And wait for a successful build after each change.