Quarto Markdown: publishing

Publish (3/7)

Publish your Quarto web

1 Overview

GitHub Pages is a website hosting service that enables you to publish content based on source code managed within a GitHub repository.

Use the quarto publish command to publish content rendered on your local machine.

quarto publish will make several operations with GitHub Pages:

• provision,
• create pipeline,
• create branch with HTML source
• parse .qmd to .html
• render (or build)
• deploy,
• hosting,
• publish

gh-pages build and deployment #17: example of Actions triggered by Quarto publish

The most important for us will be to make a branch gh-pages the first time where the output HTML will be deployed with quarto publish gh-pages.

Note(0) Files On Repository with TOKEN

Your need to create a repository on GitHub with the Quarto pages .qmd pushed there.

Create repository, commit and push files to repository with Sync tool. To write our repository you need to:

1. Create Token on GitHub.com: Creating a personal access token
2. Use this token on your Visual Code - Git, link:

$git config --global user.name "Mona Lisa"
$git config --global user.mail "monalisa@davinci.com"
$git config --global user.password "4WTVEG43_Q34WG435GAWER4_Q4vsrsrggr_3D44"

Tip(1) gh-pages service from GitHub

You can modify these options in Settings : Pages for your repository.

Notegh-pages service from github.com

fig 13

Noteat first gh-pages branch doesn’t exist: don’t worry, quarto will create later

fig 14

Notemaster/main is our branch: root

fig 15

Tip(2) Define Ignoring Output

It’s important to note that you don’t need to check your _site or _book directory into version control (if you have done this in the past you know it makes for very messy diffs!). Before proceeding you should add the output directory of your project to .gitignore. For example:

## .gitignore

/.quarto/
/_site/

If you’ve already checked these files into source control you may need to remove them explicitly:

## Terminal

git rm -r _site

Tip(3) Publish on branch gh-pages

Once you have configured the source branch and updated your .gitignore, navigate to the directory where your project / git repository is located, make sure you are not on the gh-pages branch, and execute the quarto publish command for GitHub Pages:

## Terminal

quarto publish gh-pages

The publish command will confirm that you want to publish, render your content, copy the output to a special gh-pages branch, push that branch to GitHub, and then open a browser to view your site once it is deployed.

After this first time it will be no necessary to call gh-pages brach, once it has been defined as default:

##Terminal

quarto publish 

Tip(4) Website published

Your Quarto website will be published by GitHub pages on:

userName.github.io\repositoryName

2 Publishing quarto website 2024

Note(0) set up tools

You need to set up these tools:

• git & gh CLI tools installed
• github.com account created and user logged in
• gh auth login (our machine connected to Github.com) executed
  • auth wil be done by web browser code
• Visual Code with user logged
• quarto engine installed
• quarto extension in Visual Code installed

Tip(1) create local and remote repositories

Once the web in rendered you should Publish to GitHub by the visual tool Git on VisualCode

Create the public repository on remote

Select the files your do not want to push to remote repository

Tip(2) first commit and push

Once remote repository created, you may commit and push the quarto project

Before commit & push you must identify the user name and email

The commit/push and first-time definition of remote repository on local can be done by CLI

git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/AlbertProfe/SpeedMan.git
git push -u origin main

You could rename master to main creating the branch main

We execute the commands: commit, branch, remote add, push

Commands executed properly

We check the remote repository on github.com

Tip(3) publish on gh-pages

Now is time to publish our quarto project to gh-pages

gh-pages will publish the branch gh-pages created by quarto

The quarto engine is finishing the jobs from quarto publish gh-pages

Tip(4) quarto website published

quarto project finally published on the internet

quarto project finally published on the internet by gh-pages