3 Chapter 2: Creating a Quarto Website and Deploying on GitHub Pages

3.1 Introduction to Quarto

Quarto is an open-source scientific and technical publishing system developed by Posit (formerly RStudio). It is designed to provide a unified authoring experience for creating documents, reports, presentations, and websites using multiple programming languages, including R, Python, Julia, and more. Quarto is built on top of Pandoc, which allows it to leverage advanced features for document rendering.

3.1.1 Key Characteristics of Quarto

Multi-Language Support: Quarto supports not only R but also Python, Julia, and other languages. This flexibility allows users to write documents that incorporate code from different programming environments seamlessly.
Unified Authoring System: Quarto combines the functionalities of various R packages like RMarkdown, Bookdown, and Distill into a single system. This integration simplifies the process of creating complex documents without needing to switch between different tools.
Enhanced Document Features: Quarto offers advanced features such as:
- Cross-References: Easily reference figures, tables, and sections across documents.
- Collapsible Sections: Create collapsible content blocks for better organization and readability.
- Customizable Formats: Output documents in multiple formats (HTML, PDF, Word) with consistent styling.
Improved YAML Syntax: Quarto uses a more intuitive YAML syntax for document configuration compared to RMarkdown, making it easier to specify options and settings.
Command-Line Interface (CLI): Quarto can be used from the command line, allowing for automation in document generation and integration into workflows outside of RStudio.
Version Control Friendly: Quarto documents are plain text files that work well with version control systems like Git, facilitating collaboration among teams.

3.2 Comparison of Quarto and RMarkdown

While both Quarto and RMarkdown serve similar purposes in creating dynamic documents, there are significant differences between them:

Feature	Quarto	RMarkdown
Language Support	Multi-language (R, Python, Julia)	Primarily R; supports Python with limitations
Document Structure	Unified structure across formats	Different structures depending on the output format
YAML Syntax	More intuitive and flexible	Traditional YAML syntax
Output Formats	Supports HTML, PDF, Word; highly customizable	Supports HTML, PDF; customization requires additional packages
Cross-Referencing	Built-in support with Lua filters	Requires additional packages (e.g., Bookdown)
CLI Integration	Fully functional command-line interface	Limited CLI capabilities
Ease of Transition	Designed to be compatible with existing RMarkdown files	Existing RMarkdown files can be used but may require adjustments

3.2.1 Benefits of Using Quarto Over RMarkdown

Flexibility: With its multi-language support, Quarto allows users to integrate code from various programming languages within the same document.
Simplified Workflow: By combining features from multiple tools into one system, Quarto streamlines the authoring process.
Advanced Features: The inclusion of modern features like collapsible sections and enhanced cross-referencing improves document usability.
Future-Proofing: As a next-generation tool built on Pandoc’s capabilities, Quarto is designed to evolve with the needs of users in scientific publishing.

3.2.2 In a nutshell

Quarto represents a significant advancement over RMarkdown by providing a more versatile and powerful framework for creating dynamic documents. Whether you are an experienced R user or new to programming languages like Python or Julia, Quarto offers an accessible way to produce high-quality reports and publications that meet modern standards for reproducibility and collaboration.

In the following sections, we will guide you through the process of creating a Quarto website and deploying it on GitHub Pages, showcasing the capabilities of this innovative tool in web development.

3.3 2. GitHub and GitHub Pages

GitHub is a platform for version control and collaboration, allowing you to host your code repositories online. GitHub Pages is a feature of GitHub that allows you to publish static websites directly from a repository. By combining Quarto with GitHub Pages, you can easily create and share interactive content online.

3.4 3. Step-by-Step Guide: Creating a Quarto Website and Deploying on GitHub Pages

Objective: By the end of this session, participants will have a live Quarto website hosted on GitHub Pages.

3.4.1 Step 1: Set Up Your Environment

Install R and RStudio:
- Ensure that R and RStudio are installed on your computer. Download them from the official websites if needed.
Install Quarto:
- Download and install Quarto from its official website. Follow the installation instructions specific to your operating system.

Install Git:

Install Git https://git-scm.com/

Open RStudio and go to `Tools` \> `Global Options` \> `Git/SVN` to configure Git.

3.4.2 Step 2: Create a New Quarto Website Project

