Modifying the GitHub repo containing my Distill website

tutorial giscus github deploy

Adventures with giscus (easier) and GitHub Actions (harder)

Shannon Pileggi true
2021-12-13

Note: This post was originally written by Shannon Pileggi and copied here on December 21, 2021 - see the original post here for a potentially updated version.

R logo has a worried face; little puffball monster is sitting, looking grumpy, with hat in hand and caption that says "i just need a minute."

Figure 1: Artwork by @allison_horst. Except in my case, I just needed 12 days of intermittent attempts.

TL; DR

I made two modifications to my distill website and the corresponding GitHub repository:

  1. Added giscus commenting to my blog - this was fairly straightforward and completed within 1 to 2 hours.

  2. Added GitHub actions to automatically update the repository’s README with blog stats - this took several attempts over the course of a few days.

Giscus commenting

Straightforward and completed within 1 to 2 hours.

Updating the commenting mechanism on my website from discus was something I had been meaning to do for a while, but held off on because you never know when a seemingly small change will take you down a rabbit hole.

I went for it, and thanks to Joel’s awesome post Enable giscus in Distill it was a pretty quick and easy process. 🙌

tonight i intended to update my #rstats blog from disqus to utterances, but then i found this great post by @joel_nitta about ✨giscus✨! thanks, Joel! 👏

i hope the new giscus gets used - go ahead, pipe up!😉https://t.co/Wx1j80TKVD

— Shannon Pileggi (@PipingHotData) December 1, 2021

GitHub Actions README

Several attempts over the course of a few days.

After the amazingly quick success of the giscus implementation, I was ready to tackle more! I thought a mini-project on my blog would be a nice entry point to learn GitHub Actions, and I decided to replicate Matt Dray’s post Up-to-date blog stats in your README. Between intricacies with both the README and the GitHub Action workflow yaml, this happened:

how is figuring out #rstats github actions going, you ask? preeetttty well 👍 pic.twitter.com/Boj7KvXCAi

— Shannon Pileggi (@PipingHotData) December 3, 2021

I mean, sometimes you can skip reading documentation fully, make a few tweaks to your code, cross your fingers, and hope that everything works. GitHub Actions is probably not one of those things. 😬 Below are a few of the errors I suffered through to get this working; hopefully I can save you some of the pain!

GitHub Actions

README

After much perseverance and persistence, I prevailed with my first GitHub Action. 💪

The "some stats" section is automatically updated, including a rugline type graphic with a single vertical line on the date of a each post.

Figure 2: Updated README file for the pipinghotdata_distill GitHub repository, with the stats section automatically updated daily with GitHub Actions.

Perhaps reading the documentation more closely or slowing down to think through things might have worked better for this situation. If you want to have a laugh or or want to feel better about your own struggling efforts, browse through my 34 commits or check out the corresponding GitHub Action history Dec 1 - 12, 2021. Despite the frustration, I remain grateful for these experiences as I learned a lot.

Afterwards

So what happened after these changes?

Giscus

One unexpected side effect of using giscus is all of the automatic notifications I receive about the discussion. I get notifications for:

  1. on my blog: all comments

  2. on blogs by others:

    • replies to my comments

    • all comments subsequent to mine, by anyone, as we are now all engaged in the same GitHub discussion.

The last one was a bit surprising to me, but I like it for now!

GitHub Actions

Now that I am using GitHub Actions on the README of my repository, I am no longer the only contributor to my repository! 😯 This means that when I open up my R project, I now need to remember to pull before I start working on my website.

In addition, despite my GitHub Actions working, I ran out of free time as shown in the workflow #39 error. 🤦 I guess I either need to figure out {pak} out with GitHub Actions to hopefully speed things up, or experiment less to get my actions right.😆

Acknowledgements

Thanks to:

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/jhelvy/distillery, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

Pileggi (2021, Dec. 13). The Distillery: Modifying the GitHub repo containing my Distill website. Retrieved from https://distillery.rbind.io/posts/2021-12-13-modifying-the-github-repo-containing-my-distill-website/

BibTeX citation

@misc{pileggi2021modifying,
  author = {Pileggi, Shannon},
  title = {The Distillery: Modifying the GitHub repo containing my Distill website},
  url = {https://distillery.rbind.io/posts/2021-12-13-modifying-the-github-repo-containing-my-distill-website/},
  year = {2021}
}