Quick steps to making a copy of the lab manual & publishing it
Quick guide to making a copy of the lab manual that also publishes the book, and is able to be edited online and then is republished automatically (using GitHub Actions).
- If you don't have one, create a free github user account and sign in. (www.github.com)
- From the lab manual repository page, fork the repository to your account. This will create your copy of the lab manual files on your own github account.
Uncheck Copy the main branch only to be able publish to the gh-pages branch in the next step
Here I created a copy in my personal user account rather than in the Fay Lab organization. After it does its thing you will see that the username for the repository is now yours, whereas before it was 'thefaylab/lab-manual'.
3. Next, we need to tell github where the html files for the website are located so it can publish your lab manual. Under 'Settings' choose 'Pages'.
Set the Branch to 'gh-pages'. Save.
4. To view your published lab manual, head back to the main repository page (github.com/your_user_name/lab-manual). On the right side, click the gear-icon, select 'Use your GitHub Pages website'.
Your lab manual is now published!
- You are now ready to make changes to the lab manual content to personalize it. Click on one of the .qmd files. Then click on the pencil icon in the top right to enter 'edit' mode. You can then make changes directly online.
Once done, you want to save, or 'commit' these changes. You can either hit 'Commit changes' straight away, or preferably, give future you a note about what the changes you made were (there's a default 'updated the file' but that's pretty vague!). Best to keep your message simple but specific.
- Sit back and wait for the magic to happen! When you hit 'Commit changes' this triggers a GitHub Action workflow that runs a program to republish the book based on the changes. This GitHub Action was already set up in your fork of the Lab Manual repo. If you go to the 'Actions' tab you can watch this updating happen (and see if the workflow breaks).
Hopefully all is good and if you go to your published version (your_user_name.github.io/lab-manual) and visit the relevant chapter you should see that your changes have been updated.
- That's it! One of the things we like about the automatic publishing is that it is easier for members of our team to contribute to the manual, even if they are not yet super-familiar or confident with using R and git.
Please let @gavinfay know if anything on here is unclear, or if these steps don't work for you.