How to Create a Blog Using Quarto

tutorial

quarto

github

blogging

Learn how to set up your own stylish data blog using Quarto and GitHub Pages — no advanced web skills required.

Author

Flavia Felletti

Published

May 11, 2025

Introduction

Creating your own blog is a great way to share your data projects. With Quarto and GitHub Pages, you can easily publish a professional-looking blog for free, using simple Markdown and code.

This setup is ideal for:

Showcasing data science or programming projects
Writing technical tutorials (like this ;) )
Maintaining a lightweight, fast, and version-controlled website

In this tutorial, I’ll walk you through how to create your blog step by step using Quarto and GitHub Pages.

🧰 What You’ll Need

Technical Requirements

Install Quarto Quarto is the publishing engine. You can write in Markdown, embed code, and produce beautiful web pages, one great thing about Quarto is that it supports various languages like R, Python, Julia, and Observable JavaScript. Download and install it from the official site.
Create a GitHub account (if you don’t have one yet) You’ll use GitHub to host your website for free via GitHub Pages.
Install Git (if not already installed) Quarto uses Git to publish your site to GitHub. Install Git and set it up locally.

Optional but helpful: A code editor like VS Code or PyCharm makes writing .qmd files easier, but it’s not required. I am personally using PyCharm Community Edition (the free version of PyCharm) Download PyCharm.

🚀 Step-by-Step: Create Your Blog

We’ll now create and publish your blog in just a few steps.

1. Create a New Quarto Website

Open your terminal and run the following command:

quarto create-project my-blog --type website
cd my-blog

This creates a new folder called “my-blog” with the basic structure of a Quarto website. You can rename my-blog to whatever you want. You should now have gotten the following files:

index.qmd (your homepage)
about.qmd (your About page)
_quarto.yml (the configuration file that defines your site layout and style)
A posts/ folder to hold your blog posts

If you didn’t get a posts/ folder, create it manually. You will need it to hold all your blog posts!

2. Preview Your Website Locally

To check if everything worked correctly, run the following command to see your site in your browser:

quarto preview

This launches a localhost preview. Any time you change a .qmd file and save it, the preview updates automatically. Remember, this is not your site yet, but just a local preview. Next I will guide you through creating a proper site using GitHub Pages.

3. Configure the Site for GitHub Pages

To publish your site using GitHub Pages, you need to configure Quarto to render your output into a folder named docs/.

In the root of your project, open the _quarto.yml file and modify or add the following line:

project:
  type: website
  output-dir: docs

Then render your site:

quarto render

Quarto will generate the site in a docs/ folder, which GitHub Pages can use for publishing.

4. Push Your Site to GitHub

Create a new repository on GitHub (e.g., “my-blog”)

Initialize Git and link your local project to your GitHub repo:

git init
git remote add origin https://github.com/yourusername/my-blog.git
git add .
git commit -m "Initial commit"
git push -u origin main

Don’t forget to replace “yourusername” with your actual username and “my-blog” with your actual blog name ;). 🔐 If you’re using HTTPS, GitHub will ask you for a token instead of a password. You can generate one here.

5. Enable GitHub Pages

Go to your GitHub repository
Click on Settings → Pages
Under Source, select:

Branch: main
Folder: /docs

Click Save. After a few seconds, your site will be live at: https://yourusername.github.io/data-blog/

Note: This is the path I chose to publish my blog, however there are alternative ways to do it, which may better satisfy your requirements, have a look here: GitHub Pages for Quarto.

✍🏿 Create Your First Blog Post

If you do not have a folder for your posts already, create a new one. I keep my posts inside the folder “posts”, within my own project folder DataBlog. Now you can create a new file, which will become your first post. For example:

posts/how-to-create-a-data-blog.qmd

You can start with this YAML header and modify it accordingly with your needs:

---
title: "My first post title"
date: 2025-05-11
categories: [tutorial, quarto, github, blogging]
format:
  html:
    toc: true
    code-tools: true
    theme: cosmo
---

Then write your content below using Markdown and code blocks as needed.

When ready, render the site again:

quarto render

Now push the changes to GitHub:

git add .
git commit -m "Add first blog post"
git push

Visit your blog again — Congratulations, your new post is live! ✌🏿

🗑️ Remove the Demo Post

When you create a new Quarto website project, it often comes with a demo blog post inside the posts/ folder. This is just a placeholder to show you how blog posts work. It usually has a name like:

posts/welcome/index.qmd

