Hello, Quarto

Week 0
Published

December 29, 2023

In this post, we’ll get set up with Quarto.

Quarto is a static site converter, which you can use to turn plaintext documents into attractive webpages. You should have already installed Quarto and signed up for GitHub when completing the software installation (details in BruinLearn).

Make a GitHub repository

Let’s first make a GitHub repository to host your blog.

  1. From your user page (https://github.com/<your_user_name>), click on the Repositories tab.
  2. Click on New button.
  3. Create a new repository. Carefully choose your repository name, and make sure not to select Add a README file to create a completely empty repository.

Generate blog files using Quarto

This should be very straightforward using the instructions at this link.

All you need to do is run the following code at the terminal.

quarto create-project myblog --type website:blog

Then once a folder appears, run this line.

quarto preview myblog

Feel free to replace myblog with a different name.

quarto preview should open up a link that looks like http://localhost:6832 in your web browser. The port number probably looks different.

Turn the generated Quarto blog into a GitHub repository

First, move into your blog folder.

cd myblog

Then, follow the steps under “…or create a new repository on the command line” part of your GitHub repository inside your blog folder.

echo "# <your-repository-name>" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/<your-user-name>/<your-repository-name>.git
git push -u origin main

Publish on GitHub Pages

Now, run this line on your terminal in the same directory.

quarto publish

When prompted, select these options.

? Provider: › GitHub Pages
? Authorize (Y/n) › Yes

Finally, the terminal should print out something like this:

Switched to a new branch 'gh-pages'
[gh-pages (root-commit) 386cdba] Initializing gh-pages branch
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/kose-y/test-quarto/pull/new/gh-pages
remote:
To https://github.com/kose-y/test-quarto.git
* [new branch]      HEAD -> gh-pages
Your branch is up to date with 'origin/main'.
Switched to branch 'main'
From https://github.com/kose-y/test-quarto
* branch            gh-pages   -> FETCH_HEAD
Rendering for publish:

[1/4] posts/post-with-code/index.qmd
[2/4] posts/welcome/index.qmd
[3/4] index.qmd
[4/4] about.qmd

branch 'gh-pages' set up to track 'origin/gh-pages'.
HEAD is now at 386cdba Initializing gh-pages branch
Preparing worktree (resetting branch 'gh-pages'; was at 386cdba)
fatal: pathspec '.' did not match any files
[gh-pages 1c6e662] Built site for gh-pages
29 files changed, 6535 insertions(+)
create mode 100644 .nojekyll
create mode 100644 about.html
create mode 100644 index.html
create mode 100644 listings.json
create mode 100644 posts/post-with-code/image.jpg
create mode 100644 posts/post-with-code/index.html
create mode 100644 posts/welcome/index.html
create mode 100644 posts/welcome/thumbnail.jpg
create mode 100644 profile.jpg
create mode 100644 search.json
create mode 100644 site_libs/bootstrap/bootstrap-icons.css
create mode 100644 site_libs/bootstrap/bootstrap-icons.woff
create mode 100644 site_libs/bootstrap/bootstrap.min.css
create mode 100644 site_libs/bootstrap/bootstrap.min.js
create mode 100644 site_libs/clipboard/clipboard.min.js
create mode 100644 site_libs/quarto-html/anchor.min.js
create mode 100644 site_libs/quarto-html/popper.min.js
create mode 100644 site_libs/quarto-html/quarto-syntax-highlighting.css
create mode 100644 site_libs/quarto-html/quarto.js
creatorigin https://github.com/kose-y/test-quarto.git (fetch)
origin  https://github.com/kose-y/test-quarto.git (push)
To https://github.com/kose-y/test-quarto.git
386cdba..1c6e662  HEAD -> gh-pages

[✓] Deploying gh-pages branch to website (this may take a few minutes)
[✓] Published to https://kose-y.github.io/test-quarto/

Go to the website on the last line, and if you see a webpage there, congrats! Your blog is up and running. At the moment, it’s just a copy of the template, so it’s not personalized in any way.

Edit a post

Preview your blog again:

quarto preview

Then edit the welcome page in posts/welcome/index.qmd. Any sort of change will do.

Once you save the file, you’ll see that the preview page on the web browser is automatically updated.

You can also add a new page following instructions in this post.

Edit configuration

The file posts/_metadata.yml contains shared options for the posts. It is highly recommended to modify freeze: true to freeze: auto, as you are expected to modify your posts often.

# options specified here will apply to all posts in this folder

# freeze computational output
# (see https://quarto.org/docs/projects/code-execution.html#freeze)
freeze: auto

# Enable banner style title blocks
title-block-banner: true

Please check this page for more information.

Publish again

Once you’ve made all these additions, publish the result again using quarto publish. In a few minutes, you should see your new post on your website.

References