Build a Website with Quarto
Learning goals
- I can distinguish Quarto source files, configuration, assets, and rendered output.
- I can write Markdown and YAML, use relative links, and add accessible images.
- I can configure navigation, search, and a sortable, filterable project listing.
- I can render, test, troubleshoot, and commit a small site.
Why this is useful
Quarto turns readable plain-text source into a consistent website. It can combine engineering explanations, equations, code, graphs, and project evidence without hand-editing HTML.
What you will make
Download and extract the TEJ Quarto portfolio starter. You will add one project, one category, an accessible image, and a tested relative link. This teaching website is a larger Quarto example; your project stays intentionally small.
Before you start
- Complete Git: Save the History of Your Work.
- Install Quarto on an unrestricted computer and run
quarto checkandgit --version. - Read the starter
README.md. - Do not place private student information, credentials, classroom codes, or restricted files in the project.
JupyterLite cannot render Quarto websites. Use a local or teacher-authorized hosted environment with the Quarto CLI.
1. Learn the source structure
quarto-portfolio-starter/
├── _quarto.yml # project and website configuration
├── index.qmd # home page source
├── about.qmd # about page source
├── projects/ # listing page and project pages
├── blog/ # optional posts and listing
├── assets/ # images and downloadable evidence
├── styles.css # small visual adjustments
└── _site/ # generated output; do not edit
A relative link starts from the file containing the link. From projects/circuit-analysis.qmd, ../assets/circuit-project.svg moves up from projects/, then into assets/.
2. Write Markdown
# Page title
## Section heading
Write a paragraph with **strong text**, *emphasis*, and a [useful link](https://quarto.org/).
- Use a list for related items.
- Keep units beside measured values.
Use descriptive link text. Alt text should state what a reader needs to notice, not repeat the filename.
3. Edit YAML safely
YAML front matter sits between --- lines at the top of a page:
---
title: "Motor Current Test"
description: "Compare predicted and measured current during a load test."
date: 2026-01-20
categories: [electronics, motors, measurement]
image: ../assets/motor-test.svg
image-alt: "Current rises as the motor load increases across four measured points."
---Indent with spaces, keep list items aligned, and quote text containing punctuation when unsure. A render error that names a line near the page top often indicates malformed YAML.
4. Configure the website
_quarto.yml sets project-wide behaviour. The starter uses a navbar, local full-text search, a Cosmo theme, shared CSS, a footer, and _site output.
website:
navbar:
left:
- href: index.qmd
text: Home
- href: projects/index.qmd
text: Projects
search:
location: navbar
type: overlayUse the official navigation guide if you need a sidebar for a larger site. Do not add a sidebar merely to imitate this course website.
Change the theme through the documented format.html.theme option. Keep readable contrast, visible keyboard focus, responsive layout, and consistent headings. Test at a narrow window width before adding custom CSS.
5. Add a project listing
The starter’s projects/index.qmd uses Quarto’s native listing:
listing:
contents: "*.qmd"
type: grid
grid-columns: 2
sort: "date desc"
sort-ui: [date, title]
filter-ui: [title, description, categories]
categories: trueEach project contributes its title, description, date, categories, and image through YAML. Quarto builds the responsive card grid, filter box, category controls, and sort controls. No custom JavaScript is required.
To add a category, add a term to one project’s categories list and render. To change default order, change sort using the official listing documentation.
6. Use the optional blog
The blog/ folder demonstrates dated posts and categories. Add a post by copying a file in blog/posts/, changing its metadata, and writing the note. To remove the blog, remove its navbar entry, delete the folder, render, and verify navigation and search. The starter README records the same procedure.
7. Preview, render, and commit
quarto previewPreview after one small change. Stop the preview with Ctrl+C. Then build the complete static site:
quarto renderTest the home page, project grid, category filter, sort control, search, images, and every changed link. Inspect the terminal for warnings.
git status
git diff
git add _quarto.yml index.qmd about.qmd projects blog assets styles.css README.md .gitignore
git diff --staged
git commit -m "Add tested engineering portfolio project"Adjust the file list to match your intended changes. Do not add _site, .quarto, secrets, or private evidence.
The problem
Your new project does not appear correctly: its image is broken, its category is missing, or the render stops.
The essential skill: use the first specific error, inspect the named source, make one change, and render again.
The challenge: add one project and category, change the project ordering, repair one broken image and relative link, and explain how you found the correct Quarto option.
The stumbling block: YAML indentation and relative paths can look plausible while pointing to a different structure than the rendered site expects.
The investigation: search the official Quarto website guide, listing guide, and search guide using the exact option or error text.
Separate the failure: configuration, page metadata, file path, or page content.
Search for Quarto listing sort-ui filter-ui categories or the exact YAML key named by the error.
Validate YAML spacing, confirm filename capitalization, then count folder levels from the page containing the relative link.
Check your work
quarto rendercompletes without an unexplained warning.- Search finds text from the new project.
- The listing filters by its new category and sorts by the selected field.
- Images load at desktop and narrow widths and have useful alt text.
- Internal links work from the rendered site.
git statusshows only intended source files.
Save and submit
Keep the complete source project. Submit a teacher-approved ZIP or repository plus a screenshot of the local rendered result and git log --oneline. Publishing is optional; if assigned, continue to Publish Your Quarto Site with GitHub Pages.
Reflection
What was the first useful error or observation? Which documentation page or search terms led to the fix, and what test proved it?
Summary
You can now build and verify a small technical website from maintainable source. Use Build a Technical Portfolio to decide what engineering evidence belongs in each project.