29 Publishing Resources
This section discusses how we built edav.info/ and includes references for building sites and books of your own using R.
Want to get started making a site complete with Travis CI like this one? Zach Bogart has created a bookdown-template you can clone and build off of to create your own site. For instructions, consult the README file.
The biggest selling-point for
bookdown is that it allows you to make content that is both professional and adaptable. If you want to update a regular book, you need to issue another edition and go through a lot of hassle. With
bookdown, you can publish it in different formats (including print, if desired) and be able to change things easily when needed.
bookdown for edav.info/ because it allows us to present a lot of content in a compact, searchable manner, while also letting students suggest updates and contribute to its structure. Again, it is professional and adaptable (The default
bookdown output is essentially just an online book, but we tried to liven it up by adding a lot of helpful icons, logos, and banners to improve navigation).
Below are some helpful references we used in creating edav.info/, which may be helpful if you are interested in creating your own website or online resource with R.
How to Start a Bookdown Book: The hardest part about
bookdownis getting it up and running. Sean Kross has the best template instructions we found. We started this project by cloning his template repo and building off of it. Excellent descriptions on what all the files do and what is essential to start your project.
bookdown: Authoring Books and Technical Documents with R Markdown: This textbook by Yihui Xie, author of the
bookdownpackage, explains everything
bookdownis able to accomplish (published using
bookdown…because of course it is). An incredible informative reference which we always kept close by. Author’s blurb:
A guide to authoring books with R Markdown, including how to generate figures and tables, and insert cross-references, citations, HTML widgets, and Shiny apps in R Markdown.
RStudio Bookdown Talk: Yihui Xie (author of the
bookdownpackage) discusses his package and what it can do in a one-hour talk. Good for seeing finished examples.
bookdown.org: Site for the
bookdownpackage. Has a bunch of popular books published using
bookdownand some info about how to get started using the package.
Creating Websites in R: This tutorial, written by Emily Zabor (a Columbia alum), provides a thorough walkthrough for creating websites using different R tools. She discusses how to make different kinds of sites (personal, package, project, blog) as well as GitHub integration and step-by-step instructions for getting setup with templates and hosting. Very detailed and worth perusing if interested in making your own site.
29.5 Adding a custom domain name
There are several parts to adding a custom domain name.
- Buy a domain name and edit DNS settings
Note that some tutorials list older IP addresses. Check here for the recommended ones.
- Change settings in your repo
In Settings, add your custom domain name in the GitHub Pages section.
- Add a CNAME file to the
This is a very simple text file named CNAME (all caps). The contents should be one line with the custom domain name.
For more detail on steps 2 and 3, see: Emily Zabor’s Tutorial on Custom Domains
29.6 Make a custom 404 page
Your site may be lovely, but a default 404 page is always a let down. Not if but when someone types part of your URL incorrectly or a link gets broken, you should make sure there is something to see other than a boring backend page you had no input in designing. This article explains the process, but all you have to do is make a file called
404.html in your root directory and GitHub will use it rather than the default. Because of this, there is really no excuse for not having one. Here’s a look at our 404 page. Hopefully you aren’t seeing it that often.
- Always include a link back to the site: Throw the user a life-saver.
- Make it clear that something went wrong: Don’t hide the fact that this page is because of some error.
- Use absolute paths: The URL that throws the 404 error may be nested within unexpected folders. Make sure if you have any images or links, they work regardless of the file path (use “/images/…” rather than “images/…”, maybe link directly to css/homepage, etc.)
- Other than that, have fun with it!: There are plenty of examples of people making excellent 404 pages. It should make a frustrating experience just a little bit more bearable.
29.7 Hooking up Travis
This tutorial is designed to help you add Travis to your GitHub Pages bookdown web site. It assumes you already have a working web site, with pages stored in a
We’re not necessarily recommending the
gh-pages route; we chose it since we found examples that worked for us using this method. Since the
/docs folder is a newer and cleaner approach, it is certainly possible that it provides a better way to organize the repo.
That said, there are various tutorials for how to set up the
gh-pages branch; it appears that the best way to do so is to create an orphan branch, as explained here.
We should note that this makes it all seem very easy to add Travis, which actually was not the case at all for us. I guess everything looks easy in retrospect. If you run into trouble, let us know by filing an issue or submitting a pull request. More info on all the contribution stuff can be found on our contribute page.
29.7.1 Add Travis files to GitHub repo
Add these files to your repo:
- No changes
- Remove the last two lines if you’re only interested in a GitHub Pages book.
- The only changes you need to make are to the
git configlines. You need to use your GitHub email, but the username can be anything.
- The only changes you need to make are to the
29.7.2 Add Travis service
Create a Travis account on www.travis-ci.org by clicking on “Sign in with GitHub” on the top right. Click Authorize to allow Travis to have proper access to GitHub.
Go back to GitHub and create a personal access token (PAT) if you don’t have one already. You can do so here. Note that you must save your PAT somewhere because you can’t access it once it’s created. Also note that the PAT provides a means to access your GitHub repo through an API, an alternative means to logging in with your username/password (There is an API Token in Travis but this is not the one to use).
Return to your Travis profile (travis-ci.org/profile/[GITHUB username]) and click the button next to the appropriate repo to toggle it on. Click on Settings next to the button and add your saved GITHUB_PAT under Environmental Variables: set “Name” to “GITHUB_PAT” and “Value” to the value of the token.
If all goes well, you can sit back, relax, and watch Travis do the work for you.
29.8 Notes on our workflow
29.9 Other resources
- blogdown: Creating Websites with R Markdown: Textbook on the
blogdownpackage, another option for generating websites with R.
- Getting Started with GitHub Pages: Short article from GitHub Guides on creating/hosting a website using GitHub Pages.
- A Beginner’s Guide to Travis CI for R: Fantastic blog post by Julia Silge, includes debugging advice that helped us solve a problem involving installing packages with system requirements.