Open RStudio:
- Launch RStudio and click on File > New Project.
Create a New Directory:
- Select New Directory, then choose Quarto Website as the project type.
Name Your Project:
- Enter a directory name. If you plan to deploy using GitHub Pages, consider naming it YourGitHubUsername.github.io.
- When creating your GitHub account, be sure to use your real name (e.g. John Doe). Then your website url will be johndoe.githuh.io.
Create the Project:
- Choose the directory location and click Create Project. This sets up the basic structure for your website with default files like index.qmd, about.qmd, _quarto.yml, and styles.css.

3.4.3 Step 3: Customize Your Website

Edit Content Files:
- Open index.qmd in RStudio and modify it using Markdown or HTML to customize your homepage content. You may introduce briefly who you are and the purpose of this website
- Similarly, edit about.qmd or create new .qmd files for additional pages. Give a full description of yourself to introduce yourself to your audience.
Configure Navigation:
- Open _quarto.yml to configure the website’s navigation, title, and theme. Add links to new pages you create in this file.
- Example of the YAML file (be aware that the indentation is important):

title: "My Quarto Website"
output:
  html_document:
    theme: cosmo
  pdf_document:
    toc: true
navbar:
  left:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
    - text: "Research"
      href: teaching.html
    - text: "CV"
      href: cv.pdf

3.4.4 Step 4: Render and Preview Your Website

Render the Website:
- Click the Render button in RStudio to generate HTML files from your .qmd documents. The rendered site will appear in the Viewer pane.
Preview in Browser:
- Click Show in new window to view your site in a web browser.

3.4.5 Step 5a: Deploy Your Website on GitHub

** Locate the _site folder/directory:**
- Navigate to the _site folder in your project directory. This is the folder holding all the website content and files
Create a GitHub Repository:
- Go to GitHub and create a new repository with the name “username.github.io” name as your project directory”. Be sure this username is exactly the name you use for login.
- Create a Readme.md file in the repository. This is a requirement for the repository to be created. Just enter “website”
- Click on the “Add file -> Upload files
- Go to the _site folder, highlight all folders and file and drag and drop to the box “Drag files here to add them to your repository”
- Wait for the upload to complete, then click Commit Changes
Access Your Live Site:
- After a few minutes, your site will be live at https://YourGitHubUsername.github.io/.

3.4.6 Step 5b: (Advanced) Deploy Your Website on GitHub Pages using Git

Initialize a Git Repository:
- In RStudio, open the Terminal and run:

cd _site
git init
git add .
git commit -m "Initial commit"

Create a GitHub Repository:
- Go to GitHub and create a new repository with the name “username.github.io” name as your project directory”. Be sure this username is exactly the name you use for login.
Push Local Repository to GitHub:
- In the Terminal, connect your local repository to GitHub:

git remote add origin https://github.com/YourGitHubUsername/YourRepositoryName.git
git branch -M main
git push -u origin main

GitHub removed support for password authentication in August 2021. Use a Personal Access Token (PAT) instead of GitHub password.

Step 1: Create a Personal Access Token

Go to GitHub.com and log in
- Click your profile picture → Settings
- Scroll down to Developer settings → Personal access tokens → Tokens (classic)
- Click Generate new token → Generate new token (classic)
- Give it a descriptive name (e.g., “RStudio Website”)
- Set expiration (recommend 90 days or 1 year)
Select scopes: Check repo (this gives full repository access)
- Click Generate token Copy the token immediately and save it
- Important: You won’t be able to see it again!

Step 2: Use the Token

When prompted for credentials:

Username: username Password: Paste the Personal Access Token (not GitHub password)

Enable GitHub Pages:
- On GitHub, navigate to your repository settings, scroll down to “GitHub Pages,” and select the branch (usually main) for deployment.
Access Your Live Site:
- After a few minutes, your site will be live at https://YourGitHubUsername.github.io/.

3.4.7 Exercises

Exercise 1: Create a new page titled “Projects” and add it to your site’s navigation.
Exercise 2: Customize the theme of your site by editing _quarto.yml.
Exercise 3: Add an image gallery to one of your pages using Markdown.

