GitHub Website Publishing of "Knit"-Generated HTML files in RStudio - html

Question

I want to share a step-by-step illustration on how to publish online your work on RStudio using GitHub pages.
A lot of people taking the Coursera courses on data have problems with it if they don't come from computer science, including myself, so I want to share a system that works. I'm sure it can be greatly improved.

Answer 1

Let's do it step-by-step, really easy:
1. Start with Github, not with RStudio.
Don't have an account, sign-up for one - it's free and incredibly valuable. Now go to Repositories (top menu bar), and press on the green button New in the upper-right-hand corner. Give a name to the repository ("test" for our puposes). You can skip the Description if you are in a hurry to proving to yourself that it works (same for the prompt to write some memo style one-liner under README). So go... click on Create Repository (green button). Now don't panic... just go directly to Settings (the cogwheel symbol in the vertical menu on the right-hand side). Perfect! One more click and we're there... Launch automatic page generator. Now we enter the guided part. Feel free to leave all this as is for now... We can modify it later, or we can go back and do it all over again when we know the end of the story (with a real repository that we do intend to publish. Click on Continue to layouts. Click on any of the designs (I chose "Architect)... And Publish page (green button upper-right corner). Beautiful!
Quick check: Click on Settings again, and check under GitHub Pages for the message: "Your site is published at http://...github.io/test. In my case the address is http://rinterested.github.io/test/ (was... I erased it after I finished this post) beacuse my Github account is RInterested. Very critical: pay attention to the structure: github.io without this there's no website. Now you can go to your browser, type the address and see that a new site has been born (caution: sometimes this takes minutes to materialize).
2. Now it's time to go to RStudio. If you're taking the Coursera course this is your comfort zone. If not I will assume that you've been working with [R], and that a simple download of RStudio (free online) is about to change your life for the better.
So we start RStudio and we go to the upper-right corner, where there is a cube containing an R, and the word Project. See it? Great, because we are going to start a New Project from the pull-down menu. Pop-up... which one to choose? Version Control is the answer. More pop-ups... No panicking... Click on the gray/red/green sideways GIT symbol ("Git Clone a project from a Git repository"). We have that, remember? We called it "Test". And we are facing a final screen with three fields to fill in. Under Repository URL we need to enter information that will require a quick trip back to Github for a second...
Are you there? OK... Do you see the HTTPS clone URL thing with a clipboard symbol on the right, half-way down within the test repository? Click on the clipboard symbol... Copied! Great! Now we go back to the screen with questions on RStudio, where we got re-routed, and do a right-click and paste, filling in the Repository URL field of the questionnaire. The rest is not critical. Press on Create Project... That's it!
3. Time to work. Let's now create a new R Markdown document by clicking on the corresponding option on the pull-down menu in the left-upper corner (green plus sign on a sheet of paper icon). Give it a name. You are the author. Select HTML. Click OK. Now you can modify, add, or just leave what popped-up on the screen as is to finish up the demonstration. Notice that there are so-called chunks of code started with ``{r} which indicate that the following code will be executed upon rendering the html document (or pdf). echo=FALSE means that only the result of the code (not the actual command) will be printed.
OK. Press on the top menu where you see a knitting pin (Knit HTML)... give it a name and save the document... Very important... whatever you name it it has to end up in .Rmd (case sensitive). What about "cars.Rmd"? Original enough... Save it and watch RStudio do its magic... Hopefully you're now admiring a beautiful webpage with a plot and numbers... Only one problem... It is NOT online.
4. Pushing our work to GitHub:
We are going now in the opposite direction. First, click on the GiT super-cool symbol on the top menu (above "knit HTML" depending on the configuration of your RStudio). It's a pull-down menu. Select Commit. You can select cars.html, or everything. Disregard a warning message, and post an ultra-short note under "Commit message". Whatever you want to write (e.g. "update"?). Click on the Commit button - very important! Now you are ready to click on Push... You guessed it... It's the green button. You will be prompted to enter your Github account Username and Password. Do so.
5. Back to GitHub:
Refresh the page displaying our "test" repository. You should now see the additional documents, including cars.html
Quick check: Go to your browser and enter in the URL bar what for me would be rinterested.github.io/test/cars.html (remember that you can get your own website address by going under Settings as explained above), and then just tag on the name of the document we have worked on with RStudio.
6. Hyperlink the pages:
As a test click on "index.html" under the "test" repository and somewhere there, in the body embed the following:
Click here to go to cars.
You will have to click on the pencil icon to edit this file. When done click on Commit changes. Go back on the browser to see your site. Refresh until it's updated with the hyperlink you just embedded. Click on it... You are now watching your RStudio work fully functional online. Magic!
Now it's just a matter to change things around using some html code quickly accessible online, changing the wording on the index.html (home page), or perhaps building a nice site with internal cohesiveness from scratch.
Good luck!

Answer 2

An alternative (more manual) approach - anything covered on the initial answer skipped.
1. Create a Repository in GitHub
Let's call it Course_project without need to README - we're just going to need its URL.
2. Open Windows PowerShell (or Git Bash)
Opening Git Bash is as simple as to right click on the directory in Windows Explorer we want to select, and click on Git Bash here. I'll use PowerShell. You can get the directory you're in by typing pwd. From there we can type ls to list subfolders, all along changing directory to reach where we want to be - for instance cd R to get R as the working directory.
Clone project by typing https://github.com/RInterested/Course_project.git (I am RInterested, so change that part to your GitHub username; also remember that "Course_project" is the name of this project). Change the directory to Course_project by typing cd Course_project. We now create a branch without parent branches: git checkout --orphan gh-pages. Make sure that the cloned Course_project is empty by typing: git rm -rf . We'll soon work with real RStudio markdown, but just to test what we have done so far, we can type into the empty working directory a name of a webpage: echo "Test Page" > index.html. Time now to Add/Commit/Push: git add index.html followed by git git commit -a -m "first commit", and git push origin gh-pages. This page is now visible at: http://RInterested.github.io/Course_project/index.html.
3. Creating content with RStudio
We have a directory (Course_project) and a toy index.html in it... We need real content. So we go to RStudio. Create an R Markdown file and name it (I'm calling it mtcars). Check HTML as the output. Change the document (some info about it in the answer above). Finally, an important step: Save it as Index.Rmd(make sure that the R working directory is the same as in PowerShell). Click on knit HTML to create the html file rendering the R code embedded in R Markdown.
4. Pushing it upstream with PowerShell
Now we have material within the directory Course_project, but it is not online - it is still local (you can go to it with Windows Explorer and see the html file under "index"). Type git status to see the changes made, and again follow the routine Add/Commit/Push: git add ., followed by git commit -a -m "commit", and git push origin gh-pages.
After a while the page will be live in http://RInterested.github.io/Course_project/index.html
5. Adding a second page
We can now start a second R Markdown file on RStudio (I labeled it Second_page and saved it as Second_page.Rmd. After writing what we want we knit HTML, and we can see these two new files appear in the Course_project local folder. We simply have to Add/Commit/Push like before in PowerShell. The new page will be in http://rinterested.github.io/Course_project/Second_page.html. It is very easy now to type a hyperlink on the first (index.Rmd) to the second (Second_page.html), knit the index.Rmd, and push it up to the web.