fastpages: Pitfalls, Tips & Tricks
What you need to know to be productive and have a good user experience.
🆕 📝 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 theimage:
attribute withimages/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.