# Chapter 2: Creating a Quarto Website and Deploying on GitHub Pages ## Introduction to Quarto Quarto is an open-source scientific and technical publishing system developed by Posit (formerly RStudio). It is designed to provide a unified authoring experience for creating documents, reports, presentations, and websites using multiple programming languages, including R, Python, Julia, and more. Quarto is built on top of Pandoc, which allows it to leverage advanced features for document rendering. ### Key Characteristics of Quarto 1. **Multi-Language Support**: Quarto supports not only R but also Python, Julia, and other languages. This flexibility allows users to write documents that incorporate code from different programming environments seamlessly. 2. **Unified Authoring System**: Quarto combines the functionalities of various R packages like RMarkdown, Bookdown, and Distill into a single system. This integration simplifies the process of creating complex documents without needing to switch between different tools. 3. **Enhanced Document Features**: Quarto offers advanced features such as: - **Cross-References**: Easily reference figures, tables, and sections across documents. - **Collapsible Sections**: Create collapsible content blocks for better organization and readability. - **Customizable Formats**: Output documents in multiple formats (HTML, PDF, Word) with consistent styling. 4. **Improved YAML Syntax**: Quarto uses a more intuitive YAML syntax for document configuration compared to RMarkdown, making it easier to specify options and settings. 5. **Command-Line Interface (CLI)**: Quarto can be used from the command line, allowing for automation in document generation and integration into workflows outside of RStudio. 6. **Version Control Friendly**: Quarto documents are plain text files that work well with version control systems like Git, facilitating collaboration among teams. ## Comparison of Quarto and RMarkdown While both Quarto and RMarkdown serve similar purposes in creating dynamic documents, there are significant differences between them: | Feature | Quarto | RMarkdown | |------------------------|------------------------|------------------------| | **Language Support** | Multi-language (R, Python, Julia) | Primarily R; supports Python with limitations | | **Document Structure** | Unified structure across formats | Different structures depending on the output format | | **YAML Syntax** | More intuitive and flexible | Traditional YAML syntax | | **Output Formats** | Supports HTML, PDF, Word; highly customizable | Supports HTML, PDF; customization requires additional packages | | **Cross-Referencing** | Built-in support with Lua filters | Requires additional packages (e.g., Bookdown) | | **CLI Integration** | Fully functional command-line interface | Limited CLI capabilities | | **Ease of Transition** | Designed to be compatible with existing RMarkdown files | Existing RMarkdown files can be used but may require adjustments | ### Benefits of Using Quarto Over RMarkdown 1. **Flexibility**: With its multi-language support, Quarto allows users to integrate code from various programming languages within the same document. 2. **Simplified Workflow**: By combining features from multiple tools into one system, Quarto streamlines the authoring process. 3. **Advanced Features**: The inclusion of modern features like collapsible sections and enhanced cross-referencing improves document usability. 4. **Future-Proofing**: As a next-generation tool built on Pandoc's capabilities, Quarto is designed to evolve with the needs of users in scientific publishing. ### In a nutshell Quarto represents a significant advancement over RMarkdown by providing a more versatile and powerful framework for creating dynamic documents. Whether you are an experienced R user or new to programming languages like Python or Julia, Quarto offers an accessible way to produce high-quality reports and publications that meet modern standards for reproducibility and collaboration. In the following sections, we will guide you through the process of creating a Quarto website and deploying it on GitHub Pages, showcasing the capabilities of this innovative tool in web development. ## 2. GitHub and GitHub Pages GitHub is a platform for version control and collaboration, allowing you to host your code repositories online. GitHub Pages is a feature of GitHub that allows you to publish static websites directly from a repository. By combining Quarto with GitHub Pages, you can easily create and share interactive content online. ## 3. Step-by-Step Guide: Creating a Quarto Website and Deploying on GitHub Pages **Objective:** By the end of this session, participants will have a live Quarto website hosted on GitHub Pages. ### Step 1: Set Up Your Environment 1. **Install R and RStudio:** - Ensure that R and RStudio are installed on your computer. Download them from the official websites if needed. 2. **Install Quarto:** - Download and install Quarto from its official website. Follow the installation instructions specific to your operating system. 3. **Install Git:** - Install Git <https://git-scm.com/> - ``` Open RStudio and go to `Tools` \> `Global Options` \> `Git/SVN` to configure Git. ``` ### Step 2: Create a New Quarto Website Project 1. **Open RStudio:** - Launch RStudio and click on `File` \> `New Project`. 2. **Create a New Directory:** - Select `New Directory`, then choose `Quarto Website` as the project type. 3. **Name Your Project:** - Enter a directory name. If you plan to deploy using GitHub Pages, consider naming it `YourGitHubUsername.github.io`. - When creating your GitHub account, be sure to use your real name (e.g. John Doe). Then your website url will be johndoe.githuh.io. 4. **Create the Project:** - Choose the directory location and click `Create Project`. This sets up the basic structure for your website with default files like `index.qmd`, `about.qmd`, `_quarto.yml`, and `styles.css`. ### Step 3: Customize Your Website 1. **Edit Content Files:** - Open `index.qmd` in RStudio and modify it using Markdown or HTML to customize your homepage content. You may introduce briefly who you are and the purpose of this website - Similarly, edit `about.qmd` or create new `.qmd` files for additional pages. Give a full description of yourself to introduce yourself to your audience. 2. **Configure Navigation:** - Open `_quarto.yml` to configure the website’s navigation, title, and theme. Add links to new pages you create in this file. - Example of the YAML file (be aware that the indentation is important): ```{yaml} title: "My Quarto Website" output: html_document: theme: cosmo pdf_document: toc: true navbar: left: - text: "Home" href: index.html - text: "About" href: about.html - text: "Research" href: teaching.html - text: "CV" href: cv.pdf ``` ### Step 4: Render and Preview Your Website 1. **Render the Website:** - Click the `Render` button in RStudio to generate HTML files from your `.qmd` documents. The rendered site will appear in the Viewer pane. 2. **Preview in Browser:** - Click `Show in new window` to view your site in a web browser. ### Step 5a: Deploy Your Website on GitHub 1. \*\* Locate the \_site folder/directory:\*\* - Navigate to the \_site folder in your project directory. This is the folder holding all the website content and files 2. **Create a GitHub Repository:** - Go to GitHub and create a new repository with the name "username.github.io" name as your project directory". Be sure this username is exactly the name you use for login. - Create a Readme.md file in the repository. This is a requirement for the repository to be created. Just enter "website" - Click on the "Add file -\> Upload files - Go to the \_site folder, highlight all folders and file and drag and drop to the box "Drag files here to add them to your repository" - Wait for the upload to complete, then click Commit Changes 3. **Access Your Live Site:** - After a few minutes, your site will be live at `https://YourGitHubUsername.github.io/`. ### Step 5b: (Advanced) Deploy Your Website on GitHub Pages using Git 1. **Initialize a Git Repository:** - In RStudio, open the Terminal and run: ```{bash} cd _site git init git add . git commit -m "Initial commit" ``` 2. **Create a GitHub Repository:** - Go to GitHub and create a new repository with the name "username.github.io" name as your project directory". Be sure this username is exactly the name you use for login. 3. **Push Local Repository to GitHub:** - In the Terminal, connect your local repository to GitHub: ```{bash} git remote add origin https://github.com/YourGitHubUsername/YourRepositoryName.git git branch -M main git push -u origin main ``` 4. GitHub removed support for password authentication in August 2021. Use a Personal Access Token (PAT) instead of GitHub password. Step 1: Create a Personal Access Token - Go to GitHub.com and log in - Click your profile picture → Settings - Scroll down to Developer settings → Personal access tokens → Tokens (classic) - Click Generate new token → Generate new token (classic) - Give it a descriptive name (e.g., "RStudio Website") - Set expiration (recommend 90 days or 1 year) - Select scopes: Check repo (this gives full repository access) - Click Generate token Copy the token immediately and save it - **Important:** You won't be able to see it again! Step 2: Use the Token - When prompted for credentials: Username: username Password: Paste the Personal Access Token (not GitHub password) 5. **Enable GitHub Pages:** - On GitHub, navigate to your repository settings, scroll down to "GitHub Pages," and select the branch (usually `main`) for deployment. 6. **Access Your Live Site:** - After a few minutes, your site will be live at `https://YourGitHubUsername.github.io/`. ### Exercises - **Exercise 1:** Create a new page titled "Projects" and add it to your site’s navigation. - **Exercise 2:** Customize the theme of your site by editing `_quarto.yml`. - **Exercise 3:** Add an image gallery to one of your pages using Markdown.