Nested Quarto Website

Quarto projects provide an easy way to build static websites. But can we take it a step further—embedding one Quarto project within another, Inception-style?

Quarto
Author

Guillaume Gilles

Published

March 23, 2025

Quarto projects are directories designed to make publishing collections of documents easy, whether as a blog or a full website. They can also be used to create books and manuscripts in both print formats (PDF and MS Word) and online formats (HTML and ePub). For example, Quarto websites allow for shared navigation, consistent visual styling, customizable rendering options, and dynamic output using Python, R, Julia, and Observable.

How do Quarto projects work?

At the root of your directory, a YAML file, _quarto.yml, defines metadata that is shared across multiple documents. Any document rendered within the project directory automatically inherits this metadata. The default _quarto.yml file for creating a website look like this:

project:
  type: website

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

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

With these basic metadata, Quarto will produce an elegant website, with a navigation bar shared across multiple documents, such as the website’s home page, index.qmd, and an about page, about.qmd.

One Website to Rule Them All: A Quarto Dilemma

I love Quarto simplicity and versatility so much that I use it everywhere. My website, teaching materials, blog posts, and projects are all built with Quarto. For a coherent user experience between these different projects, my setup ensures that everything shares the same navigation bar, footer, and overall graphical identity while allowing seamless access to my home and about pages from any webpage.

The goals of this workflow are:

  1. Hosted directly from your GitHub repository, thanks to GitHub Pages
  2. Standalone GitHub repository with GitHub Pages enabled so they are independantly accessible.
  3. Finally, a personnal website as a central hub for all my online contents.

In order to achieve this goal, /home/guillaume/website/ directory on my local machine look like this (edited for clarity):

.
├── _quarto.yml                             # Root YAML configuration file for the Quarto project
├── blog/                                   # Directory for blog posts
├── projects/                               # Directory containing various projects
│   ├── machine-learning/                   # Machine Learning project
│   │   ├── _quarto.yml                     # Quarto configuration specific to this project
│   │   ├── …                               # Other project files
├── teaching/                               # Directory storing subdirectories for different courses
│   ├── data-description/                   # Data Description course
│   │   ├── _quarto.yml                     # Quarto configuration for this course
│   │   ├── …                               # Other course files
│   ├── management-information-system/      # Management Information System course
│   │   ├── _quarto.yml                     # Quarto configuration for this course
│   │   ├── …                               # Other course files
└── index.md                                # Website's home page

As you can see, it contains a _quarto.yml at the root level for my website defining

several subdirectorires, each with its own independent _quarto.yml metadata file. Since a Quarto project requires a single _quarto.yml file at the root of the directory, having multiple _quarto.yml files at different levels causes conflicts, making the directory structure unworkable.

To host all my Quarto projects within my personal website, I needed to find a workaround.

Prevent Rendering of Subdirectory Projects

The first step is to prevent subdirectories from being rendered. Fortunately, the Quarto developers have implemented a simple yet effective feature: any file or directory prefixed with _ is ignored during the rendering stage of the quarto render command.

.
├── _quarto.yml                             # Root YAML configuration file for the Quarto project
├── blog/                                   # Directory for blog posts
├── projects/                               # Directory containing various projects
│   ├── _machine-learning/                  # Machine Learning project
│   │   ├── _quarto.yml                     # Quarto configuration specific to this project
│   │   ├── …                               # Other project files
├── teaching/                               # Directory storing subdirectories for different courses
│   ├── _data-description/                  # Data Description course
│   │   ├── _quarto.yml                     # Quarto configuration for this course
│   │   ├── …                               # Other course files
│   ├── _management-information-system/     # Management Information System course
│   │   ├── _quarto.yml                     # Quarto configuration for this course
│   │   ├── …                               # Other course files
└── index.md                                # Website's home page

Rendering independant subdirectories

In my example, _machine-learning/ or _management-information-system/ are independant projects with multiple files and their own metadata YAML file. To ensure a coherent user experience inside my website, I needed to make sure their metadata will match the directory structure they will be living after being rendered by Qaurto.

  1. Need to have navbar properties inside references. so only book + website :
  • website: https://quarto.org/docs/reference/projects/websites.html#navbar
  • book: https://quarto.org/docs/reference/projects/books.html#navbar
  1. render sub project 2.1 render entire website except subfolder https://quarto.org/docs/websites/index.html#render-targets _strategic-qsfsqdfqs

using teaching-listing.yml for listing properties inside teaching.qmd

