Knitting to a different branch for GitHub Pages

R Markdown
#1

Hello, folks! I am asking here in hopes of having better luck than on Twitter :slight_smile:

Does anyone know any tricks/workflows/utilities for knitting/rendering an R Markdown document into a different branch (e.g. "docs" or "gh-pages", which is then configured to be the source for GitHub Pages) so that the rendered HTML file is not in the main branch where the source Rmd is.

Like pkgdown::deploy_to_branch(), but for a single document (in my case a {distill} article) instead of a website/blog.

#2

You would need to do that in your CI workflow

  • Have a workflow that renders the document in the Github Action Workspace
  • Commit this new rendered HTML document into the gh pages branch

I think it would be something like that. I don't have a live example at end - We should definitely make one

Steps would be (following one the example action actions/examples at master · r-lib/actions · GitHub

  • install R
  • install Pandoc
  • install packages dependencies (or track them using renv and restore the project
  • use rmarkdown::render() to render the Rmd doc inside GHA workflow
  • Commit the result from GHA to the gh-page branch and not the main one.

For the last step you could find some existing actions usuful like Deploy to GitHub Pages · Actions · GitHub Marketplace · GitHub that works well to deploy to GH page a directory you would have created during the previous step of the workflow. There is also GitHub - peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly. but I only use the former one.

You could also use only git command on your workflow to change branch but this is more advanced I believe.

Hope it helps.

(And I note the need of more example and helper function for publication - thanks for the feedback!)

1 Like
#3

Thank you so much for that detailed and informative response, @cderv! And I really appreciate all the links you provided!

#4

Here's a working example of rendering a distill website and deploying to GitHub Pages (don't worry about the non-existent content :grimacing:, let's just focus on the GHA workflow).

2 Likes
#5

Thank you so much, @jennybryan! Having that as an example is super helpful!

Quick question because I don't have experience with GHA. Did you have to create a gh-pages branch manually or did JamesIves/github-pages-deploy-action@4.1.0 create it automatically?

#6

Yes The action will create the branch for you.

The doc of the action I linked above is helpful to understand how it works and how to configure. Don’t hesitate to look at it !

If the remote branch that you wish to deploy to doesn't already exist the action will create it for you.

From

1 Like
#7

Yeah as @cderv says, the action should create the branch for you.

I also have no particular reason to pin to that version (4.1.0) so if I were fiddling with something today, I'd go straight to the latest version of that action (4.1.3).

2 Likes
#8

Thank you both so much!

1 Like
#9

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.