Update GitHub Pages section

[apreshill]

This PR updates the GitHub Pages section (and splits off the existing section on Travis). Cl topics like Travis/GH actions remain to be updated.

[cderv]

Few comments below. I believe the part on .nojekyll is not correct.

Also, on the whole chapter, your proposal is to separate Github Pages from Github Actions ?

I have the same thought as for Netlify: I am wondering if we should have

6. Publishing 
  |>> Github 
      |>> Github Pages
      |>> Github Actions

Now considering

• RStudio Connect
• Netlify
• GIthub Pages

maybe we need to replace the last part (now travis) to something like "Automate Publishing" and explain how to do it for the 3 service above.

How would that be ?

And as commented below, I would use gh-pages instead of docs/ folder to automate the build and publish with GH pages. Am I the only one ?

[cderv]

Is this the preferred way all the time compared to gh-pages ?
Or is this what you think is simpler to use with Bookdown ?

My view on this:

• /docs folder is simpler when not using a CI:

  • Build locally to docs/
  • Commit and push

• I find gh-pages cleaner to have in the source repo and easier to put in place when using a CI. Locally I use a Makefile to help me generally

  • On main branch, _book (or other output dir) is in .gitignore
  • I build the book locally
  • Then I switch branch to gh-pages
  • I commit the _book folder
  • I push the gh-pages branch
  • I switched back to main branch

Makefile do all that for me usually. Using a R file with gert should use the same. An R function could help with that.

Anyway, just sharing how I work with this.

[apreshill]

I would definitely suggest the gh-pages route for folks who are comfortable with Make, gert, and CI systems like GHA (like yourself). I can draft that section, but could use a draft GHA workflow (much easier than Make/gert) since there is no deploy_to_branch() :)

[cderv]

Ok so we agree on this.

I suggest we do the GHA part later - this would require to rework a bit a workflow, and I would like to show netlify and rstudio connect for all options. Best would be to have demo repo too with all this !
So it is a bit of work to it right IMO.

It is also possible to work on helper function to help deploy. We have already publish_book() for rstudio connect, we could have another one for GH Pages deployement (but it could also be directly in the Workflow template).

I can work ont that... but later in another PR.

How does that sounds ?

[cderv]

This is where the file needs to be inside the /docs folder.

So it should be file.create("docs/.nojekyll") in your example. And docs/ should not be cleaned, otherwise the file would need to be restored.

Other solution would be to create the file at build time, but this currently needs a hack because the file is not moved automatically to output dir. See #1190 (comment)

This is why we need to provide a better way.

I would advice your solution for now creating in the right directory. As it will be tracked by Git, a user would quickly see if this will is to be deleted during a cleaning.

Note on cleaning: You need to clean you book output dir sometimes when working on a book because bookdown won't do that for you. There could be some conflicts sometimes. For example: You work on a chapter, you build, you commit, you are not happy and change the structure of the book which will lead to new html file name because new chapters. The old chapter does not exist anymore, but the HTML files still are. You will commit the new ones but it will not necessarily overwrite the old ones if the names are different. You will have old HTML files in your published book. For this a cleaning is required before rebuilding the book.

[apreshill]

Got it, I was thinking that was not going to work but then re-read the existing section (https://bookdown.org/yihui/bookdown/github.html) and thought I was wrong.

[cderv]

I think in this case you also want to delete them locally, at least _book, isn't it ?

Your new book will be in docs/.

But I guess it is easier for a user to do that itself than knowing how to remove from git.

[apreshill]

I was told by several on the tidyverse team that you had to do both (which is what this says)- so you mean only do step 1?

[cderv]

No no what I am saying is that git rm -r --cache _book/ will not delete the _book folder.
It will still be there but untracked. If you don't need it anymore (because you are using docs/ now, it should be removed I think (bookdown::clean_book(TRUE))

For _bookdown_files, I don't remember what it is used for. Doing git rm -r --cache _bookdown_files/ will untrack eveything from Git, but the files will still be there on the system.

I wasn't sure here if we are supposed to keep those or not.

Anyway, if those command where proven useful in the past, then it is the right one to switch. Usually I would set up at the start of a project, so I don't really try to undo stuff. But just start fresh.

Meaning:

• bookdown::clean_book(TRUE) => start fresh bookdown project
• change config output_dir and other stuff
• bookdown::render_book()
• Commit everything (new stuff and also result of first step deletion.)

The only time I am using git rm -r --cache if I am right is when I want to untrack something without deleting it in my worktree because I want to now ignore it in the future

[yihui]

Reading all these steps, I feel we should just provide an "official" Github action to automatically publish to either docs/ or gh-pages (based on user's configuration). Then we won't need to document the complicated git commands or emphasize the importance of .nojekyll (or how to create/maintain it).

With that action, I think the Travis section can be deleted, since there won't be any obvious benefits with using Travis.

Perhaps we should wait till @cderv is back to work on this action, and then greatly simplify this section.

[apreshill]

I agree- I think that would be much more user-friendly. This action exists: https://github.com/r-lib/actions/blob/master/examples/bookdown.yaml but focuses on Netlify.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}