“You’ll probably want to remove the demo post to keep your site clean. I removed them manually from Pycharm, but you can removed them from your terminal using a command like:

rm posts/welcome/index.qmd

Don’t forget not to render and commit!

quarto render
git add .
git commit -m "Remove demo post"
git push

🎨 Customize the Site

Now you may want to customize the site. To do this, you need to change the _quarto.yml file. Open it and change title, navigation bar, theme, and styling according to your wishes.

For example:

project:
  type: website
  output-dir: docs

website:
  title: "My Blog"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css

🧩 Optional: Add an Image and About Info

Write a small biography in about.qmd. and add a personal image. Here you can also add your contacts.

This is how my about.qmd looks like:

---
title: "About"
image: flavia_cartoon.png
about:
  template: jolla
  links:
    - icon: linkedin
      text: LinkedIn
      href: https://www.linkedin.com/in/flavia-felletti-phd-8066141b8/
    - icon: github
      text: Github
      href: https://github.com/Flazoukie

---

## About This Blog

Welcome to my blog! Here is where I share my journey in data science through hands-on projects, tutorials, and reflections.
I hope you'll find something useful, inspiring, or entertaining for you here.

Feel free to take inspiration!

Ensure the image is copied into the docs/ folder so it shows up on GitHub Pages. Remember now to render to turn your Markdown files into a working website:

quarto render

This generates a docs/ folder with all the HTML files that make up your website.

Don’t forget to commit and push to GitHub to apply teh changes to your website!

git add .
git commit -m "Customize the website"
git push

✅ Wrap-Up

Congratulations! 🎉 You now have a working blog hosted for free, using Quarto and GitHub Pages.

If you found this guide helpful, or want to give me your feedback, feel free to connect on LinkedIn or explore more on this blog.

Happy blogging!