Setps

  1. quarto render projects and teaching
  2. make sure _quarto.yml sub-projects information take into consideration the website docs directory hierarchy. ../../about.html jump 2 levels, from specific projects to teaching level, then to root level of website.
  # Navbar
  navbar:
    logo: ../../images/cat.png
    title: false
    right:
      - text: ABOUT
        href: ../../about.html
      - text: PROJECTS
        href: ../../projects.html
      - text: TEACHING
        href: ../../teaching.html
      - text: BLOG
        href: ../../blog.html
  1. quarto render website
  2. Moving each docs/ sub-projects into website’s docs/teaching or docs/projects directories (since each render of the website wipes out the docs/ directory).
  • rename appropriately from docs/ to description-donnees for example.

Automatation

  • R
  • scripts
    • build_website

Yes! Since Step #2 already processes the directories, we can remove the redundant loop in Step #3 and just copy the files.

Updated Shell Script (build_site.sh)

#!/bin/bash

# Exit on error
set -e

# Step 1: Render the Quarto project
echo "Rendering Quarto project..."
quarto render

# Step 2: Create one level of subdirectories inside docs/, removing `_`
echo "Creating directory structure in docs/..."
for dir in teaching projects; do
    find "$dir" -maxdepth 1 -type d | while read -r subdir; do
        # Remove leading `_` from directory names
        clean_subdir=$(echo "$subdir" | sed 's|/_|/|g' | sed 's|^_||')

        # Construct the corresponding directory inside docs/
        newdir="docs/$clean_subdir"
        mkdir -p "$newdir"
    done
done

