Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add netlify continuous deployment section #1217

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 176 additions & 0 deletions inst/examples/06-publishing.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,182 @@ bookdown::publish_book(render = 'local')

If you have set up your own RStudio Connect server, you can certainly publish the book to that server instead of bookdown.org.

## Netlify Drop

Netlify (<https://netlify.com>) is a platform that offers cloud hosting and serverless backend services for static websites. Netlify offers both free and paid tiers for service, but they also offer a service called Netlify Drop (<https://app.netlify.com/drop>), which is a free publishing option that does not require a Netlify account to start. This option does not rely on your **bookdown** project being in a version-controlled repository. All you need is a **bookdown** project that you can build locally. Watch a quick video introduction here: <https://youtu.be/-LRlQ_jaLAU>

### The build-and-deploy pipeline sequence

This publishing approach sets up the following flow of events:

1. You start with a local **bookdown** project.
1. You build your book locally to an output directory of choice (`_book` by default).
1. You go to Netlify Drop (<https://app.netlify.com/drop>), and drag & drop the output directory into the Netlify browser-based user interface.
1. You make changes to your book, rebuild locally, then drag & drop the output directory again into Netlify to update.

The above is an overview- read on for step-by-step instructions.

### Before you begin

Start with a local **bookdown** project (it does not need to be in GitHub or another version-controlled repository).

:::{.rmdimportant latex=true}
If you don't have an existing book, you can create a simple **bookdown** HTML book to practice with instead:

+ Create a new project with the RStudio Project Wizard by doing *File > New Project > New Directory > Book Project using bookdown*. Choose either `gitbook` or `bs4_book` from the dropdown menu.

+ Alternately, you may use the function `create_gitbook()` or `create_bs4_book()` from your R console.
:::


### Build your book

From your **bookdown** project, build your book locally using whichever method from Chapter \@ref(build-the-book) you prefer.

### Deploy your site

Go to Netlify Drop ([netlify.com/drop](https://app.netlify.com/drop)) where you should see a box like this:

```{r echo=FALSE, fig.align='center', fig.alt="Screenshot of drag & drop deploy box on Netlify"}
knitr::include_graphics("images/netlify-drop.png")
```

Then drag and drop the output directory from your **bookdown** project (`_book` by default, unless you changed this in your `_bookdown.yml` file). You should see your book deploy quickly with a random subdomain name of the form `http(s)://random-word-12345.netlify.com`.

You'll also see a notice that unclaimed sites are deleted after 24 hours. You can sign up for a Netlify account to claim your site and keep it online permanently.

### *Optional: Sign up for Netlify*

Click on the *Sign Up for Netlify* link. Sign up with *GitHub* to connect your GitHub and Netlify accounts (as shown below). If you use a different version control service, select GitLab or BitBucket instead.

```{r netlify-sign-up, echo=FALSE, fig.align='center', fig.alt="Screenshot for signing up for Netlify through GitHub"}
knitr::include_graphics("images/netlify-sign-up.png")
```

### *Optional: Update your site*

After signing up for Netlify, you *can* update this kind of site, but it is a manual update. Go to Netlify.com (<https://www.netlify.com/>) and navigate to find your site, then click on *Deploys*. You should see this box (you may need to scroll to the bottom of this page):

```{r echo=FALSE, fig.align='center', fig.alt="Screenshot of drag and drop deploy update box on Netlify"}
knitr::include_graphics("images/netlify-drag-drop-update.png")
```

Edit your book, build it locally again, then drag and drop the output directory here again.

### *Optional: change the default subdomain* {#netlify-subdomain}

Navigate to your site's landing page on Netlify.com (<https://www.netlify.com/>), click on *Overview > Site Settings*. Under *Site information*, click on *Change site name* and update to `http(s)://<SUBDOMAIN-YOU-WANT-HERE>.netlify.com`. If you want to use a different domain, you need to configure some DNS records of the domain to point it to the Netlify server.

### Drawbacks and alternatives

This workflow is great to quickly share a book prototype. However, if you opt to not claim your site, the link will expire in 24 hours. Even if you do claim your site and set up a Netlify account, this workflow is not ideal for books you are actively editing or collaborating on because every time you update your local version of the book, you need to manually upload the book to Netlify. You are also not reaping the benefits of version control with this approach.

## Netlify continuous deployment {#netlify-cd}

Netlify ([netlify.com](https://www.netlify.com/)) also offers continuous deployment as a free option for hosting your static **bookdown** site. Netlify's free tier offers a few useful and unique features like [branch deploys](https://www.netlify.com/docs/continuous-deployment/#branches-deploys), [deploy previews](https://www.youtube.com/watch?v=s_4UL9oAcVE), and simple [redirect rules](https://www.netlify.com/docs/redirects/).^[For a comparison of Netlify versus GitHub Pages, see: https://yihui.name/en/2017/06/netlify-instead-of-github-pages/] When you create a static site through Netlify, your website will be online in a few seconds with a random subdomain name of the form `http(s)://random-word-12345.netlify.com` provided by Netlify (you can customize the name after making an account).

Continuous deployment means that when you push your code to a Git(Hub) repository, Netlify detects this push, then automatically publishes the updated site for you- no manual steps are needed after the initial setup. As described in the Netlify documentation (https://www.netlify.com/docs/continuous-deployment/):

> "Continuous deployment works by connecting a Git repository to a Netlify site and keeping the two in sync."
Comment on lines +96 to +98
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This approach suppose that the built book is commited to Github in the main branch right ?

Source repo needs to have

  • Source of the book to be able to rebuild the book
  • Source of the website (build book) so that Netlify can retrieve and deploy (bc Netlify does not know how to build the book unlike with Blogdown and Hugo)

I am not sure this is clear to every user. This methods and Github Pages / Gitlab Pages without CI are the same.

Maybe we should mention such things ?



### The build-and-deploy pipeline sequence

This publishing approach sets up the following flow of events:

1. You start with a local **bookdown** project in a GIT repository that is connected to a GitHub repository. The below steps assume you are on your `main` branch.
1. You log in to Netlify and create a new site from GitHub.
1. You set the Netlify publish directory to be your book's output directory (the default is `_book`).
1. You build your book locally, then push your `main` branch to your GitHub repository.
1. The push to `main` triggers Netlify to publish your book from the output directory at: `http(s)://random-word-12345.netlify.com`.
1. Rinse and repeat! Every push to `main` triggers the online version of your book to update on your Netlify site.

The above is an overview- read on for step-by-step instructions.

### Before you begin

1. You need a GitHub (<https://github.com/>) account.^[If you are not familiar with GitHub, we suggest you read through the free online book "Happy Git with R" (<https://happygitwithr.com/>) first before working through these instructions.]

1. You need a Netlify (<https://netlify.com/>) account connected to your GitHub account.

1. Start with a **bookdown** project linked to a remote GitHub repository that you can push/pull to from your local copy.

:::{.rmdimportant latex=true}

If you don't have an existing book, you can create a simple **bookdown** HTML book to practice with instead:

+ Create a new project with the RStudio Project Wizard by doing *File > New Project > New Directory > Book Project using bookdown*. Choose either `gitbook` or `bs4_book` from the dropdown menu.

+ Alternately, you may use the function `create_gitbook()` or `create_bs4_book()` from your R console.

:::


If you have been trying out other publishing approaches, you may want to undo some things in your **bookdown** project:

* Delete the `.nojekyll` file locally if you made one- you don't need it.
* Switch your output directory back to `_book` (the default). In your `_bookdown.yml` file, you can either comment out that line (`#`) or delete it.
* If you want a different output directory, replace all future instances of `_book` with your output directory.
Comment on lines +136 to +137
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why this is needed ?

Netlify lets you pick the folder in which the files for the static website are stored in git right ?

So any output_dir value would work, wouldn't it ?

* Edit your `.gitignore` to make sure that it does **not** include your output directory (i.e., `_book`). From R, you can do [`usethis::edit_git_ignore()`](https://usethis.r-lib.org/reference/edit.html).
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master
```
Comment on lines +139 to +144
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need this for Netlify deployment exactly ?

These commands are to remove a folder from being tracked by Git without removing the folder. Usually when you want to untrack something and add it to gitignore.

Suggested change
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master
```
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
# Tells git to stop tracking the docx/ folder but does not delete this folder
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master

Also maybe you should keep using `main` instead of `master` for examples also ? 


### Sign up for Netlify {#netlify-new}

To setup a new account, go to Netlify (<https://www.netlify.com/>) and click on the *Sign Up* link. Sign up with *GitHub* to connect your GitHub and Netlify accounts (as shown below). If you use a different version control service, select GitLab or BitBucket instead.

```{r ref.label='netlify-sign-up', opts.label = TRUE}
```

### Create a new Netlify site

+ Log in to Netlify.

+ Select *New site from Git*.

+ Follow these next steps within Netlify's *Create a new site* wizard:

+ *Step 1: Connect to Git provider.* Select GitHub. At this point, you may see a pop-up to let you know that Netlify is being authorized to access your GitHub.

+ *Step 2: Pick a repository.* Find the Git repository attached to your **bookdown** project and select it. You can select from all of your personal repositories, or use the drop-down to select an organization that you are a part of.

+ *Step 3: Build options, and deploy!* Start with deploying the master branch only. For the "Basic build settings", leave the Build Command blank. For the Publish Directory, choose your output directory- this will be `_book` by default (no quotes needed).

### (Re-)Build your book

In your local **bookdown** project, make a small insignificant change- you could add a `subtitle` field in the YAML of your `index.Rmd` file like:

```
---
title: "A Minimal Book Example"
subtitle: "I'm a book continuously deployed on Netlify!"
site: bookdown::bookdown_site
---
```

Build your book locally, then commit and push all changes to GitHub.

### View on GitHub

View your GitHub account in your browser, navigate to your **bookdown** repository, and verify that all the rendered book files have been pushed to it successfully. These will be in a folder called `_book` (unless you changed your `output_dir` in your `_bookdown.yml` file).

### View on Netlify

On Netlify, go to your site's page and click on *Deploy* to watch the deploy progress. A few minutes after your last push to GitHub, you should see your extra line of text appear at `http(s)://random-word-12345.netlify.com`.

### *Optional: change the default subdomain*

You may want to change the default subdomain given by Netlify, described previously in Chapter \@ref(netlify-subdomain).

### Drawbacks and alternatives

Using Netlify requires an additional service, but that addition does not add any complexity in terms of accounts (if you sign up using your GitHub account) or file structures present in your repository. The main downside to this approach is that ultimately the rendered book files are stored in your `main` branch on GitHub. Some users prefer to keep the `main` branch clear of all non-source files (i.e., `.html` files); if you are one of these users, you might prefer more advanced deployment options that also build your book for you.


## GitHub

You can host your book on GitHub\index{GitHub} for free via GitHub Pages (https://pages.github.com). GitHub supports Jekyll (http://jekyllrb.com), a static website builder, to build a website from Markdown files. That may be the more common use case of GitHub Pages, but GitHub also supports arbitrary static HTML files, so you can just host the HTML output files of your book on GitHub. The key is to create a hidden file `.nojekyll` that tells GitHub that your website is not to be built via Jekyll, since the **bookdown** HTML output is already a standalone website.
Expand Down
Binary file added inst/examples/images/netlify-drag-drop-update.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added inst/examples/images/netlify-drop.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added inst/examples/images/netlify-sign-up.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.