Overview: a powerful workflow

Publishing a bookdown (Xie 2020) website with GitLab Pages is as easy as:

  • hosting a repository on GitLab
  • adding a configuration file to the project

You will get a hosting service for your bookdown book (like GitHub Pages) and great features which are not available with GitHub Actions and GitHub Pages:

  • pull requests previews
  • a review application dedicated to non git users that allows them to comment on these previews

Host a project on GitLab

As GitHub, GitLab is a web-based Git repository manager. Creating a new project on GitLab is fairly intuitive for GitHub users. GitLab users can create unlimitate private projects for free (see here).

GitLab also offers a continuous integration service (GitLab CI) and a static websites hosting service (GitLab Pages) in its free plan.1
These features are also present in the open source software GitLab Community Edition (CE) which is widely used in industry as a self hosted git repository manager.

Add a GitLab CI configuration file

Add the following .gitlab-ci.yml file in the root of the project:

image: rocker/verse:4.0.2

.bookdown:
  stage: deploy
  script:
    - Rscript -e "bookdown::render_book('index.Rmd', 'all', output_dir = 'public')"
  artifacts:
    paths:
      - public

pages:
  extends: .bookdown
  only:
    - master

mr-review:
  extends: .bookdown
  after_script:
    - echo "ENVIRONMENT_URL=https://$CI_PROJECT_NAMESPACE.$CI_PAGES_DOMAIN/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html" >> deploy.env
  artifacts:
    reports:
      dotenv: deploy.env
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: $ENVIRONMENT_URL
  only:
    - merge_requests

For explanations, see section 1.

See the result

When the CI job is done, the website is served on GitLab Pages.
CI jobs status can be found in CI / CD menu > Jobs. An example, here.
The address of the GitLab Pages project can be found in Settings > Pages. An example, here.

For each merge request, you also can access to a preview version of your website. Here is a demo:

  • open this merge request page

  • click on the button View app

  • note the Review button on the right hand side of the website. With this button, you can leave a feedback on the merge request.

References

Xie, Yihui. 2020. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.


  1. CI pipelines are limited to 2,000 minutes per month↩︎