It uses Liquid to rewrite the web page after it has been compiled, giving you complete control of formatting and allowing you to define custom Markdown syntax. Since it uses only the default tools built in to Jekyll, it works natively on Github Pages! Here is how it works.
This tutorial teaches you to create R Markdown documents with RStudio and publish them via GitHub, using GitHub Pages.
- Github will automatically create pages for you, if you include the markdown file.
- The Github Markdown renderer can automatically detect a simple copy-pasted link and make it a clickable link. Github Pages doesn’t propose a feature to reproduce that behavior, so you’ll have to braces your links with the syntax.
RStudio is a popular integrated development environment for R. It integrates the tools you use with R into a single environment. GitHub Pages allows you to host websites directly from your GitHub repository.
In this tutorial, you will learn how to:
- Create a new repository.
- Work with your repository on your local machine using Git and RStudio.
- Use the GitHub.com website or GitHub Enterprise to complete the GitHub workflow.
- Publish and share your R Markdown documents using GitHub Pages.
Prerequisites
- For this tutorial you will need an account on GitHub.com or GitHub Enterprise.
- If you are new to Git, GitHub and GitHub Pages it is recommended to complete the GitHub Pages from the command-line course first.
- Some programming knowledge with R will be helpful but is not required.
Install Git and RStudio
For this tutorial you will use Git and RStudio to work with your GitHub repository.
- Download and install Git.
- Download and install RStudio (1.1.383 or higher).
- Open RStudio.
Create the remote repository on GitHub
Now that you have what you need installed locally, let’s create the repository that will hold your new website.
- On GitHub.com, create a new repository.Note: if your organization uses GitHub Enterprise you can also create the repository there.
- Name your repository
cars
. You can use a different name. - Enter a description for your repository.
- Choose Public visibility.
- Select Initialize this repository with a README.
- Click Add
.ignore
and selectR
. - Click Create repository.
Clone the repository with RStudio
After you’ve created a repository on GitHub (the remote repository), the next step is to clone it to your local environment.
- On GitHub, navigate to the Code tab of the repository.
- On the right side of the screen, click
Clone or download
. - Click the
Copy to clipboard
icon to the right of the repository URL. - Open RStudio on your local environment.
- Click
File
,New Project
,Version Control
,Git
. - Paste the repository URL and enter TAB to move to the
Project directory name
field. - Click
Create Project
.
Create an R Markdown document in RStudio
Now that you have a local copy of the repository, let’s add an R Markdown document to your project.
- In RStudio click
File
,New File
,R Markdown
. - Choose HTML output as default output.
- Click
File
,Save
to save the document. - Enter
speed-and-distance
and clickSave
.
Commit and push the changes to GitHub
After you have created the R Markdown document and finished making your changes, it is time to commit them.
- In RStudio click the
Git
tab in the upper right pane. - Click
Commit
. - In the
Review changes
view, check the staged box for all files. - Add a commit message, for example
Add initial speed and distance report
. - Click
Commit
. - Click the
Pull
button to fetch any remote changes. - Click the
Push
button to push your changes to the remote repository. - On GitHub, navigate to the Code tab of the repository to see the changes.
Create local branches with Git
Let’s make a couple of more changes in your project using the steps of GitHub Flow. As RStudio currently does not support local branches very well, we will use Git from the command-line in RStudio.
- In RStudio click the
Terminal
tab in the lower left pane. The Terminal tab is next to the Console tab. Note: if you cannot find the Terminal tab, check if you use RStudio version 1.1.383 or higher. ClickHelp
,About RStudio
to check the current version. - Create a new branch. Replace
<BRANCH-NAME>
with a descriptive name, for examplespeed-and-distance-report
: - Check your repository’s status: Notice that although you created a new branch, you are still checked out to master, as indicated by the in-line response from Git.
- Check out to your new branch:
- Verify that you are now checked out to your new branch:
Make local changes with Git
Let’s generate the HTML output in a separate directory called
docs
. To do this we add a function in the heading of the R Markdown document to ‘knit’ the output in the desired output directory.- In RStudio open
speed-and-distance.Rmd
and add the following lines in the heading under thetitle
field: - Click
File
,Save
to save the changes. - Click
Knit
in the document pane forspeed-and-distance.Rmd
.
Commit local changes with Git
After you have created the HTML output, it is time to commit the changes.
- Determine your file’s status. Remember that
git status
allows us to see the status of the files on our branch at any given time. Your file is listed under the headingUntracked files
: - Add your file to the staging area so it’s prepared to become part of the next commit:
- See your file’s current status. Your file is now listed under the heading
Changes to be committed
. This tells us that the file is in the staging area. It also indicates this is a new file: - Commit your file. Replace
<COMMIT-MESSAGE>
with a log message describing the changes, for exampleKnit output to a docs folder
. A commit tells Git to collect all of the files in the staging area and store them to version control as a single unit of work: - See the history of commits:
- See the changes between the master branch and the current branch (HEAD):
Open a pull request on GitHub
Now that you have made some local commits, it is time to send your changes to the remote copy of your repository on GitHub and create a Pull Request.
- Push the changes to the remote repository:
- Create a Pull Request on GitHub.
- Fill out the body of the Pull Request with information about the changes you’re introducing.
Merge your pull request on GitHub
Since this is your repository, you probably don’t have anyone to collaborate with (yet). Go ahead and merge your Pull Request now.
- On GitHub, navigate to the Pull Request that you just opened.
- Scroll down and click the big green
Merge Pull Request
button. - Click Confirm Merge.
- Delete the branch
<BRANCH-NAME>
.
Create the pages site
This tutorial is going to use GitHub Pages to publish the HTML output. To initialize GitHub Pages we need to perform a few more steps:
- In your repository, click the Settings tab.
- Scroll down to the GitHub Pages section.
- Under
Source
, selectmaster branch /docs folder
. - Click
Save
to save the changes. - Click the generated GitHub Pages URL to view the rendered R Markdown document.
Note: GitHub Pages sites are always public when hosted on GitHub.com. If you want to share a site with a select number of people you can use Jekyll Auth. On GitHub Enterprise users need to authenticate to access GitHub Pages sites when private mode is enabled.
Update local repository
After you merge your Pull Request, you will need to update your local copy of the repository.
- In the RStudio Terminal pane, type:
- Type:
- Delete the local branch
: - See the history of your commits in a graph:
You can also view the history of your commits in RStudio. Click
Commit
in the Git pane to open the Review Changes panel and then click History
.Add welcome page, theme and navigation
Let’s add a welcome page, theme and navigation to allow you to publish a collection of R Markdown documents.
- First create a new branch. Again replace
<BRANCH-NAME>
with a descriptive name, for exampleadd-theme-and-navbar
: - Add a file
_site.yml
with the following contents: - Add a new R Markdown document
index.Rmd
. This is your welcome page. - Open
speed-and-distance.Rmd
and remove theknit
andoutput
fields from the heading. The heading will now look like this: - Save the changes.
- Open the
Console
in the left bottom pane and render the site using the following command: - Commit the local changes with Git:
Open a pull request
Now that you have added the home page and navigation, it is time to send your changes to the remote copy of your repository on GitHub and open a new pull request.
- Push the changes to the remote repository:
- Open a Pull Request on GitHub.
- Go ahead and merge your Pull Request.
- View your updated site. The site should look similar to this image.
- Add the GitHub Pages URL to the repository description to make it easier to discover.
If you can’t remember the GitHub Pages URL you can always visit the URL in the GitHub Pages section on the settings page.
Congratulations! ?
You have completed the GitHub workflow with RStudio and added a GitHub Pages site to your project to publish your rendered R Markdown documents.
Links
- The R Markdown Websites article on the R Markdown website is a good resource to build GitHub Pages websites that host collections of R Markdown documents.
- Use GitHub Desktop if you prefer to use a graphical user interface rather than typing Git commands in the terminal when working with branches in RStudio.
Welcome to the Markdown Community Page
Markdown is
a text-to-HTML conversion tool for web writers. Markdown allows you towrite using an easy-to-read, easy-to-write plain text format, thenconvert it to structurally valid XHTML (or HTML).
This page is maintained by and for the markdown community to document varioustools and resources available to document authors and developers, as well asimplementors of the various markdown implementations.
Authors
Coming soon...
Developers
Github Pages Markdown Math
Whether you're building a web site, a text editor, or something else, if yourproject needs to process markdown documents, you'll need to chose animplementation of a parser library. While the language your project iscoded in will likely have the largest impact on which implementation youchose, there are a number of other factors to consider. Is performancea high priority? Perhaps bindings to a C library will suit you best.Will untrusted users be able to post documents to your web site? Be sureyou are sanitizing the HTML to avoid XSS attacks and the like. Do youwant to offer support for a superset of Markdown's syntax? Will yoube writting your own superset? Some implementations come as/is, whileothers have varying degrees of customizability. Will your project have aninternational audience? Perhaps an implementation that supports Unicodeinput and/or right-to-left text is right for you.
Github Pages Html
Implementors
If you would like to develop your own implementation of the parser, you maywant to take a look at the rather lengthy list of existing implementationsalready out there (if your implementation is missing from the list, please add it).Obviously, not every one of those implementations parses markdown text in exactlythe same way. As this fragmentation of Markdown can cause frustration to thedocument author, it is important to be aware of the existing implementationsand how they behave. The very useful tool, Babelmark 2, has been providedby John MacFarlane to compare the output of various implementations. See John'sFAQ to add your implementation. The FAQ also discusses why this all mattersand provides examples of some common edge cases that various implementationsdisagree on.