-
Notifications
You must be signed in to change notification settings - Fork 24
/
deploy.Rmd
116 lines (74 loc) · 5.54 KB
/
deploy.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---
title: "Deployment"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Deployment}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
This vignette describes the process of deployment, how you get your hugodown website off your local computer and on to the internet for everyone to see. The easiest workflow for most people is to use [netlify](https://www.netlify.com). I'll describe this process in details, and then discuss other approaches that require a manual build site.
(Most of these techiques assume that you're already familiar with the basics of Git and GitHub. If you're not, you can try the Dropbox deployment described below, or try reading with [Happy Git and GitHub for the R user](http://happygitwithr.com/) by Jenny Bryan.)
## Netlify
(Adapted from [A Spoonful of Hugo: The netlify.toml File](https://alison.rbind.io/post/2017-06-12-up-and-running-with-blogdown/#deploy-in-netlify) by Alison Hill, with permission.)
First, create an account if you don't already have one:
1. Navigate to [Netlify](https://www.netlify.com/) and click on the *Sign Up* link.
```{r, echo = FALSE, out.width = "400px"}
knitr::include_graphics("netlify-landing.png")
```
2. Sign up with *GitHub* to connect your GitHub and Netlify accounts.
```{r, echo = FALSE, out.width = "400px"}
knitr::include_graphics("netlify-sign-up.png")
```
If you use a different version control service, select GitLab or BitBucket instead.
Next create a netlify site for your GitHub repo:
1. On the netlify website, go *New Site from Git* and pick your repo. You'll be prompted to fill in these fields. They are probably already filled in correctly for you:
```{r, echo = FALSE, out.width = "400px"}
knitr::include_graphics("netlify-deploy-settings.png")
```
Leave the advanced settings as is, and click deploy site. (This won't work but we'll fix it momentarily.)
Finally, configure your blog with `netlify.toml`. This prevents the biggest source of pain when deploying with netlify: version mismatches.
1. Check you have a `_hugodown.yaml` file that contains `hugo_version: 0.66.0` or similar. It's added automatically you created your site with a hugodown helper; you'll need to add it yourself if you've created the site another way.
2. Run `hugodown::use_netlify_toml()`, check the new `netlify.toml` in, commit, and push to Github.
Now return to [netlify](https://app.netlify.com), and look in the deploy log. You should see entries like:
10:00:42 PM: Build ready to start
10:00:43 PM: build-image version: 8e315e54bc4032a32e73290be556cde4f8348c12
...
10:00:56 PM: Found netlify.toml. Overriding site configuration
...
10:01:02 PM: Installing Hugo 0.68.3
10:01:02 PM: Hugo Static Site Generator v0.68.3-157669A0 linux/amd64 BuildDate: 2020-03-24T12:05:34Z
...
10:01:04 PM: Executing user command: hugo
10:01:04 PM: Building sites …
...
10:01:23 PM: Site is live
Success!
## Manual builds
The advantage of netlify is that automatically runs hugo for you; in other deployment scenarios you'll need to run `hugodown::build_site()` and publish the `public/` directory that it creates. The following sections provide some advice for deployment scenarios that need this.
### RStudio connect
For most sites, `rmarkdown::publish_site()` should just work.
If you deploy your site this way, and it doesn't look quite right (e.g. missing style sheets) it's likely because the theme you're using requires a `baseURL`. In this case, you'll need to update your `config.toml` with the URL for your site and republish.
### GitHub pages
You'll need to make a few changes to your site:
- Run `file.create("static/.nojekyll")`. This ensures that GitHub pages knows that you're using a regular HTML website, not a jekyll website (jekyll is GitHub's own blogging system).
- If you have a custom domain name, create a `static/CNAME` file containing your domain name (e.g. just `tidyverse.org`, not `https://tidyverse.org`). Note that setting a custom domain name in the admin settings on your GitHub repo will not work.
- In `config.toml`:
- Set `publishDir = "docs/"`
- Set `baseURL` to the url where you site will be published.
To deploy:
- Run `hugodown::build_site()` and check in the rendered `docs/` directory. (If no `docs/` directory is created, double check your config above).
After the first deploy, you'll need to go the admin page for your repo and select \"master branch `/docs` folder) for source:
```{r, echo = FALSE, out.width = "400px"}
knitr::include_graphics("github-setup.png")
```
### Site44 (dropbox)
If you don't use Git and GitHub, one deployment option is [Site44](https://www.site44.com/), a service that allows you to publish websites from within Dropbox folders. Site44 creates a `Dropbox/Apps/site44` directory, and any folders within that directory are published as websites.
The recommended workflow for deploying hugodown websites to Site44 is to develop your website in a separate project directory, and then, when it's ready for final publishing, run `build_site()` then copy the contents of the `public` directory to the folder for your website.
### Amazon S3
If you are a user of Amazon Web Services you can serve your website directly from Amazon S3. This option is a bit more technically involved than GitHub Pages, Netlify, or Site 44. See the article on [Hosting a Static Website on Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) for additional details.