{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Introduction to Quarto\n",
        "\n",
        "One plain-text source, many polished outputs\n",
        "\n",
        "# Introduction to Quarto\n",
        "\n",
        "Resource: [quarto-article-example](quarto-article-example.zip)\n",
        "\n",
        "**Goal for today:** by the end of class you can create a Quarto project\n",
        "from VS Code, render it, and know exactly *where* to put a setting so it\n",
        "applies to the right things.\n",
        "\n",
        "| Part | Topic                                | Time |\n",
        "|------|--------------------------------------|------|\n",
        "| 1    | Why Quarto?                          |      |\n",
        "| 2    | From Markdown to Quarto              |      |\n",
        "| 3    | Anatomy of a `.qmd` file + rendering |      |\n",
        "| 4    | YAML crash course                    |      |\n",
        "| 4b   | The most-used YAML options           |      |\n",
        "| 5    | The four YAML levels                 |      |\n",
        "| 6    | Projects: websites, blogs, books     |      |\n",
        "| 7    | Wrap-up and cheat sheet              |      |\n",
        "\n",
        "**Before we start**\n",
        "\n",
        "-   You need two things installed (see the setup guide):\n",
        "    -   the **Quarto CLI** (the actual program)\n",
        "    -   the **Quarto extension** for VS Code (the editor integration)\n",
        "-   Follow along in VS Code; run every cell as we go"
      ],
      "id": "82324ef6-f5b7-458d-a068-c16d2e58e69e"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Sanity check: is Quarto installed and on your PATH?\n",
        "!quarto --version"
      ],
      "id": "cell-02"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Part 1: Why Quarto?\n",
        "\n",
        "**What it is**\n",
        "\n",
        "-   An open-source **publishing system** from Posit (the company behind\n",
        "    RStudio)\n",
        "-   You write **plain text + code**; Quarto produces **polished\n",
        "    documents**\n",
        "-   Think of it as a *compiler for documents*: source file in, finished\n",
        "    product out\n",
        "\n",
        "**The pitch: why people love it**\n",
        "\n",
        "-   **One source, many outputs**: the same file becomes an HTML page, a\n",
        "    PDF, a Word doc, or a slide deck\n",
        "-   **Code and narrative live together**: figures and tables are\n",
        "    produced *by the code*, so they never go stale (no more copy-pasting\n",
        "    plots into Word)\n",
        "-   **Language agnostic**: Python, R, Julia, and Observable JS; it also\n",
        "    renders Jupyter notebooks directly\n",
        "-   **Plain text**: readable without special software, and plays\n",
        "    perfectly with Git\n",
        "-   **Reproducible**: anyone with your files can re-render and get the\n",
        "    same report\n",
        "\n",
        "**Who uses it, and for what**\n",
        "\n",
        "| Who | What they make |\n",
        "|------------------------------------|------------------------------------|\n",
        "| Data scientists | Analysis reports, dashboards, internal docs |\n",
        "| Researchers | Papers, lab websites, reproducible manuscripts |\n",
        "| Instructors | Course websites, lecture slides, notes (including this course) |\n",
        "| Authors | Free online books (e.g. *R for Data Science*, 2nd ed.) |\n",
        "| Students (you!) | A **portfolio website** showing your projects to employers |\n",
        "\n",
        "## Part 2: From Markdown to Quarto\n",
        "\n",
        "**Markdown refresher**: a lightweight way to format text with a few\n",
        "symbols.\n",
        "\n",
        "| You type                               | You get            |\n",
        "|----------------------------------------|--------------------|\n",
        "| `# Heading 1`, `## Heading 2`          | Section headings   |\n",
        "| `**bold**`, `*italic*`                 | **bold**, *italic* |\n",
        "| `- item`                               | Bulleted list      |\n",
        "| `1. item`                              | Numbered list      |\n",
        "| `[Georgetown](https://georgetown.edu)` | A link             |\n",
        "| `![caption](figs/plot.png)`            | An image           |\n",
        "| `` `x = 5` ``                          | Inline code        |\n",
        "| `$E = mc^2$`                           | Math: $E = mc^2$   |\n",
        "\n",
        "**The limitation of plain Markdown**\n",
        "\n",
        "-   It is **static**: it cannot run code\n",
        "-   Limited control over layout, output format, and styling\n",
        "\n",
        "**Quarto Markdown (`.qmd`) = Markdown + two additions**\n",
        "\n",
        "1.  A **YAML header** at the top (settings: title, author, output\n",
        "    format, …)\n",
        "2.  **Executable code cells** whose results are inserted into the\n",
        "    document\n",
        "\n",
        "> If you know Markdown, you already know about 80% of Quarto. Every\n",
        "> Markdown cell in this notebook is valid Quarto.\n",
        "\n",
        "### What happens when you click “Render”\n",
        "\n",
        "    report.qmd ──► Jupyter (Python) or knitr (R) ──► report.md ──► Pandoc ──► report.html\n",
        "                      runs the code, inserts           plain          converts     report.pdf\n",
        "                      outputs into the text            Markdown       formats      report.docx\n",
        "\n",
        "-   Step 1: an **engine** runs your code and pastes the results into\n",
        "    ordinary Markdown\n",
        "-   Step 2: **Pandoc** (a universal document converter) turns that\n",
        "    Markdown into the format you asked for\n",
        "-   You never touch the intermediate `.md`; Quarto handles both steps\n",
        "\n",
        "### A taste of Quarto-only Markdown\n",
        "\n",
        "Quarto adds a few extras on top of standard Markdown. One example, a\n",
        "**callout box**:\n",
        "\n",
        "``` markdown\n",
        "::: {.callout-tip}\n",
        "## Pro tip\n",
        "Render early and often. Small errors are easy to find; big ones are not.\n",
        ":::\n",
        "```\n",
        "\n",
        "Others you will meet later: citations (`[@smith2020]`), cross-references\n",
        "(`@fig-scatter`), multi-column layouts.\n",
        "\n",
        "## Part 3: Anatomy of a `.qmd` file + rendering\n",
        "\n",
        "A complete, minimal Quarto document has **three parts**:\n",
        "\n",
        "```` markdown\n",
        "---\n",
        "title: \"My First Report\"          # <── 1. YAML header (between the --- lines)\n",
        "author: \"Hoya Saxa\"\n",
        "format: html\n",
        "---\n",
        "\n",
        "## Introduction                   # <── 2. Markdown body (just normal Markdown)\n",
        "\n",
        "This report looks at **penguins**.\n",
        "\n",
        "```{python}                       # <── 3. Executable code cell\n",
        "#| echo: false\n",
        "import math\n",
        "print(math.pi)\n",
        "```\n",
        "````\n",
        "\n",
        "**Watch the braces**\n",
        "\n",
        "-   ```` ```{python} ```` (with braces) means **run this code**\n",
        "-   ```` ```python ```` (no braces) means **just display this code**, do\n",
        "    not run it\n",
        "\n",
        "### How to render\n",
        "\n",
        "| Where | Action | What it does |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| VS Code | **Preview** button, or `Ctrl+Shift+K` (`Cmd+Shift+K` on Mac) | Renders and opens a live preview that updates every time you save |\n",
        "| Terminal | `quarto preview report.qmd` | Same as above, from the command line |\n",
        "| Terminal | `quarto render report.qmd` | Renders once to the default format, no live preview |\n",
        "| Terminal | `quarto render report.qmd --to pdf` | Renders to a specific format |\n",
        "\n",
        "**Notes**\n",
        "\n",
        "-   `preview` is for *working*; `render` is for *producing the final\n",
        "    files*\n",
        "-   PDF output needs a LaTeX installation: run `quarto install tinytex`\n",
        "    once\n",
        "-   Jupyter notebooks work too: `quarto render notebook.ipynb`; the YAML\n",
        "    goes in a **raw cell at the very top** (scroll up: this notebook has\n",
        "    one)\n",
        "\n",
        "### Live demo: write and render a `.qmd`"
      ],
      "id": "e352aba4-d78e-4633-8373-08396e01ce82"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "%%writefile hello.qmd\n",
        "---\n",
        "title: \"Hello, Quarto\"\n",
        "author: \"Your Name\"\n",
        "format: html\n",
        "---\n",
        "\n",
        "## A tiny report\n",
        "\n",
        "Quarto ran the code below and inserted the result.\n",
        "\n",
        "```{python}\n",
        "squares = [n**2 for n in range(1, 6)]\n",
        "print(squares)\n",
        "```\n",
        "\n",
        "The sum of the first five squares is `{python} sum(squares)`."
      ],
      "id": "cell-08"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "!quarto render hello.qmd\n",
        "# Now open hello.html in your browser (or right-click > Open with Live Preview in VS Code)"
      ],
      "id": "cell-09"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "**Try it:** change `format: html` to `format: docx`, re-render, and open\n",
        "the Word file. Same source, different output.\n",
        "\n",
        "## Part 4: YAML crash course\n",
        "\n",
        "**YAML** (“YAML Ain’t Markup Language”) is a human-readable format for\n",
        "**settings**. Quarto uses it everywhere.\n",
        "\n",
        "**The rules**\n",
        "\n",
        "-   `key: value` (a **space after the colon** is required)\n",
        "-   **Nesting** is done with **indentation**: use spaces (2 is\n",
        "    standard), **never tabs**\n",
        "-   **Lists** use a dash: `- item`\n",
        "-   Booleans: `true` / `false`\n",
        "-   Put text containing special characters (`:`, `#`, `@`) in **quotes**\n",
        "\n",
        "``` yaml\n",
        "title: \"Analysis: Part 1\"     # quoted because the title contains a colon\n",
        "author: \"Ada Lovelace\"\n",
        "date: today\n",
        "format:                       # a key whose value is a nested block\n",
        "  html:\n",
        "    toc: true                 # indented 4 spaces: belongs to html\n",
        "    code-fold: true\n",
        "  pdf: default\n",
        "bibliography: refs.bib\n",
        "categories:                   # a list\n",
        "  - python\n",
        "  - visualization\n",
        "```\n",
        "\n",
        "**Most common YAML errors:** no space after a colon (`title:\"Report\"`),\n",
        "inconsistent indentation or tabs, and an unquoted colon inside a value\n",
        "(`title: Part 1: Intro`).\n",
        "\n",
        "**Tip:** in VS Code the Quarto extension **autocompletes** YAML options\n",
        "(`Ctrl+Space`) and underlines invalid ones. Let it help you.\n",
        "\n",
        "## Part 4b: The most-used YAML options\n",
        "\n",
        "Quarto has hundreds of options. You will use about fifteen of them\n",
        "almost every day.\n",
        "\n",
        "**Document info** (top level)\n",
        "\n",
        "| Option | Example | Effect |\n",
        "|----|----|----|\n",
        "| `title`, `subtitle` | `title: \"Lab 3\"` | Title block at the top |\n",
        "| `author` | `author: \"Ada Lovelace\"` | Byline (can be a list) |\n",
        "| `date` | `date: today` | Date; `today` fills in the render date |\n",
        "\n",
        "**Format and layout** (under `format: html:` and friends)\n",
        "\n",
        "| Option | Example | Effect |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| `format` | `format: html` | Output type: `html`, `pdf`, `docx`, `revealjs` |\n",
        "| `toc` | `toc: true` | Table of contents from your headings |\n",
        "| `toc-depth` | `toc-depth: 2` | How many heading levels the TOC shows |\n",
        "| `number-sections` | `number-sections: true` | Numbers headings 1, 1.1, 1.2, … |\n",
        "| `theme` | `theme: cosmo` | Visual theme (try `flatly`, `darkly`, `lux`) |\n",
        "| `embed-resources` | `embed-resources: true` | Packs everything into one shareable `.html` file |\n",
        "\n",
        "**Code display** (HTML only, under `format: html:`)\n",
        "\n",
        "| Option | Example | Effect |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| `code-fold` | `code-fold: true` | Code hidden behind a clickable “Code” toggle |\n",
        "| `code-tools` | `code-tools: true` | Menu to show/hide all code and view the source |\n",
        "| `code-line-numbers` | `code-line-numbers: true` | Line numbers on code blocks |\n",
        "\n",
        "**Execution** (under `execute:`)\n",
        "\n",
        "| Option | Example | Effect |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| `echo` | `echo: false` | Hide all code, keep outputs (reports for non-coders) |\n",
        "| `eval` | `eval: false` | Show code but do not run any of it |\n",
        "| `warning` | `warning: false` | Hide warning messages |\n",
        "| `error` | `error: true` | Show errors in the output instead of stopping the render |\n",
        "| `freeze` | `freeze: auto` | Projects only: re-run code only when its source changed |\n",
        "\n",
        "**Figures** (top level, or per cell)\n",
        "\n",
        "| Option | Example | Effect |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| `fig-width`, `fig-height` | `fig-width: 6` | Default figure size in inches |\n",
        "| `fig-cap` | `fig-cap: \"Scores\"` | Caption (usually set per cell) |\n",
        "\n",
        "### Key idea: `execute:` sets defaults, cells override them\n",
        "\n",
        "-   The `execute:` block = **document-wide default behavior** for every\n",
        "    code cell\n",
        "-   A `#|` option in a cell = **an exception for that one cell**\n",
        "-   Same option name in both places: `execute: echo: false` in the\n",
        "    header, `#| echo: true` in one cell\n",
        "\n",
        "**`code-fold` vs `echo: false`: a common confusion**\n",
        "\n",
        "|                   | Reader can see the code?     |\n",
        "|-------------------|------------------------------|\n",
        "| `echo: false`     | No, it is gone from the page |\n",
        "| `code-fold: true` | Yes, one click away          |\n",
        "\n",
        "-   Report for a manager: `echo: false`\n",
        "-   Homework or a portfolio: `code-fold: true` (clean page, but your\n",
        "    work is visible)\n",
        "\n",
        "**`error: true`: your debugging friend**\n",
        "\n",
        "-   Default: one broken cell **stops the whole render**, and you get no\n",
        "    output at all\n",
        "-   With `error: true`: the render finishes and the error message\n",
        "    appears **in the page**, right where it happened\n",
        "-   Use it while drafting; turn it off for the final version so mistakes\n",
        "    do not slip through\n",
        "\n",
        "### Live demo: a typical header with these options"
      ],
      "id": "597d1802-3b82-4ff7-afcf-b36af44b7738"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "%%writefile options-demo.qmd\n",
        "---\n",
        "title: \"Options Demo\"\n",
        "author: \"Your Name\"\n",
        "date: today\n",
        "format:\n",
        "  html:\n",
        "    theme: flatly\n",
        "    toc: true\n",
        "    number-sections: true\n",
        "    code-fold: true\n",
        "    code-tools: true\n",
        "    embed-resources: true\n",
        "execute:\n",
        "  echo: true\n",
        "  warning: false\n",
        "  error: true\n",
        "---\n",
        "\n",
        "## Data\n",
        "\n",
        "```{python}\n",
        "scores = [72, 85, 90, 64, 88, 95, 78]\n",
        "print(\"Mean score:\", sum(scores) / len(scores))\n",
        "```\n",
        "\n",
        "## A hidden calculation\n",
        "\n",
        "```{python}\n",
        "#| echo: false\n",
        "print(\"Students above 80:\", sum(s > 80 for s in scores))\n",
        "```\n",
        "\n",
        "## A broken cell\n",
        "\n",
        "```{python}\n",
        "print(scores[100])   # deliberate IndexError\n",
        "```\n",
        "\n",
        "The render still finishes because of `error: true`."
      ],
      "id": "cell-14"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "!quarto render options-demo.qmd\n",
        "# Open options-demo.html: find the \"Code\" toggles, the TOC, the numbered sections, and the error message"
      ],
      "id": "cell-15"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "**Try it **\n",
        "\n",
        "1.  Change `error: true` to `error: false` and re-render: what happens?\n",
        "2.  Change `code-fold: true` to `false`: what changes on the page?\n",
        "3.  Change `theme: flatly` to `theme: darkly`\n",
        "\n",
        "## Part 5: The four YAML levels\n",
        "\n",
        "**This is the single most important idea of the day.**\n",
        "\n",
        "Quarto settings can be written at four levels. Each level covers a\n",
        "different **scope**:\n",
        "\n",
        "    PROJECT    _quarto.yml           applies to every file in the project\n",
        "     └─ METADATA  _metadata.yml      applies to every file in that folder (and its subfolders)\n",
        "         └─ FILE    YAML front matter   applies to one document\n",
        "             └─ CELL  #| options        applies to one code cell\n",
        "\n",
        "**The rule: settings cascade downward, and the closest (most specific)\n",
        "setting wins.**\n",
        "\n",
        "-   Like CSS, or like a company policy: company-wide rule \\< department\n",
        "    rule \\< your manager’s instruction for this one task\n",
        "-   Rule of thumb: **put a setting at the highest level where it is true\n",
        "    for everything below it**\n",
        "\n",
        "### Level 1: Project (`_quarto.yml`)\n",
        "\n",
        "-   **Where:** a file named exactly `_quarto.yml` in the project’s\n",
        "    **root folder**\n",
        "-   **Scope:** every document in the project\n",
        "-   **Bonus job:** its presence is what *makes* a folder a Quarto\n",
        "    project\n",
        "-   **Typical contents:** project type, site navigation, shared theme,\n",
        "    default author, execution defaults\n",
        "\n",
        "``` yaml\n",
        "project:\n",
        "  type: website\n",
        "  output-dir: _site\n",
        "\n",
        "author: \"Hoya Saxa\"\n",
        "\n",
        "format:\n",
        "  html:\n",
        "    theme: cosmo\n",
        "    toc: true\n",
        "\n",
        "execute:\n",
        "  echo: true\n",
        "```\n",
        "\n",
        "### Level 2: Metadata / directory (`_metadata.yml`)\n",
        "\n",
        "-   **Where:** a file named exactly `_metadata.yml` inside **any\n",
        "    subfolder** of a project\n",
        "-   **Scope:** every document in that folder and its subfolders\n",
        "-   **Same keys** as the file-level header (no `---` lines needed)\n",
        "-   **Typical use:** a `posts/` folder where every post shares settings\n",
        "\n",
        "``` yaml\n",
        "# posts/_metadata.yml\n",
        "author: \"Data Science Club\"\n",
        "categories:\n",
        "  - club-news\n",
        "title-block-banner: true\n",
        "```\n",
        "\n",
        "### Level 3: File / document (YAML front matter)\n",
        "\n",
        "-   **Where:** between the `---` lines at the top of a `.qmd` (or the\n",
        "    first raw cell of an `.ipynb`)\n",
        "-   **Scope:** this one document\n",
        "-   **Typical use:** title, date, and anything this file does\n",
        "    differently from the rest\n",
        "\n",
        "``` yaml\n",
        "---\n",
        "title: \"Lab 3 Results\"\n",
        "date: 2026-10-22\n",
        "format:\n",
        "  html:\n",
        "    code-fold: true\n",
        "execute:\n",
        "  warning: false\n",
        "---\n",
        "```\n",
        "\n",
        "### Level 4: Cell (`#|` options)\n",
        "\n",
        "-   **Where:** special comment lines at the **top of a code cell**,\n",
        "    starting with `#|` (hash pipe, then a space)\n",
        "-   **Scope:** this one cell only\n",
        "-   **Typical use:** hide this code, caption this figure, skip running\n",
        "    this cell\n",
        "\n",
        "```` markdown\n",
        "```{python}\n",
        "#| label: fig-scores\n",
        "#| fig-cap: \"Distribution of exam scores\"\n",
        "#| echo: false\n",
        "import matplotlib.pyplot as plt\n",
        "plt.hist([72, 85, 90, 64, 88, 95, 78]);\n",
        "```\n",
        "````\n",
        "\n",
        "**The cell options you will use 90% of the time**\n",
        "\n",
        "| Option            | Effect                                            |\n",
        "|-------------------|---------------------------------------------------|\n",
        "| `echo: false`     | Hide the code, show the output                    |\n",
        "| `eval: false`     | Show the code, do not run it                      |\n",
        "| `include: false`  | Run it, but show nothing (good for setup/imports) |\n",
        "| `output: false`   | Show code, hide output                            |\n",
        "| `warning: false`  | Hide warning messages                             |\n",
        "| `fig-cap: \"...\"`  | Figure caption                                    |\n",
        "| `label: fig-name` | Name for cross-referencing (`@fig-name`)          |\n",
        "| `code-fold: true` | Collapse code behind a “Code” toggle              |\n",
        "\n",
        "### Putting it together: predict the outcome\n",
        "\n",
        "Imagine this project layout:\n",
        "\n",
        "    my-project/\n",
        "    ├── _quarto.yml            author: \"Project Author\",  theme: cosmo,   toc: true,  echo: true\n",
        "    └── posts/\n",
        "        ├── _metadata.yml      author: \"Folder Author\",   theme: darkly\n",
        "        └── post.qmd           theme: flatly,  echo: false\n",
        "                                 cell A has  #| echo: true\n",
        "                                 cell B has no options\n",
        "\n",
        "**Before scrolling: for `post.qmd`, what are the author, the theme, the\n",
        "table of contents, and the code visibility of each cell?**"
      ],
      "id": "b025a189-8bca-4363-965c-8b5f4579cde1"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<details>"
      ],
      "id": "79f0ac55-5239-4f41-9a20-bfb74e8296ac"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<summary>"
      ],
      "id": "bcbef786-6195-450b-9b79-51651d83b7ef"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Click for the answer"
      ],
      "id": "79fb75fa-0fc1-4d20-9126-32232930f0a9"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</summary>"
      ],
      "id": "292e2781-ca21-49ef-ac38-a832719de8ad"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "| Setting     | Final value   | Decided at                        |\n",
        "|-------------|---------------|-----------------------------------|\n",
        "| `author`    | Folder Author | Metadata (beats project)          |\n",
        "| `theme`     | flatly        | File (beats metadata and project) |\n",
        "| `toc`       | true          | Project (nobody overrode it)      |\n",
        "| Cell A code | shown         | Cell (beats file)                 |\n",
        "| Cell B code | hidden        | File                              |\n",
        "\n",
        "Note that settings **merge**: the file changed `theme` but did not wipe\n",
        "out `toc` from the project."
      ],
      "id": "be23f87f-050c-4927-8c3a-ddf92e6c1b51"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</details>"
      ],
      "id": "bff06e6c-0990-45aa-8cd4-759b4ac7b5f5"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Live demo: build this exact project and check our prediction"
      ],
      "id": "e5e9ef93-d217-4b43-8cf0-a50de79ea504"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import os\n",
        "os.makedirs(\"cascade-demo/posts\", exist_ok=True)"
      ],
      "id": "cell-21"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "%%writefile cascade-demo/_quarto.yml\n",
        "project:\n",
        "  title: \"Cascade demo\"\n",
        "\n",
        "author: \"Project Author\"\n",
        "\n",
        "format:\n",
        "  html:\n",
        "    theme: cosmo\n",
        "    toc: true\n",
        "\n",
        "execute:\n",
        "  echo: true"
      ],
      "id": "cell-22"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "%%writefile cascade-demo/posts/_metadata.yml\n",
        "author: \"Folder Author\"\n",
        "format:\n",
        "  html:\n",
        "    theme: darkly"
      ],
      "id": "cell-23"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "%%writefile cascade-demo/posts/post.qmd\n",
        "---\n",
        "title: \"Who wins?\"\n",
        "format:\n",
        "  html:\n",
        "    theme: flatly\n",
        "execute:\n",
        "  echo: false\n",
        "---\n",
        "\n",
        "## Cell A\n",
        "\n",
        "```{python}\n",
        "#| echo: true\n",
        "print(\"Cell A: cell-level echo: true overrides the file's echo: false\")\n",
        "```\n",
        "\n",
        "## Cell B\n",
        "\n",
        "```{python}\n",
        "print(\"Cell B: follows the file-level setting, so its code is hidden\")\n",
        "```"
      ],
      "id": "cell-24"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "!quarto render cascade-demo\n",
        "# Open cascade-demo/posts/post.html: check the author, the theme, the TOC, and which code is visible"
      ],
      "id": "cell-25"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "**Try it :** delete the `theme: flatly` lines from `post.qmd` and\n",
        "re-render. Which theme do you get now, and why?\n",
        "\n",
        "## Part 6: Projects: websites, blogs, books\n",
        "\n",
        "**Why projects?**\n",
        "\n",
        "-   A single `.qmd` is great for one report\n",
        "-   Real work has **many files** that share settings, navigation, and\n",
        "    links between pages\n",
        "-   A **project** is simply a folder with a `_quarto.yml`; Quarto\n",
        "    renders all of it together\n",
        "\n",
        "**Project types**\n",
        "\n",
        "| Type | Use it for | Output folder |\n",
        "|------------------------|------------------------|------------------------|\n",
        "| Default | A collection of standalone documents with shared settings | next to the sources |\n",
        "| Website | Portfolio, course site, documentation | `_site/` |\n",
        "| Blog | A website with dated posts and an automatic listing page | `_site/` |\n",
        "| Book | Long-form content in ordered chapters (HTML + PDF) | `_book/` |\n",
        "| Manuscript | A scholarly article with linked notebooks | `_manuscript/` |\n",
        "\n",
        "### Creating an empty project shell from VS Code\n",
        "\n",
        "1.  Open VS Code\n",
        "2.  Open the **Command Palette**: `Ctrl+Shift+P` (`Cmd+Shift+P` on Mac)\n",
        "3.  Type **`Quarto: Create Project`** and press Enter\n",
        "4.  Pick a project type (e.g. **Website Project**)\n",
        "5.  Choose the **parent folder** where it should live, then type a\n",
        "    **name** for the new project folder\n",
        "6.  VS Code opens the new project, already populated with starter files\n",
        "\n",
        "**Equivalent terminal command** (handy to know, same result):\n",
        "\n",
        "``` bash\n",
        "quarto create project website my-site\n",
        "quarto create project book my-book\n",
        "```\n",
        "\n",
        "**Golden rule:** always open the **project root folder** in VS Code\n",
        "(File \\> Open Folder), and run `quarto` commands from that folder.\n",
        "\n",
        "### Website project: what you get\n",
        "\n",
        "    my-site/\n",
        "    ├── _quarto.yml     project settings + navigation bar\n",
        "    ├── index.qmd       the home page (index = \"front door\" of any website)\n",
        "    ├── about.qmd       a second page\n",
        "    └── styles.css      optional custom styling\n",
        "\n",
        "The generated `_quarto.yml` (yours may differ slightly by version):\n",
        "\n",
        "``` yaml\n",
        "project:\n",
        "  type: website\n",
        "\n",
        "website:\n",
        "  title: \"my-site\"\n",
        "  navbar:\n",
        "    left:\n",
        "      - href: index.qmd\n",
        "        text: Home\n",
        "      - about.qmd\n",
        "\n",
        "format:\n",
        "  html:\n",
        "    theme: cosmo\n",
        "    css: styles.css\n",
        "    toc: true\n",
        "```\n",
        "\n",
        "**Common workflow: add a page**\n",
        "\n",
        "1.  Create `projects.qmd` with a title in its YAML header\n",
        "2.  Add `- projects.qmd` under `navbar: left:` in `_quarto.yml`\n",
        "3.  Run `quarto preview` from the project folder; the new page appears\n",
        "    in the menu\n",
        "\n",
        "**What to deploy:** the `_site/` folder is a complete, self-contained\n",
        "website (plain HTML/CSS/JS). Copy it to any web host: GitHub Pages,\n",
        "Quarto Pub (`quarto publish`), Netlify, or your GU Domains space.\n",
        "\n",
        "### Blog project: the `_metadata.yml` level in the wild\n",
        "\n",
        "    my-blog/\n",
        "    ├── _quarto.yml\n",
        "    ├── index.qmd           auto-generated listing of all posts\n",
        "    ├── about.qmd\n",
        "    └── posts/\n",
        "        ├── _metadata.yml   shared settings for every post\n",
        "        ├── welcome/\n",
        "        │   └── index.qmd\n",
        "        └── post-with-code/\n",
        "            └── index.qmd\n",
        "\n",
        "The starter `posts/_metadata.yml` looks like this:\n",
        "\n",
        "``` yaml\n",
        "# options specified here will apply to all posts in this folder\n",
        "freeze: true               # do not re-run old posts' code on every render\n",
        "title-block-banner: true   # banner-style title on every post\n",
        "```\n",
        "\n",
        "-   New post = new folder under `posts/` with an `index.qmd` inside; it\n",
        "    shows up in the listing automatically\n",
        "\n",
        "### Book project: what you get\n",
        "\n",
        "    my-book/\n",
        "    ├── _quarto.yml\n",
        "    ├── index.qmd        preface (the book's front page)\n",
        "    ├── intro.qmd        chapter 1\n",
        "    ├── summary.qmd      chapter 2\n",
        "    ├── references.qmd   bibliography page\n",
        "    ├── references.bib   citation database (BibTeX)\n",
        "    └── cover.png\n",
        "\n",
        "The key part of `_quarto.yml`:\n",
        "\n",
        "``` yaml\n",
        "project:\n",
        "  type: book\n",
        "\n",
        "book:\n",
        "  title: \"my-book\"\n",
        "  author: \"Jane Doe\"\n",
        "  chapters:\n",
        "    - index.qmd\n",
        "    - intro.qmd\n",
        "    - summary.qmd\n",
        "    - references.qmd\n",
        "\n",
        "bibliography: references.bib\n",
        "\n",
        "format:\n",
        "  html:\n",
        "    theme: cosmo\n",
        "  pdf:\n",
        "    documentclass: scrreprt\n",
        "```\n",
        "\n",
        "-   The **`chapters:` list sets the order** of the book; a file not\n",
        "    listed is not in the book\n",
        "-   Add a chapter: create `methods.qmd`, add it to the list\n",
        "-   One source, two products: an HTML book **and** a PDF book from the\n",
        "    same files\n",
        "\n",
        "### Common project pitfalls\n",
        "\n",
        "-   Running `quarto render` from the **wrong folder** (must be the\n",
        "    project root, or pass the path)\n",
        "-   **Editing files inside `_site/` or `_book/`**: they are regenerated\n",
        "    on every render, so your edits vanish. Edit the `.qmd` sources\n",
        "    instead\n",
        "-   Creating a new page but **forgetting to add it** to the navbar or\n",
        "    `chapters:` list\n",
        "-   Misspelling `_quarto.yml` or `_metadata.yml` (the leading underscore\n",
        "    matters)\n",
        "\n",
        "## Part 7: Wrap-up\n",
        "\n",
        "**Big ideas**\n",
        "\n",
        "-   Quarto = **Markdown + YAML + executable code**, rendered by an\n",
        "    engine and Pandoc\n",
        "-   A small set of options does most of the work: `toc`, `theme`,\n",
        "    `code-fold`, and the `execute:` block (`echo`, `eval`, `warning`,\n",
        "    `error`)\n",
        "-   **One source, many outputs**: HTML, PDF, Word, slides, websites,\n",
        "    books\n",
        "-   **Four YAML levels**, closest wins: project `_quarto.yml` \\>\n",
        "    metadata `_metadata.yml` \\> file front matter \\> cell `#|`\n",
        "-   A **project** is a folder with `_quarto.yml`; create one from VS\n",
        "    Code with **Quarto: Create Project**\n",
        "\n",
        "**Cheat sheet**\n",
        "\n",
        "| Task                 | How                                              |\n",
        "|----------------------|--------------------------------------------------|\n",
        "| Check install        | `quarto check`                                   |\n",
        "| Live preview         | VS Code Preview button, or `quarto preview`      |\n",
        "| Render one file      | `quarto render file.qmd`                         |\n",
        "| Render to a format   | `quarto render file.qmd --to pdf`                |\n",
        "| Render whole project | `quarto render` (from project root)              |\n",
        "| New project          | Command Palette \\> `Quarto: Create Project`      |\n",
        "| Publish              | `quarto publish`, or copy `_site/` to a web host |\n",
        "\n",
        "| Level    | File / syntax      | Scope                |\n",
        "|----------|--------------------|----------------------|\n",
        "| Project  | `_quarto.yml`      | whole project        |\n",
        "| Metadata | `_metadata.yml`    | one folder and below |\n",
        "| File     | `---` front matter | one document         |\n",
        "| Cell     | `#| option: value` | one code cell        |\n",
        "\n",
        "**Practice before next class**\n",
        "\n",
        "1.  Create a **Website** project from VS Code\n",
        "2.  Set `author` in `_quarto.yml`; override it on `about.qmd`\n",
        "3.  Add a `projects.qmd` page and link it in the navbar\n",
        "4.  Add a Python cell to `projects.qmd` that makes a plot; give it a\n",
        "    `fig-cap` and hide its code with `echo: false`\n",
        "5.  Turn on `code-fold: true` and `toc: true` for the whole site in\n",
        "    `_quarto.yml`\n",
        "6.  Render and open `_site/index.html`\n",
        "\n",
        "**Where to learn more:** the official guide at\n",
        "[quarto.org/docs/guide](https://quarto.org/docs/guide/) and the gallery\n",
        "at [quarto.org/docs/gallery](https://quarto.org/docs/gallery/)"
      ],
      "id": "35e85156-ed65-4508-8376-e81fc482a7c7"
    }
  ],
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3",
      "language": "python"
    },
    "language_info": {
      "name": "python"
    }
  }
}