README

My personal blog

Operational Notes

• Ruby 101

• Check for errors: jekyll doctor
• Build for deployment: jekyll build
• To preview blog with draft posts (posts stored in _drafts folder): jekyll serve --drafts

Code Notes

• /feed.xml is generated by the jekyll-feed plugin while /r.xml is a feed exclusively for the r tag that is generated by the r.xml script. Both feed.xml and r.xml are generated when jekyll build is run.
• When jekyll build is run, scripts such as r.xml are run and the resulting data and content is put into the _site folder which generates the site.
• Configure _config.yml as necessary to configure site-wide variables and settings. Use exclude: to exclude files (such as README.md) from the jekyll build process. Use header_pages: to add additional pages to the site.
• _sass contains the CSS styling

Atom XML Feed

For R-Bloggers I needed to create a custom feed that only contained R content. My solution was to make all R posts contain the tag "r" and then use jekyll to build an r.xml file. The file in root, r.xml is what builds the feed. I first tried to use https://github.com/jekyll/jekyll-feed to build a feed for a specific tag or category, but was unable to get it to work.

• Atom XML Feed Verifier: https://validator.w3.org/feed/
• Can use a RSS aggregator like feedly for checking the content.

Other Modifications

• Post tag pages added per these instructions
• Leaflet Javascript library added based on this. See _includes/leaflet.html

Other Notes

• Installing jekyll: gem install jekyll bundler

• Installing the bundle: bundle install

• Updating the bundle: bundle update

• Ran into an issue with two versions of jekyll. Had to apt remove jekyll per jekyll/jekyll#7088 (ie. only install the gem)

• Had to copy 'assets' and '_sass' folders from minima github (release file) into this repo to fix file not found errors

Blogging with Jupyter Notebooks

Steps for using jupyter notebooks to create a blog post:

• Add the desired YAML header to the beginning of the jupyter notebook in a raw cell. Include the beginning and trailing ---. For example:

---
layout: post
title: "Test Jupyter Post"
date: 2021-10-17
author: Jesse Cambon
tags: [python, data]
image: "/images/tidygeocoder_hex_dark2021.png"
---

Now run the build_jupyter.py script on your notebook:

python build_jupyter.py path/to/notebook.ipynb

This script will create a .md file in the same directory as jupyter notebook. The script handles moving all the image files to the jupyter_files directory and fixing the image references within the newly created markdown file.

IMPORTANT:

• If you include images within your juypter notebook, make sure the alternative text is not "png" (ie. do not do this: ![png](/path/to/image.jpg)) The build_jupyter.py script will edit image paths with the alt text png to point to the jupyter files directory (if there are graphs within the notebook that generate images).

References:

• https://www.linode.com/docs/guides/jupyter-notebook-on-jekyll/
• https://jaketae.github.io/blog/jupyter-automation/
• https://cduvallet.github.io/posts/2018/03/ipython-notebooks-jekyll

Resources

• Quick reference: https://jekyllrb.com/docs/usage/
• Minima Theme: https://github.com/jekyll/minima
• Jekyll-Feed plugin (for RSS) https://github.com/jekyll/jekyll-feed