From 519c3566a88d5e4901425bddce171edf02aff63f Mon Sep 17 00:00:00 2001 From: "Hans F. Nordhaug" Date: Mon, 5 Aug 2024 13:43:55 +0200 Subject: [PATCH 1/5] Add instructions for GitLab Pages Resolves #1994 --- docs/publishing/_providers.md | 1 + docs/publishing/ci.qmd | 8 +++++++- docs/publishing/gitlab-pages.qmd | 34 ++++++++++++++++++++++++++++++++ docs/publishing/other.qmd | 4 ++-- 4 files changed, 44 insertions(+), 3 deletions(-) create mode 100644 docs/publishing/gitlab-pages.qmd diff --git a/docs/publishing/_providers.md b/docs/publishing/_providers.md index f85e3aa6f8..41f9dbc060 100644 --- a/docs/publishing/_providers.md +++ b/docs/publishing/_providers.md @@ -4,6 +4,7 @@ |----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Quarto Pub](/docs/publishing/quarto-pub.qmd) | Publishing service for Quarto documents, websites, and books. Use Quarto Pub when you want a free, easy to use service for publicly available content. | | [GitHub Pages](/docs/publishing/github-pages.qmd) | Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub. | +| [GitLab Pages](/docs/publishing/gitlab-pages.qmd) | Publish content based on source code managed within a GitLab repository. Use GitLab Pages when the source code for your document or site is hosted on GitLab. | | [Posit Connect](/docs/publishing/rstudio-connect.qmd) | Publishing platform for secure sharing of data products within an organization. Use Posit Connect when you want to publish content within an organization rather than on the public internet. | | [Posit Cloud](/docs/publishing/posit-cloud.qmd) | Create data projects and publish results from your web browser. Use Posit Cloud when you want to organize all your static documents and interactive applications in one place. | | [Netlify](/docs/publishing/netlify.qmd) | Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities. | diff --git a/docs/publishing/ci.qmd b/docs/publishing/ci.qmd index 787e0b6977..f23e82840f 100644 --- a/docs/publishing/ci.qmd +++ b/docs/publishing/ci.qmd @@ -38,7 +38,7 @@ Below we'll describe how to implement each of these strategies using [GitHub Act ## GitHub Actions -[GitHub Actions](https://docs.github.com/en/actions){data-heading="GitHub Actions"} is a Continuous Integration service from GitHub, and an excellent choice if your source code is already managed it a GitHub repository. Quarto makes available a set of [standard](https://github.com/quarto-dev/quarto-actions) GitHub Actions that make it easy to install Quarto and then render and publish content. +[GitHub Actions](https://docs.github.com/en/actions){data-heading="GitHub Actions"} is a Continuous Integration service from GitHub, and an excellent choice if your source code is already managed in a GitHub repository. Quarto makes available a set of [standard](https://github.com/quarto-dev/quarto-actions) GitHub Actions that make it easy to install Quarto and then render and publish content. Learn about using GitHub Actions with various publishing services here: @@ -48,6 +48,12 @@ Learn about using GitHub Actions with various publishing services here: If you want to use the standard Quarto actions as part of another workflow see the [GitHub Actions for Quarto](https://github.com/quarto-dev/quarto-actions) repository. +## GitLab Pipelines + +[GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="[GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. [Quarto Forge](https://gitlab.com/quarto-forge) makes available a set of [Docker images](https://gitlab.com/quarto-forge/docker) that make it easy to use Quarto to render and publish content with GitLab Pipelines. + +Learn about using GitHub Pipelines to publish your site with [GitLab Pages](gitlab-pages.qmd). + ## Posit Connect If you are publishing a source code version of your content to Posit Connect it's possible to configure Connect to retrieve the code from a Git repository and then render and execute on the Connect Server. diff --git a/docs/publishing/gitlab-pages.qmd b/docs/publishing/gitlab-pages.qmd new file mode 100644 index 0000000000..1bcf86f707 --- /dev/null +++ b/docs/publishing/gitlab-pages.qmd @@ -0,0 +1,34 @@ +--- +title: "GitLab Pages" +--- + +## Overview + +[GitLab Pages](https://pages.github.com/) is a website hosting service that enables you to publish content based on source code managed within a GitLab repository. + +There s currently only one way to publish Quarto websites and documents to GitLab Pages: + +1. Use a [GitLab Pipeline] to automatically render your files (a single Quarto document or a Quarto project) and publish the resulting content whenever you push a source code change to your repository. + +We'll cover each of these methods below, but first an important pre-requisite: you need to have a Git repository on your local machine that is synced to GitLab. The URL of the published website will be derived from the combination of your username and the repository name (e.g. `https://username.gitlab.io/reponame/`). + +You can optionally configure a [custom domain](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/) for a GitLab Pages site, but before exploring that ground you should get your site up and running with the default domain. + +### GitLab Pipeline + +Before setting up the pipeline, add at least on file that will get rendeded and deployed. Enable the pipeline by adding a `.gitlab-ci.yml` file to your repository: + +``` {.yaml filename=".gitlab-ci.yml"} +image: registry.gitlab.com/quarto-forge/docker/quarto + +pages: + script: + - quarto render --execute --to html --output-dir public + artifacts: + paths: + - public +``` + +This pipeline will run whenever you push to your repository. It will also run when you manually trigger the action from the **Build - Pipelines** page of your repository. + +The pipeline will render your content and publish it to GitLab Pages using the [Tier 0](https://gitlab.com/quarto-forge/docker#tier-0) Docker image from [Quarto Forge](https://gitlab.com/quarto-forge). Docker images in this tier are the best option to GitLab CI if you are not doing any computation. diff --git a/docs/publishing/other.qmd b/docs/publishing/other.qmd index 617cdcc565..94fb56c745 100644 --- a/docs/publishing/other.qmd +++ b/docs/publishing/other.qmd @@ -4,7 +4,7 @@ title: "Other Services" ## Overview -There are a wide variety of ways to publish Quarto websites. Other articles cover publishing to [Quarto Pub](quarto-pub.qmd), [GitHub Pages](github-pages.qmd), [Netlify](netlify.qmd), and [Posit Connect](rstudio-connect.qmd). Below we'll describe some general guidelines as well as offer some specific advice for [Firebase](#google-firebase), [Site44], and [Amazon S3]. We'll mostly defer to the documentation provided by the various services, but will note any Quarto website specific configuration required. +There are a wide variety of ways to publish Quarto websites. Other articles cover publishing to [Quarto Pub](quarto-pub.qmd), [GitHub Pages](github-pages.qmd), [GitLab Pages](gitlab-pages.qmd), [Netlify](netlify.qmd), and [Posit Connect](rstudio-connect.qmd). Below we'll describe some general guidelines as well as offer some specific advice for [Firebase](#google-firebase), [Site44], and [Amazon S3]. We'll mostly defer to the documentation provided by the various services, but will note any Quarto website specific configuration required. The most important thing to understand is that website content is by default written to the `_site` sub-directory and book content to the `_book` directory (you can customize either using the `output-dir` option). Publishing is simply a matter of copying the output directory to a web server or web hosting service. @@ -44,4 +44,4 @@ If you are a user of Amazon Web Services you can serve your website directly fro Any web server or web host can be used to deploy a Quarto website. Here's a recent [CNET roundup](https://www.cnet.com/web-hosting/) of other web hosts you could consider. You can also deploy a Quarto website on any internal (intranet) web server. -You can also render and publish Quarto websites using a Continuous Integration (CI) service. See the articles on [Publishing with CI](ci.qmd) for additional details. \ No newline at end of file +You can also render and publish Quarto websites using a Continuous Integration (CI) service. See the articles on [Publishing with CI](ci.qmd) for additional details. From a39be567f06d241feee05d76b2a8e2c7111bc4a4 Mon Sep 17 00:00:00 2001 From: "Hans F. Nordhaug" Date: Mon, 5 Aug 2024 14:32:06 +0200 Subject: [PATCH 2/5] Switch to official, non third-party, Docker images The images from Quarto Forge are not well-maintained. --- docs/publishing/ci.qmd | 2 +- docs/publishing/gitlab-pages.qmd | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/publishing/ci.qmd b/docs/publishing/ci.qmd index f23e82840f..2277ebd40f 100644 --- a/docs/publishing/ci.qmd +++ b/docs/publishing/ci.qmd @@ -50,7 +50,7 @@ If you want to use the standard Quarto actions as part of another workflow see t ## GitLab Pipelines -[GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="[GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. [Quarto Forge](https://gitlab.com/quarto-forge) makes available a set of [Docker images](https://gitlab.com/quarto-forge/docker) that make it easy to use Quarto to render and publish content with GitLab Pipelines. +[GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="[GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. Quarto makes available a set of [Docker images](https://github.com/orgs/quarto-dev/packages) that make it easy to use Quarto to render and publish content with GitLab Pipelines. Learn about using GitHub Pipelines to publish your site with [GitLab Pages](gitlab-pages.qmd). diff --git a/docs/publishing/gitlab-pages.qmd b/docs/publishing/gitlab-pages.qmd index 1bcf86f707..89b8201e53 100644 --- a/docs/publishing/gitlab-pages.qmd +++ b/docs/publishing/gitlab-pages.qmd @@ -19,7 +19,7 @@ You can optionally configure a [custom domain](https://docs.gitlab.com/ee/user/p Before setting up the pipeline, add at least on file that will get rendeded and deployed. Enable the pipeline by adding a `.gitlab-ci.yml` file to your repository: ``` {.yaml filename=".gitlab-ci.yml"} -image: registry.gitlab.com/quarto-forge/docker/quarto +image: ghcr.io/quarto-dev/quarto:latest pages: script: @@ -31,4 +31,4 @@ pages: This pipeline will run whenever you push to your repository. It will also run when you manually trigger the action from the **Build - Pipelines** page of your repository. -The pipeline will render your content and publish it to GitLab Pages using the [Tier 0](https://gitlab.com/quarto-forge/docker#tier-0) Docker image from [Quarto Forge](https://gitlab.com/quarto-forge). Docker images in this tier are the best option to GitLab CI if you are not doing any computation. +The pipeline will render your content and publish it to GitLab Pages using the minimal [official Docker image](https://github.com/orgs/quarto-dev/packages) from Quarto. Switch from `ghcr.io/quarto-dev/quarto:latest` to `ghcr.io/quarto-dev/quarto-full:latest` to get programming and LaTeX support. From 8e3b0a7a3a1ab45c3378fd4cea3cc84ee318797e Mon Sep 17 00:00:00 2001 From: "Hans F. Nordhaug" Date: Mon, 5 Aug 2024 14:38:37 +0200 Subject: [PATCH 3/5] Typos --- docs/publishing/gitlab-pages.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/publishing/gitlab-pages.qmd b/docs/publishing/gitlab-pages.qmd index 89b8201e53..6ffd94e1dc 100644 --- a/docs/publishing/gitlab-pages.qmd +++ b/docs/publishing/gitlab-pages.qmd @@ -16,7 +16,7 @@ You can optionally configure a [custom domain](https://docs.gitlab.com/ee/user/p ### GitLab Pipeline -Before setting up the pipeline, add at least on file that will get rendeded and deployed. Enable the pipeline by adding a `.gitlab-ci.yml` file to your repository: +Before setting up the pipeline, add at least one file that will get rendered and deployed. Enable the pipeline by adding a `.gitlab-ci.yml` file to your repository: ``` {.yaml filename=".gitlab-ci.yml"} image: ghcr.io/quarto-dev/quarto:latest @@ -29,6 +29,6 @@ pages: - public ``` -This pipeline will run whenever you push to your repository. It will also run when you manually trigger the action from the **Build - Pipelines** page of your repository. +This pipeline will run whenever you push to your repository. It will also run when you manually trigger the pipeline from the **Build - Pipelines** page of your repository. The pipeline will render your content and publish it to GitLab Pages using the minimal [official Docker image](https://github.com/orgs/quarto-dev/packages) from Quarto. Switch from `ghcr.io/quarto-dev/quarto:latest` to `ghcr.io/quarto-dev/quarto-full:latest` to get programming and LaTeX support. From 40eeaf0c4cb06f2653a707227d7acb64b6e8acc1 Mon Sep 17 00:00:00 2001 From: Hans Fredrik Nordhaug Date: Mon, 26 Aug 2024 23:48:04 +0200 Subject: [PATCH 4/5] Gitlab is not among the providers supported by the publish command --- docs/publishing/_providers.md | 1 - docs/publishing/ci.qmd | 2 +- docs/publishing/index.qmd | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/publishing/_providers.md b/docs/publishing/_providers.md index 41f9dbc060..f85e3aa6f8 100644 --- a/docs/publishing/_providers.md +++ b/docs/publishing/_providers.md @@ -4,7 +4,6 @@ |----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Quarto Pub](/docs/publishing/quarto-pub.qmd) | Publishing service for Quarto documents, websites, and books. Use Quarto Pub when you want a free, easy to use service for publicly available content. | | [GitHub Pages](/docs/publishing/github-pages.qmd) | Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub. | -| [GitLab Pages](/docs/publishing/gitlab-pages.qmd) | Publish content based on source code managed within a GitLab repository. Use GitLab Pages when the source code for your document or site is hosted on GitLab. | | [Posit Connect](/docs/publishing/rstudio-connect.qmd) | Publishing platform for secure sharing of data products within an organization. Use Posit Connect when you want to publish content within an organization rather than on the public internet. | | [Posit Cloud](/docs/publishing/posit-cloud.qmd) | Create data projects and publish results from your web browser. Use Posit Cloud when you want to organize all your static documents and interactive applications in one place. | | [Netlify](/docs/publishing/netlify.qmd) | Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities. | diff --git a/docs/publishing/ci.qmd b/docs/publishing/ci.qmd index 2277ebd40f..6579661b2f 100644 --- a/docs/publishing/ci.qmd +++ b/docs/publishing/ci.qmd @@ -50,7 +50,7 @@ If you want to use the standard Quarto actions as part of another workflow see t ## GitLab Pipelines -[GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="[GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. Quarto makes available a set of [Docker images](https://github.com/orgs/quarto-dev/packages) that make it easy to use Quarto to render and publish content with GitLab Pipelines. +[GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. Quarto makes available a set of [Docker images](https://github.com/orgs/quarto-dev/packages) that make it easy to use Quarto to render and publish content with GitLab Pipelines. Learn about using GitHub Pipelines to publish your site with [GitLab Pages](gitlab-pages.qmd). diff --git a/docs/publishing/index.qmd b/docs/publishing/index.qmd index 99180d65e6..ac8f57d42a 100644 --- a/docs/publishing/index.qmd +++ b/docs/publishing/index.qmd @@ -8,6 +8,6 @@ There are a wide variety of ways to publish documents, presentations, and websit ## Getting Started -To get started, review the documentation for using one of the following publishing services: +To get started, review the documentation for using one of the following publishing providers supported by the `quarto publish` command: {{< include _providers.md >}} From d5cdce2f0a3ea8d62bf66e303ec4dd646835e682 Mon Sep 17 00:00:00 2001 From: Hans Fredrik Nordhaug Date: Mon, 26 Aug 2024 23:58:49 +0200 Subject: [PATCH 5/5] Typo --- docs/publishing/ci.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/publishing/ci.qmd b/docs/publishing/ci.qmd index 6579661b2f..be90763791 100644 --- a/docs/publishing/ci.qmd +++ b/docs/publishing/ci.qmd @@ -52,7 +52,7 @@ If you want to use the standard Quarto actions as part of another workflow see t [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/){data-heading="GitLab Pipelines"} is a Continuous Integration service from GitLab, and an excellent choice if your source code is already managed in a GitLab repository. Quarto makes available a set of [Docker images](https://github.com/orgs/quarto-dev/packages) that make it easy to use Quarto to render and publish content with GitLab Pipelines. -Learn about using GitHub Pipelines to publish your site with [GitLab Pages](gitlab-pages.qmd). +Learn about using GitLab Pipelines to publish your site with [GitLab Pages](gitlab-pages.qmd). ## Posit Connect