Figure 1: Chafffinch at bird tables
Publishing xaringan slides
This is my first attempt to publish my NHS-R Community 2020 Virtual Conference Lightning talk slides using the code shared by Dr. Silvia Canelón who ran the workshop Sharing Your Work with xaringan. I’m indebted to Silvia’s workshop and also to the code she used to publish the workshop slides.
Unfortunately, it looks like they render better on the index.Rmd file and not on an article. The slides look the same (with lost formats and no interactivity) whether the link is to the self-contained html in a repository on my computer or to the url.
This RStudio Community conversation helped me realise this is probably something in distill and not something I was doing. In particular, it’s where @Apreshill says:
But also, this is the index.Rmd, not a post, so not entirely sure. I also added this line to my _site.yml, but confess to not testing whether that is required or not for this to work:
I tried adding the line include: [“slides/”] @Apreshill refers to but that didn’t solve the formatting.
Things to note when publishing using GitHub
To get started there are lots of blogs on publishing to GitHub pages but this from R Studio/distill creators is also very clear.
The following are notes I’ve made and learned around publishing html and xaringan slides to GitHub.
Publishing subfolders
Although I managed to publish a GitHub repository following the instructions, I remained frustratingly confused about how to publish the html slides in subfolders. It turned out it was a simple thing that no one mentioned; you just need to add the subfolder directory to the url!
For example, @tomjemmett had published the NHS-R Community repository https://github.com/nhs-r-community/Conference_2020 and the url becomes: https://nhs-r-community.github.io/Conference_2020/
To see my xaringan slides I needed to get the page to the subfolder /Lightning_talks/ZoëTurner_SQLvR/ and this only needs to be added to the url like so: https://nhs-r-community.github.io/Conference_2020/Lightning_talks/Zo%C3%ABTurner_SQLvR/index.html#1
The #1 at the end of the url refers to the slide number so you can go straight to a particular slide if you want.
It took me days of looking at websites on how to publish GitHub pages to realise this small thing and the danger of continued searching was that some pages referred to the old way of publishing GitHub pages which necessitated creating a new branch called gh-pages.
Thankfully, after days of puzzling over this I decided to take a copy (fork) of Silvia’s repository and run her code, which worked perfectly, so I knew I was on the right lines. Comparing the urls to the slides and where she she had saved them in her repository, I noticed the file paths were the same and then it all clicked for me. The point to all this is that it’s a generous thing to open up your code to such naive scrutiny and I am forever grateful to those that do.
Things to note
I have a special character in my name: Zoë. The ë appears like that in the url but when copied and pasted here, for example, it comes out as Zo%C3%AB. Thankfully, both work, which is good to know if you have an unusual character in your name!
Be patient
I quite often got a 404 error page just after saving a file to publish which was odd as everything worked ok. This was because it can take quite a few minutes for things to refresh.
Xaringan slides are blank
Also note that if the xaringan slides don’t appear but there is a blank box in the top left hand side of the screen and with a slider, it has worked. This can occur if you work on a VPN, as I do, where the security is very tight.
I also noticed the same box when I knitted xaringan slides and I was using a link to a video. The particular slide would only work when the slides were opened in the Chrome browser. Given that the NHS often default to Explorer or Edge browsers, it might also be worth checking you are using Chrome if you are not on a VPN and still get the blank slider box.
Xaringan slides are not self-contained
Unlike using html, the xaringan slides need to have the images, CSS and libraries available to run it. I made the mistake of using two folders for my images but it worked out that I used /img for the slide backgrounds and the /images for the pictures related only to that presentation.
Update…
Silvia kindly shared the update about making the xaringan presentations ‘self-contained’. I’d used that line of code for this blog originally as I hadn’t read the instructions and had wondered if that was why the slide navigation was missing (see the answer to that below!). Testing how ‘self-contained’ self-contained is I emailed myself just the html and got the text but no formats. Zipping together the html along with the css, img and libs (my names for these) folders did mean the html opened up ok with all the formatting. It’s a little like when saving a webpage and a same-named folder appears that is needed for the html to open.
Reasons not to use pdfs
Using pdfs gets around the need to email out supporting files and folders as it’s just one file to send, however, I’m reluctant to use pdfs because of accessibility as much as aesthetics:
https://www.gov.uk/guidance/publishing-accessible-documents
Think about format
Doing this will help your document support as many users as possible and can future-proof your information.
Publish in HTML format wherever possible so that your documents use your users’ custom browser settings. It can be difficult to make other formats easier to read.
For example, PDF documents:
can make your content harder to find, use and maintain do not work well with assistive technologies like screen readers a lot of the time. If your documents do not meet accessibility standards you could be breaking the Equality Act 2010.
Aesthetically, you lose interactivity (dygraphs or plotly charts) or movement in your slides (videos or GIFs) with pdfs so if you look through the commits in my Presentation repository you will see me flicking between html to pdf and back to html as I’ve tried this out.
Missing slide navigation
I was puzzled for a long time why I had published my slides in this blog but the slide navigation was missing. As I consistently fail to read instructions it turned out I needed the line:
xaringanExtra::use_share_again()
in the presentation slide code. I put this in the code chunk related to libraries (often listed as r libs).
Because I missed doing this from the beginning there were a few steps I needed to to to get this to publish on the blog. These were:
Presentation repo
- Add the line of code to the presentation code
- Knit the presentation
- Commit and push the presentation rmd and html file
Blog repo
- Knit the blog post
- Build the website
- Commit and push all changes
- Do a little celebration jig and thank Silvia yet again for helping me out as she let me know this missing line of code in the NHS-R Community Slack Group