Chapter 6 Deployment and Hosting on Github
Here is how to deploy this book and host on github
https://bookdown.org/yihui/bookdown/github.html
https://rachaellappan.github.io/bookdown/
Note that the echo = FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot.
- Setting it up with GitHub This involves using a bit of Git. If you are unfamiliar with Git, Software Carpentry has great introductory Git lessons but I will describe the steps here anyway.
The goal is to create a repository on GitHub (a place to upload the files for your Bookdown book), and connect the files on your computer to this repository so that the book can be displayed online from your GitHub account.
If you would like to keep track of the changes you make to your book (version control), set this up before you start working on it.
6.0.0.1 Create a GitHub account, if you don’t have one already.
Create a new private repository while logged in to GitHub in a web browser (from the “+” menu in the top right). This is where the files in your book will be uploaded to; as mine contain a lot of analysed data I prefer to keep the files in a private repository but this is up to you. Keep the resulting webpage open for now.
If you are using Windows, install Git Bash. Keep the default options until you are prompted to select a terminal emulator, and select “Use Windows default console window.” This is how it is installed for Software Carpentry workshops. The Git Bash terminal will allow you to use Git from the command line on a Windows machine.
Connect Git to your GitHub account by giving it your email and username:
git config --global user.email "you@example.com" git config --global user.name "Your Name"
Open up Git Bash and move to the directory where your Bookdown book is. For example (my USB is in G: drive): cd /g/PhD/Bookdown/bookdown-start-master/ Initiate a repository inside this directory: git init Connect the repository here on your computer to the online repository in your GitHub account. Do this by adding all of the files in the directory to the staging area of Git (the place for files that are ready to be saved in their current state to keep track of their changes): git add . Commit the changes (save a snapshot of the files as they currently are) with whatever message you like:
git commit -m “Started book” Tell Git where your online repository is - this link will be on the webpage you have after creating the online repository through your GitHub account:
git remote add origin https://github.com/rachaellappan/test.git And send the files there:
git push -u origin master You will be prompted for your GitHub login. Then if you refresh your GitHub repository, you can see the basic Bookdown files are now there.
Now you can start working on your book. Whenever you want to “save” the current version of the book, just repeat the git add, git commit and git push steps as above. This is useful for keeping track of how the book has changed (for example, if you need to revert back to a previous version) but your files are always saved on your computer.
- Knitting the whole book Once all of my chapters are ready to become a complete book, I use the simple one-liner as described here in R while in the book’s directory with index.Rmd.
#bookdown::render_book(“index.Rmd,” “bookdown::gitbook”)
- Hosting the book Now that the book is ready for the world to see, you simply need to tell GitHub where to find the rendered book. In your GitHub repository, enter the settings tab up the top and enable GitHub pages on the /docs folder. Because the book has been knitted, the HTML version of your book has been generated and is in the docs folder. GitHub pages creates a URL that will display those HTML pages.
Note that if your repository is private, people won’t be able to view the files you’ve uploaded to GitHub but they will see the complete book.
That’s it! I hope you find Bookdown as useful a tool as I have, I am always excited by neat and tidy ways to display complex information.
If you have any questions or comments, find me on Twitter or email me!
summary(cars)## speed dist
## Min. : 4.0 Min. : 2.00
## 1st Qu.:12.0 1st Qu.: 26.00
## Median :15.0 Median : 36.00
## Mean :15.4 Mean : 42.98
## 3rd Qu.:19.0 3rd Qu.: 56.00
## Max. :25.0 Max. :120.006.1 Including Plots
You can also embed plots, for example:
