TL;DR

I’m not a web developer. I don’t know JavaScript. But I still put together a functioning personal site using Quarto, mostly just writing in Markdown and poking at HTML. It lets me share plots and was surprisingly fun to make. This post walks through what I did (and what I figured out along the way).

So this isn’t a tutorial, exactly. And I’m definitely not a web developer. I don’t know JavaScript. I’ve barely touched HTML. But I still built a pretty clean, functional, and actually-useful website using a tool called Quarto.

I wanted something simple. I didn’t want to mess with frameworks or notebooks in the cloud. I just wanted:

• A way to show Python code and the results (like plots and tables)
• Something people could read in their browser, no downloads required
• No Google Colab links that get blocked on work Wi-Fi
• And ideally, a site that didn’t look like it was made in 2004 (not that there's something inherently wrong with that, I just can't pull it off)

My goal was to try and build a portfolio mostly sticking to Markdown and YAML, so Quarto was a good choice for me. Plus a new shiny toy to play with.

Here's how a project page looks:

Why Quarto?

I had never heard of Quarto before a few months ago. I kind of stumbled across it while Googling “how to publish Jupyter notebooks without making people download them.”

Here’s what won me over:

• I can write in Markdown. Like, normal Markdown.
• I can stick Python code blocks in the middle, and Quarto runs the code for me.
• The plots, tables, and results? They show up on the site automatically. No iframe weirdness.
• The whole site works offline. You don’t need a Jupyter server or anything running in the background.

And I didn’t need to touch JavaScript at all.

Code + Output in One Place

One of the first things I tried in Quarto was a simple Python plot. Just a plt.plot(…) kind of thing.

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [10, 20, 25, 30])
plt.title("Simple Line Plot")
plt.show()

I wrote that in a .qmd file, ran quarto render command, and it worked. The code showed up on the page, and the plot was right underneath it, no notebook viewer, no downloading, no extra steps. Just open the site, scroll, and it’s all there.

Works Offline, Securely, and Anywhere

Before this, I used to share notebooks with people using Google Colab. Which works great unless you’re on a corporate network where Colab is blocked.

That’s what I like about Quarto: it renders everything ahead of time. Like, fully. The plots, the tables, the output — it’s all baked into the page. So the person reading it doesn’t need Python installed. Or Jupyter. Or an internet connection, honestly.

You just open the page and read.

This made a huge difference when I wanted to share stuff with people who aren’t super technical or who just want to glance at what I did without installing anything.

Simple Workflow

I write in .qmd (Quarto Markdown), which feels just like writing a blog post, think of them as Markdown files with superpowers. It’s basically regular Markdown, but with code blocks that actually do things.

I write some text.

I add a code chunk (like {python} or {r}).

Maybe toss in an image or two.

Then I run quarto render and it builds the whole site for me. All the code runs, the plots get saved, and everything gets wrapped up into a nice clean page I can open in a browser or upload online. (Realistically, I run quarto preview a couple dozen times to check what happens. But that’s just me.)

How I Built My Site (Step-by-Step)

Here’s a quick breakdown of what I did

Step 1: Installing Quarto

First, I downloaded Quarto from the official site. To write my files, I used Visual Studio Code — but honestly, any text editor would work. If you like editing things directly on GitHub, you could probably get by that way too.

Step 2: Creating the website

In my terminal, I ran quarto create-project my-site --type website. That created a whole folder with a working website scaffold — homepage, config file, everything. I opened index.qmd, added a few lines of Markdown, hit quarto render… and suddenly I had a homepage.

My project structure

Here’s how my folder looks now after a little tinkering:

📁 my-site/
├── index.qmd        # homepage
├── about.qmd        # second page
├── _quarto.yml      # site settings
├── styles.css       # optional custom styling
├── projects/        # my project pages
├── images/          # charts, screenshots, etc.
└── _site/           # auto-generated output

Don’t worry about the _site/ folder — Quarto makes it for you when you render. It’s what you’ll publish.

Step 3: Customizing it a bit

I edited _quarto.yml to update the site title and navigation bar. It looks like this:

project:
  type: website

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

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

This controls what links show up in the navigation bar, which theme I’m using, and which CSS file I want to apply. Simple stuff, but very satisfying.

Here’s how it looks with the default theme:

Quarto also supports several built-in themes like cosmo, flatly, journal, and more. You can easily swap them in the YAML file to see which one fits your style best.

You’ll find the full list of built-in themes (with previews) in the Quarto Themes documentation.

Step 4: Adding code, images, and more

I started adding .qmd pages like blog posts — a mix of text and code.

Code chunks are formatted like this:

Here’s a real example from one of my Quarto pages:

Below: I wrote this Python code to visualize Medium article stats, and Quarto rendered both the code block and the plot in one go.

I wanted to add images, but decided against it. Still, it’s just like Markdown:

![My Plot](images/plot.png)

And Quarto took care of the rest. The code runs, the plot shows up, the formatting looks nice. No copy-pasting outputs or screenshots.

Step 5: Getting a preview and publishing

To preview the site locally, I just ran:

quarto preview

To build for real:

quarto render

After that, I pushed everything to GitHub and published with GitHub Pages. You could also use Netlify or Vercel if you prefer. No backend needed — it’s all static HTML.

Step 6: Putting it on GitHub

Once the site is working locally and it has been rendered (quarto render), the next step is to actually get it on the web. For that, I used GitHub because it’s free, fast, and works great with Quarto.

Here’s how I did it.

Prerequisites

Before pushing the site I needed:

• A GitHub account
• Git installed on my computer
• Project already tracked with Git: git init was done earlier
• The project already on GitHub

If your site’s already connected to a GitHub repo, skip to the push section below.

Creating a GitHub repo

Here's how I created the repository:

1. Went to GitHub.com
2. Clicked “New repository”
3. Named it something like my-site
4. Left everything else as-is — no README, no .gitignore (Quarto had already made those files for me)
5. Clicked Create repository

After that, GitHub showed me a bunch of commands to hook up my local folder to the new repo.

git remote add origin https://github.com/yourusername/your-repo-name.git
git branch -M main

Pushing the site files

Once the project was ready and the remote was set, I just pushed everything:

git add .
git commit -m "Update site content"
git push origin main

That put my latest changes on GitHub. Now it existed online. But it took one last step.

Publishing with GitHub Pages

This part was surprisingly simple.

Since I was using Quarto’s built-in support for GitHub Pages (highly recommend), I just made sure my _quarto.yml had this in it:

project:
  type: website
  output-dir: _site

publish:
  provider: gh-pages

Then, in the terminal, I ran quarto publish gh-pages. And just like that, the site went live. (I haven’t set up a custom domain, but that can be done later if I change my mind.)

What I figured out

• I only need to run quarto publish gh-pages when I actually want to deploy the site - like after big edits or updates.
• I can preview locally anytime with quarto preview. That doesn’t touch GitHub at all.
• The _site/ folder is where Quarto builds the actual website files. I don’t mess with that manually.

Custom Styles (Optional)

Out of the box, Quarto looks great. But I wanted something that felt more “me.” So I added a styles.css file with some custom fonts, colors, and a light/dark mode toggle.

What I changed:

• Switched the font to something more monospace-y
• Gave the site a warm background
• Styled code blocks and headings
• Added a light/dark theme toggle just because I could

Here’s a tiny snippet of what I used:

:root {
  --bg: #FDF6E3;
  --text: #4B4B4B;
}

body {
  font-family: Menlo, Consolas, 'Liberation Mono', monospace;
  background-color: var(--bg);
  color: var(--text);
  max-width: 720px;
  margin: 4rem auto;
  padding: 0 1rem;
}

That's probably not the most effective way to do it, but I was quite happy to play around.

I linked the CSS file in _quarto.yml like this:

format:
  html:
    css: styles.css

One More Thing: Going Beyond Themes

If I’m just tweaking fonts, colors, or spacing, doing it in styles.css is super easy with Quarto. But to go further, like changing the page layout, moving the nav, or adding a custom footer, I needed a custom HTML template.

I didn’t need this for basic styling, just when I wanted full control over how the site was structured. For example, I wanted to drop a home block right in the middle of the page and play around with the navigation. Doing it this way gave me way more creative freedom.

Final Thoughts

I’m not a developer. I don’t know frontend frameworks. I didn’t plan some perfect site with a big launch. But with Quarto, I was able to build something simple, functional, and mine. It lets me share my code snippets or my plots all in one place. And I didn’t have to fight with HTML or copy-paste screenshots from notebooks.

I’m not saying my site is amazing. It’s very much a work in progress. But it’s out there. It works, and it's enough for now.

Also: it’s just a tiny step away from how I normally take notes in Obsidian. That made it feel familiar, like I wasn’t learning a whole new system, just building on something I already used.

If you want to share your work without diving into full-on web dev, Quarto is a surprisingly good place to start.

Let me know if you’ve built something similar! I’m still learning and always curious how other people do it.

Resources

Quarto Documentation
Markdown Guide