--- title: "How to Create a Blog Using Quarto" description: > <span class="description">Learn how to set up your own stylish data blog using Quarto and GitHub Pages — no advanced web skills required.</span> author: Flavia Felletti date: 2025-05-11 categories: [tutorial, quarto, github, blogging] image: ../welcome.png format: html: toc: true code-tools: true theme: cosmo title-block: true title-block-style: "default" css: styles.css --- ## Introduction Creating your own blog is a great way to share your data projects. With **[Quarto](https://quarto.org)** and **[GitHub Pages](https://pages.github.com/)**, you can easily publish a professional-looking blog for free, using simple Markdown and code. This setup is ideal for: * Showcasing data science or programming projects * Writing technical tutorials (like this ;) ) * Maintaining a lightweight, fast, and version-controlled website In this tutorial, I’ll walk you through how to create your blog step by step using Quarto and GitHub Pages. --- ## 🧰 What You’ll Need ### Technical Requirements 1. **Install [Quarto](https://quarto.org/docs/get-started/)** Quarto is the publishing engine. You can write in Markdown, embed code, and produce beautiful web pages, one great thing about Quarto is that it supports various languages like R, Python, Julia, and Observable JavaScript. Download and install it from the official site. 2. **Create a GitHub account** (if you don’t have one yet) You'll use GitHub to host your website for free via GitHub Pages. 3. **Install Git** (if not already installed) Quarto uses Git to publish your site to GitHub. [Install Git](https://git-scm.com/downloads) and set it up locally. > _Optional but helpful_: A code editor like VS Code or PyCharm makes writing `.qmd` files easier, but it’s not required. I am personally using PyCharm Community Edition (the free version of PyCharm) [Download PyCharm](https://www.jetbrains.com/pycharm/download/?section=windows). --- ## 🚀 Step-by-Step: Create Your Blog We’ll now create and publish your blog in just a few steps. --- ### 1. Create a New Quarto Website Open your terminal and run the following command: ```bash quarto create-project my-blog --type website cd my-blog ``` This creates a new folder called "my-blog" with the basic structure of a Quarto website. You can rename my-blog to whatever you want. You should now have gotten the following files: * index.qmd (your homepage) * about.qmd (your About page) * _quarto.yml (the configuration file that defines your site layout and style) * A posts/ folder to hold your blog posts ::: tip If you didn’t get a `posts/` folder, create it manually. You will need it to hold all your blog posts! ::: ### 2. Preview Your Website Locally To check if everything worked correctly, run the following command to see your site in your browser: ```bash quarto preview ``` This launches a localhost preview. Any time you change a .qmd file and save it, the preview updates automatically. Remember, this is not your site yet, but just a local preview. Next I will guide you through creating a proper site using GitHub Pages. ### 3. Configure the Site for GitHub Pages To publish your site using GitHub Pages, you need to configure Quarto to render your output into a folder named docs/. In the root of your project, open the _quarto.yml file and modify or add the following line: ```yaml project: type: website output-dir: docs ``` Then render your site: ```bash quarto render ``` Quarto will generate the site in a docs/ folder, which GitHub Pages can use for publishing. ### 4. Push Your Site to GitHub Create a new repository on GitHub (e.g., "my-blog") Initialize Git and link your local project to your GitHub repo: ```bash git init git remote add origin https://github.com/yourusername/my-blog.git git add . git commit -m "Initial commit" git push -u origin main ``` Don't forget to replace "yourusername" with your actual username and "my-blog" with your actual blog name ;). 🔐 If you're using HTTPS, GitHub will ask you for a token instead of a password. You can generate one here. ### 5. Enable GitHub Pages 1. Go to your GitHub repository 2. Click on Settings → Pages 3. Under Source, select: * Branch: main * Folder: /docs Click Save. After a few seconds, your site will be live at: https://yourusername.github.io/data-blog/ > _Note:_ This is the path I chose to publish my blog, however there are alternative ways to do it, which may better satisfy your requirements, have a look here: [GitHub Pages for Quarto](https://quarto.org/docs/publishing/github-pages.html#render-to-docs). --- ## ✍🏿 Create Your First Blog Post If you do not have a folder for your posts already, create a new one. I keep my posts inside the folder "posts", within my own project folder DataBlog. Now you can create a new file, which will become your first post. For example: ```bash posts/how-to-create-a-data-blog.qmd ``` You can start with this YAML header and modify it accordingly with your needs: ```yaml --- title: "My first post title" date: 2025-05-11 categories: [tutorial, quarto, github, blogging] format: html: toc: true code-tools: true theme: cosmo --- ``` Then write your content below using Markdown and code blocks as needed. When ready, render the site again: ```bash quarto render ``` Now push the changes to GitHub: ```bash git add . git commit -m "Add first blog post" git push ``` Visit your blog again — Congratulations, your new post is live! ✌🏿 ## 🗑️ Remove the Demo Post When you create a new Quarto website project, it often comes with a demo blog post inside the posts/ folder. This is just a placeholder to show you how blog posts work. It usually has a name like: ```bash posts/welcome/index.qmd ``` “You’ll probably want to remove the demo post to keep your site clean. I removed them manually from Pycharm, but you can removed them from your terminal using a command like: ```bash rm posts/welcome/index.qmd ``` Don't forget not to render and commit! ```bash quarto render git add . git commit -m "Remove demo post" git push ``` ## 🎨 Customize the Site Now you may want to customize the site. To do this, you need to change the _quarto.yml file. Open it and change title, navigation bar, theme, and styling according to your wishes. For example: ```yaml project: type: website output-dir: docs website: title: "My Blog" navbar: left: - href: index.qmd text: Home - about.qmd format: html: theme: cosmo css: styles.css ``` 🧩 Optional: Add an Image and About Info Write a small biography in about.qmd. and add a personal image. Here you can also add your contacts. This is how my about.qmd looks like: ```yaml --- title: "About" image: flavia_cartoon.png about: template: jolla links: - icon: linkedin text: LinkedIn href: https://www.linkedin.com/in/flavia-felletti-phd-8066141b8/ - icon: github text: Github href: https://github.com/Flazoukie --- ## About This Blog Welcome to my blog! Here is where I share my journey in data science through hands-on projects, tutorials, and reflections. I hope you'll find something useful, inspiring, or entertaining for you here. ``` Feel free to take inspiration! Ensure the image is copied into the docs/ folder so it shows up on GitHub Pages. Remember now to render to turn your Markdown files into a working website: ```bash quarto render ``` This generates a docs/ folder with all the HTML files that make up your website. Don't forget to commit and push to GitHub to apply teh changes to your website! ```bash git add . git commit -m "Customize the website" git push ``` ## ✅ Wrap-Up Congratulations! 🎉 You now have a working blog hosted for free, using Quarto and GitHub Pages. If you found this guide helpful, or want to give me your feedback, feel free to connect on [LinkedIn](https://www.linkedin.com/in/flavia-felletti-phd-8066141b8/) or explore more on this blog. Happy blogging!