# Step 3: Copy files from `teaching/*/docs/` and `projects/*/docs/` to `docs/teaching/*` and `docs/projects/*`
echo "Copying files..."
find teaching projects -maxdepth 2 -type d -name "docs" | while read -r source_dir; do
    # Determine the parent directory (e.g., teaching/_data-analysis/docs → teaching/_data-analysis)
    parent_dir=$(dirname "$source_dir")

    # Remove leading `_` from parent directory name
    clean_subdir=$(echo "$parent_dir" | sed 's|/_|/|g' | sed 's|^_||')

    # Define the target directory in `docs/`
    target_dir="docs/$clean_subdir"

    # Copy files if the source directory is not empty
    if [ -d "$source_dir" ]; then
        cp -r "$source_dir"/* "$target_dir"/ 2>/dev/null || true
        echo "Copied files from $source_dir to $target_dir"
    fi
done

echo "Build process completed successfully!"

How It Works

Creates directories inside docs/, removing _ from names.
Moves files from teaching/_data-analysis/docs/ → docs/teaching/data-analysis/.
Ensures no files are lost, and empty docs/ directories inside teaching/ and projects/ are ignored.

Key Fixes

✅ Removes redundant loops in Step #3 since Step #2 already creates the directory structure.
✅ Uses cp -r instead of mv to copy files instead of moving them.
✅ Uses find ... -maxdepth 2 -type d -name "docs" to locate all docs/ directories.
✅ Automatically maps teaching/_data-analysis/docs → docs/teaching/data-analysis/ while removing _.

Example

Before Running the Script

teaching/
  _data-analysis/
    docs/
      file1.html
      file2.pdf
  _statistics/
    docs/
      report.md
projects/
  _equity-post-HCT-survival-predictions/
    docs/
      analysis.csv

After Running the Script

docs/
  teaching/
    data-analysis/
      file1.html
      file2.pdf
    statistics/
      report.md
  projects/
    equity-post-HCT-survival-predictions/
      analysis.csv

✅ All files are copied instead of moved
✅ No redundant loops
✅ _ removed from directory names in docs/

Final Thoughts

This is now fully optimized and should work perfectly for your Quarto project! 🚀
Let me know if you need any tweaks. 😊

Complete explaining

You’re very welcome! 😊 I’m glad it’s working perfectly. Now, let’s go line by line and explain exactly what each part of the script does.

Full Script with Line-by-Line Explanation

#!/bin/bash
  • This tells the system to run the script using the Bash shell.
# Exit on error
set -e
  • set -e ensures that if any command fails, the script will immediately stop.
  • This prevents silent errors and makes debugging easier.

Step 1: Render the Quarto project

# Step 1: Render the Quarto project
echo "Rendering Quarto project..."
quarto render
  • Runs quarto render, which processes the Quarto files and generates the output inside the docs/ folder.
  • The echo command prints a message to inform the user.

Step 2: Create the necessary directory structure inside docs/

# Step 2: Create one level of subdirectories inside docs/, removing `_`
echo "Creating directory structure in docs/..."
  • Prints a message to indicate that the script is creating directories inside docs/.
for dir in teaching projects; do
  • Loops through two main folders:
    • teaching/
    • projects/
    find "$dir" -maxdepth 1 -type d | while read -r subdir; do
  • Uses find to locate all immediate subdirectories (ignoring files) inside teaching/ and projects/.
  • -maxdepth 1 ensures only the first-level directories are processed.
  • -type d filters for directories only.
  • The while read -r subdir; do loop iterates through each directory found.
        # Remove leading `_` from directory names
        clean_subdir=$(echo "$subdir" | sed 's|/_|/|g' | sed 's|^_||')
  • Uses sed (stream editor) to remove leading underscores (_) from directory names:
    • s|/_|/|g → replaces /_ with / (removes _ when it’s part of a path).
    • s|^_|| → removes _ if it’s at the start of the name.

For example:

teaching/_data-analysis → teaching/data-analysis
projects/_equity-post-HCT-survival-predictions → projects/equity-post-HCT-survival-predictions
        # Construct the corresponding directory inside docs/
        newdir="docs/$clean_subdir"
        mkdir -p "$newdir"
  • Creates a matching directory structure inside docs/, but without _.
  • mkdir -p ensures it only creates directories if they don’t already exist.

Step 3: Copy Files from /docs/ folders in teaching/ and projects/

# Step 3: Copy files from `teaching/*/docs/` and `projects/*/docs/` to the corresponding location in `docs/`
echo "Copying files..."
  • Prints a message to indicate that files are now being copied.
find teaching projects -maxdepth 2 -type d -name "docs" | while read -r source_dir; do
  • Uses find to locate all docs/ subdirectories inside teaching/ and projects/, up to two levels deep.
  • -maxdepth 2 ensures it finds docs/ only inside first-level subdirectories (e.g., teaching/_data-analysis/docs/).
  • -type d -name "docs" ensures that only directories named docs are selected.
  • while read -r source_dir; do loops over each docs/ folder found.
    # Determine the parent directory (e.g., teaching/_data-analysis/docs → teaching/_data-analysis)
    parent_dir=$(dirname "$source_dir")
  • Gets the parent directory of docs/, so we know where the files originally belong.

    • Example:

      teaching/_data-analysis/docs → teaching/_data-analysis
    # Remove leading `_` from parent directory name
    clean_subdir=$(echo "$parent_dir" | sed 's|/_|/|g' | sed 's|^_||')

  • Removes _ from the parent directory name, just like in Step 2.

  • Example transformation:

    teaching/_data-analysis → teaching/data-analysis
    # Define the target directory in `docs/`
    target_dir="docs/$clean_subdir"
  • Defines where the files should be copied inside docs/.
    # Copy files if the source directory is not empty
    if [ -d "$source_dir" ]; then
  • Checks if docs/ exists before attempting to copy files.
        cp -r "$source_dir"/* "$target_dir"/ 2>/dev/null || true
  • Copies all files from the source docs/ folder into the corresponding docs/ directory.
  • cp -r ensures it copies all files and subdirectories.
  • 2>/dev/null || true:
    • Redirects errors (e.g., if docs/ is empty) to prevent script failure.
    • The || true ensures the script continues running even if no files exist.
        echo "Copied files from $source_dir to $target_dir"
  • Prints a confirmation message each time files are copied.

Final Step: Script Completion Message

done
done
  • Closes both while and for loops.
echo "Build process completed successfully!"
  • Prints a final message indicating the script finished successfully.

Summary of What the Script Does

  1. Renders the Quarto project (quarto render).
  2. Creates directories inside docs/, ensuring that _ is removed from names.
  3. Finds all docs/ folders inside teaching/ and projects/.
  4. Copies files from those docs/ folders into the correct docs/ directory.
  5. Ensures the entire process runs smoothly, even if some folders are empty.

Example: Before & After Running the Script

Before

teaching/
  _data-analysis/
    docs/
      file1.html
      file2.pdf
  _statistics/
    docs/
      report.md
projects/
  _equity-post-HCT-survival-predictions/
    docs/
      analysis.csv

After

docs/
  teaching/
    data-analysis/
      file1.html
      file2.pdf
    statistics/
      report.md
  projects/
    equity-post-HCT-survival-predictions/
      analysis.csv

✅ Files are copied instead of moved
✅ Underscores _ are removed from directory names
✅ Directory structure is maintained

Final Thoughts

This script is now fully optimized, efficient, and robust. 🚀
If you ever need additional tweaks, let me know! 😊

Back to top