You can use GitHub Pages to host a personal website (one per account) or project sites (unlimited). Here, we’ll walk through the steps for setting up a project site to showcase your work.


If you are starting from scratch, begin at Step 1. If you already have an existing repository that you would like to create a GitHub Page for, you can skip to Step 3.


Step 1: Create a new repository on GitHub

Do so by navigating to Repositories > New. Give your repo an informative name and a description, if you’d like. Initializing it with a README and a .gitignore is recommended.


Step 2: Clone your respository to your computer


Step 2.1: Copy your repository URL from GitHub

Click on the green ‘Code’ button and copy the URL to your clipboard.


Step 2.2: Create a new project in RStudio.

In RStudio, click on Project (top right hand corner) > New Project.


Step 2.3: Select “Version Control.”


Step 2.4: Select “Git.”


Step 2.5: Paste the repo URL and press the ‘Tab’ button on your keyboard to auto-fill the Project Directory Name. Click ‘Create Project.’

Remember to choose where you would like to save your project by clicking on the ‘Browse’ button and picking a subdirectory. I like to save all my projects under a ‘Repositories’ subdirectory for the sake of organization.


Step 3: Create an RMarkdown file and make some edits.


Step 3.1: To create a new R Markdown file, click File > New File > R Markdown… (or click on the green + sign icon in the top left corner of RStudio)


Step 3.2: Give it a title and be sure that the Default Output Format is set to HTML.


Step 3.3: Delete everything after the initial code chunk (i.e. from ## R Markdown at line 12 to Note that... at line 30)…


Step 3.4: …and add some text or code of your own!


Step 3.5: Save and knit your .Rmd file. IMPORTANT: Be sure to name your file as index.Rmd and save to your root directory.

Clicking the knit button will automatically save your `.Rmd file.` If you have not yet saved your file before clicking knit for the first time, it will open up the window to name and save your file before proceeding.

Clicking the knit button will automatically save your .Rmd file. If you have not yet saved your file before clicking knit for the first time, it will open up the window to name and save your file before proceeding.

Your knitted .html file will be saved to your root directory alongside the original .Rmd. You are able to send this .html file to others for viewing, but hang tight…GitHub Pages will make it even easier to share your work and ensure that your collaborators have the most up-to-date version.
NOTE: This knitted document is only stored as an `.html` file on your local computer at this point.

NOTE: This knitted document is only stored as an .html file on your local computer at this point.


Step 4: Push your index.Rmd and index.html to GitHub.

If you are unfamiliar or confused by the process of getting files from your computer to GitHub, check out this fun comic by Erika Heidi.


Step 4.1: Stage your files by checking the boxes under the Git tab.

NOTE: Since I didn't initially push my `gh_pages_example.Rproj`, I'll do that now as well.

NOTE: Since I didn’t initially push my gh_pages_example.Rproj, I’ll do that now as well.


Step 4.2: Commit your files by first adding a descriptive commit message, then click ‘Commit.’


Step 4.3: Push your files to GitHub by clicking ‘Push.’


Step 5: Turn your index.html file into a web page.

We’re almost there! First head back to your GitHub repository and click the Settings tab, then select the Pages option from the menu on the left-hand side of the page.


Step 5.1: To activate your GitHub Page, first select the main branch from the dropdown.


Step 5.2: Set the folder to /(root) (if not already set).

Step 5.3: Now save! GitHub will tell you that “Your site is ready to be published at https://{your-username}.github.io/{your-repo-name}/” in a light blue banner.

It can take a bit for your GitHub Pages build to complete and for your changes to appear (sometimes up to 10 minutes). Be patient :)

If your build isn’t yet ready for viewing, you’ll typically get a 404 error after clicking on your URL.

When the banner surrounding your GitHub Page URL turns green (refreshing your page helps), your build is typically ready to go.

TIP: If your URL still doesn’t want to resolve, adding index after the backslash of your URL sometimes helps to expedite the process. Regardless, patience is often key and your web page will be up and running soon!

Now that you have your web page up and running, you can send your URL to collaborators to easily share your report/work. If you need to make changes, simply edit your index.Rmd in RStudio and push changes to your GitHub repo (i.e Steps 3.4 - 4.3). Your GitHub page will automatically update, which means no need to send a new, updated .html file or a different URL (but remember, it can a few minutes before those changes appear online)!