Posit 入門繁中教材（Quarto＋Positron）

內容筆記

文字、程式碼、結果放在同一處

多數資料工作的結尾，是把數字和圖從一個工具複製貼到另一個工具：跑完分析、把圖截圖貼進投影片或 Word、再手打一段解讀。資料一更新，一切重來，還得祈禱沒漏掉任何一個數字。Quarto 的解法是把寫作、程式碼、結果放進同一個檔案。

Quarto 是開源的出版系統，用「文字與程式碼混合的純文字檔」製作文件、簡報、網站等。每次建置（build）文件時程式碼都會重新執行，因此結果永遠與資料同步。

這種把「說明」與「程式碼」編織在一起的做法叫 literate programming（文學式編程）：不是「程式碼加幾行註解」，而是寫成一份人可以由上讀到下的文件，程式碼與其輸出就放在該出現的位置。

它帶來三個好處（原文為三張翻卡，內容如下）：

從原始檔到成品

Quarto 文件寫在副檔名為 .qmd 的檔案中。.qmd 是原始檔（source）：純文字，含 markdown 格式，通常還有一些程式碼。它本身不適合直接拿來分享，要把它渲染（render）成成品。

下面把同一份文件的「原始檔」和「渲染結果」並排給你看。原始檔 hello.qmd 共 17 行：

---
title: "Weekly Temperatures"
author: "Ana Lopez"
format: html
---

## Summary

This week was **warmer** than last week,
peaking on *Saturday*.

```{r}
#| echo: false
temps <- c(18, 21, 24, 19, 23, 26, 25)
plot(temps, type = "b", pch = 19,
     xlab = "Day", ylab = "Temperature (°C)")
```

渲染成 HTML 後：最上方是大標題「Weekly Temperatures」，其下是作者名，然後是「Summary」標題、套好粗體（warmer）與斜體（Saturday）的句子，最後是一張一週氣溫（18、21、24、19、23、26、25 °C）的折線圖，程式碼被隱藏（因為 echo: false）。

渲染時發生什麼事

渲染分幾個步驟，Quarto 全部代勞：

1. Quarto 執行文件中每一個程式碼格（code cell），語言可以是 R、Python 或其他。
2. 把結果（數字、表格、圖）放回程式碼原本所在位置的文字中。
3. 把合併後的文字轉成你指定的格式：網頁、PDF、Word 等。

一份原始檔，多種格式

Quarto 最厲害之處：同一份 .qmd 可以變成截然不同的東西，只要改檔案最上方的一行就能切換。原文列出的輸出類型：

想看大家做了什麼，可瀏覽 Quarto Gallery。

從 R Markdown 轉過來？

若你用過 R，可能聽過 R Markdown：.Rmd 檔混合文字與 R 程式碼，可渲染成 HTML、PDF 或 Word。它已存在十年以上、仍被廣泛使用。本課不需要會它，但知道來龍去脈有幫助。

Quarto 是 R Markdown 的下一代，由同一個團隊 Posit 打造，把 R Markdown 累積的經驗重建成一個「不綁定 R」的系統。

關鍵詞

• Quarto：開源出版系統，用混合文字與程式碼的純文字檔產出文件、簡報、網站等。
• literate programming（文學式編程）：把說明與程式碼編織成一份可由上讀到下的文件。
• .qmd：Quarto 原始檔，純文字，含 markdown 與（常見的）程式碼。
• render（渲染）：執行程式碼並把 .qmd 轉成成品；產生新檔、不改原始檔。
• R Markdown（.Rmd）：Quarto 的前身，綁定 R 的套件。

可執行要點

• 記住流程：.qmd（原始檔）→ 執行程式碼 → markdown → 輸出成品
• 把「複製貼上圖表到 Word／投影片」的習慣，改想成「改資料、重新渲染」
• 若手上有舊的 .Rmd，之後可直接試著用 Quarto 渲染看看
• 逛一下 Quarto Gallery 找靈感

內容筆記

三個組成部分

每個 .qmd 檔都由同樣三種材料構成。下面是一份小而完整的 Quarto 文件，回報一週氣溫的平均：

---
title: "Weekly Temperatures"
format: html
---

## Summary

This week was **warmer** than last week.

```{python}
temps = [18, 21, 24, 19, 23]
sum(temps) / len(temps)
```

一開始符號看起來很多，但拆開來就是三塊，各有職責：

動手試：第一次渲染

原課程提供瀏覽器內的 Quarto 模擬器（左側編輯器、右側預覽，不用安裝任何東西）。它使用 Quarto 自己的格式化引擎，所以預覽結果與真正的 Quarto 一致；但只能預覽 HTML、也讀不到你電腦裡的檔案。本筆記改成請你在自己的環境操作（第 7 單元會教如何在自己電腦上用 Quarto）。本例用 Python，但這一課不需要你寫任何程式。

動手試： 在你自己的 .qmd 輸入上面那份完整文件（模擬器載入的就是它，程式碼格內是 temps = [18, 21, 24, 19, 23] 與 sum(temps) / len(temps)），渲染後依序做三個修改，每改一次就重新渲染一次：

1. 把 YAML 標頭的 title 改成別的，例如 "My First Quarto Document"。
2. 把文字中的 warmer 改成 cooler。
3. 改 temps 其中一個數字，例如把 24 改成 30。

預期結果： 標題改了、文字改了、而且改數字後平均值會自動更新。你會看到：YAML 的 title 變成頂端的大標題、markdown 變成排版文字、程式碼格同時顯示程式碼與其結果。這就是 Quarto 的核心觀念：結果永遠來自執行程式碼。

分辨哪個片段屬於哪一部分

接下來三個單元會逐一深入這三部分。先確認你分得清楚，下面是原課程的分類練習（原為拖曳，這裡直接給答案）：

判準：整份文件的選項放 YAML 標頭；你寫的文字是 markdown；需要執行的東西放程式碼格。

關鍵詞

• YAML header：檔案最上方被兩條 --- 包住的設定區。
• Markdown text：用簡單符號標記格式的內文。
• Code cell：會在渲染時執行並顯示結果的程式碼區塊（R Markdown 稱 code chunk）。
• Quarto simulator：原課程內建的瀏覽器版編輯與預覽環境，只預覽 HTML。

可執行要點

• 在自己的 .qmd 貼上範例文件並渲染一次
• 依序改標題、改文字、改數字，各渲染一次，確認每一處變動對應到輸出
• 看到任一片段時，先判斷它是 YAML、markdown 還是 code cell

內容筆記

Markdown 速覽

Markdown 是用少數簡單符號為純文字加格式的方法。你輸入 bold，渲染後就顯示粗體的 bold。沒有按鈕、沒有選單，只有任何鍵盤都能打出的字元。它被設計成「還沒渲染也很好讀」，所以用純文字編輯器打開 markdown 檔仍然看得懂。

最常用語法一覽：

標題

一行以 # 開頭就是標題，# 的數量決定層級：## 是章節、### 是其下的小節，依此類推。

## Results

### By region

粗體、斜體與行內程式碼

• 兩個星號 → 粗體
• 一個星號 → 斜體
• `反引號` → 行內程式碼，很適合標示檔名與函式名稱

動手試（markdown playground）： 原課程的練習場會邊打邊即時更新預覽。請在你自己的 .qmd 輸入以下內容，改幾個字、加一個標題，看渲染結果：

---
title: "Markdown Playground"
---

## A heading

Some **bold** text, some *italic* text, and a file name like `report.qmd`.

### A smaller heading

Try making *this sentence* bold instead.

預期結果：## A heading 顯示為較大的章節標題、### A smaller heading 為較小的小節標題；「bold」粗體、「italic」斜體、report.qmd 以程式碼字型顯示。

清單

每行以 - 開頭是項目清單；以「數字加句點」開頭是編號清單：

- Flour
- Milk
- Eggs

1. Mix the batter
2. Heat the pan
3. Cook both sides

連結與圖片

連結：中括號放要顯示的文字，後面緊接小括號放網址。圖片：同樣的寫法，前面加一個 !。當圖片單獨成一行時，中括號裡的文字會成為圖說（caption）。再用大括號加上 fig-alt 屬性，描述圖片給使用螢幕閱讀器的人：

Learn more on the [Quarto website](https://quarto.org).

![Daily highs for the week](temps.png){fig-alt="A line chart of daily high temperatures rising from 15 to 24 degrees over seven days."}

練習：幫食譜加格式

下面這份食譜文字都對、卻完全沒有格式（原課程在模擬器中，按 Render 才更新）：

---
title: "Pancakes"
---

Ingredients

1 cup flour

1 cup milk

1 egg

Steps

Whisk everything together.

Cook on a hot pan for 2 minutes per side.

Serve warm.

Do not overmix the batter.

動手試： 把它貼進你自己的 .qmd，先渲染看看，再用 markdown 做四件事：

1. 把 Ingredients 與 Steps 改成二級標題（## ）。
2. 三樣食材改成項目清單。
3. 三個步驟改成編號清單。
4. 把 Do not overmix the batter. 整句改成粗體。

提示：二級標題是兩個 # 加空格；每項食材以 - 開頭、步驟以 1.、2.、3. 開頭，且標題與清單之間要空一行；整句粗體是前後各包兩個星號。

參考答案：

---
title: "Pancakes"
---

## Ingredients

- 1 cup flour
- 1 cup milk
- 1 egg

## Steps

1. Whisk everything together.
2. Cook on a hot pan for 2 minutes per side.
3. Serve warm.

**Do not overmix the batter.**

小測：哪一行才是連結？

要把文字「the docs」連到 https://quarto.org，正確寫法是 the docs。!the docs 是圖片語法；(the docs)[https://quarto.org] 括號顛倒了。

關鍵詞

• Markdown：用簡單符號為純文字加格式的語法。
• fig-alt：圖片的替代文字屬性，給螢幕閱讀器使用者描述圖片。
• 行內程式碼（inline code）：用單一反引號包住、以程式碼字型顯示的文字。
• caption（圖說）：獨立成行的圖片，中括號中的文字會成為它的說明。

可執行要點

• 在 .qmd 練習標題（##、###）、粗體、斜體、行內程式碼各一次
• 每次寫清單前，先確認上方有一個空行
• 加圖片時順手補上 {fig-alt="..."}
• 把「食譜」練習自己做一遍並對照參考答案

內容筆記

YAML 怎麼運作

標頭位於 .qmd 檔最上方，夾在兩行三個破折號（---）之間。裡面用 YAML 撰寫，這是一種簡單的設定格式。每一行是一組 key: value：選項名稱、冒號、一個空格、你要的值。

---
title: "Quarterly Sales Report"
subtitle: "Third quarter"
author: "Ana Lopez"
date: today
---

選擇輸出格式

format 選項決定 Quarto 產出哪種檔案，文件其餘內容完全不變。下面是存成 report.qmd 的一份短報告（含標題、清單、表格與一段 Python 畫圖的程式碼格）：

---
title: "Quarterly Sales Report"
author: "Ana Lopez"
format: html
---

## Highlights

Sales grew **12%** this quarter, led by the *West* region.

- Two new regions opened
- Returns fell to a record low
- Online orders passed in-store orders

## Sales by Region

| Region | Sales | Change |
|--------|------:|--------|
| North  |   120 | Up     |
| South  |    95 | Down   |
| West   |   143 | Up     |

## Monthly Trend

```{python}
#| echo: false
import matplotlib.pyplot as plt

plt.figure(figsize=(6, 3))
plt.plot(["Jul", "Aug", "Sep"], [102, 115, 128], marker="o")
plt.ylabel("Sales (thousands)")
plt.show()
```

只改 format 這一行再渲染，結果如下（原文為四個分頁籤，這裡全部展開）：

HTML 版：大標題、作者、帶底線的章節標題、項目清單、有樣式的表格，以及七至九月（Jul、Aug、Sep；銷售 102、115、128 千）的折線圖。

PDF（Typst）版：標題與作者置中、襯線字體、較緊湊的表格。

Word 版：標題與作者置中、藍色章節標題、簡單表格與折線圖。

Slides 版：標題投影片只顯示大字的「Quarterly Sales Report」與下方的「Ana Lopez」。

小測：同事想用 Word 編輯並加註解你的報告，要渲染成哪個格式？答案是 format: docx。

格式選項：一份來源，多種格式

把多個格式列在 format 底下，各佔一行。default 代表「這個格式，不做任何更改」：

---
title: "Quarterly Sales Report"
format:
  html: default
  docx: default
---

渲染後，同一個檔案產出網頁和 Word 文件。選項可以在兩個層級設定。

所有格式共用的選項放在標頭最上層，與 title 並排。下例 number-sections: true 讓網頁與 Word 文件的標題都自動編號：

---
title: "Quarterly Sales Report"
number-sections: true
format:
  html: default
  docx: default
---

只給單一格式的選項，縮排放在該格式名稱底下。下例兩份檔案仍都有章節編號，但只有網頁會把程式碼折疊在一個 Code 按鈕後面；Word 文件無法折疊程式碼，因此 code-fold 是 HTML 專屬選項：

---
title: "Quarterly Sales Report"
number-sections: true
format:
  html:
    code-fold: true
  docx: default
---

注意縮排：code-fold 縮在 html: 之下，html: 又縮在 format: 之下，YAML 才知道它是 HTML 的選項。若同一個選項在兩個層級都設定，格式內層的那個優先（只對該格式生效）。

動手試： 在你自己的 .qmd 貼上下面這份使用簡寫 format: html 的文件：

---
title: "Quarterly Sales Report"
format: html
---

## Revenue

Revenue grew in every region.

```{python}
regions = {"North": 120, "South": 95, "West": 143}
sum(regions.values())
```

## Costs

Costs stayed flat.

把 format: html 改成帶選項的長寫法，並開啟 number-sections 與 code-fold：

format:
  html:
    number-sections: true
    code-fold: true

預期結果： 每個標題前出現編號，程式碼格被折疊在一個 Code 按鈕後面。

練習：修好壞掉的標頭

下面這個標頭有三個錯誤。原課程要你先渲染、讀錯誤訊息（模擬器會指出出問題的那一行），逐一修好直到文件能渲染且章節有編號：

---
title: Sales Report: Q3
author:Ana Lopez
format:
  html:
  number-sections: true
---

（原課程文件在標頭後有兩節：## Revenue「Revenue grew in every region.」與 ## Costs「Costs stayed flat.」。）

提示對應三條規則：

1. title 含冒號 → 需要加引號包住。
2. author:Ana Lopez → 冒號後要有空格。
3. number-sections: true 的縮排要比 html: 更深，才算是 HTML 的選項。

參考答案：

---
title: "Sales Report: Q3"
author: Ana Lopez
format:
  html:
    number-sections: true
---

關鍵詞

• YAML：簡單的設定語法，每行 key: value。
• format：決定輸出格式的選項：html、typst、pdf、docx、revealjs 等。
• default：html: default 表示該格式、不改任何設定。
• Typst / LaTeX：兩種排版 PDF 的系統；Typst 隨 Quarto 附帶，LaTeX 需另裝。
• reveal.js：在瀏覽器播放的簡報格式，## 標題開啟新投影片。
• number-sections：自動幫標題編號。
• code-fold：HTML 專屬選項，把程式碼折疊在 Code 按鈕後。

可執行要點

• 寫 YAML 時自我檢查三條規則：冒號後空格、含冒號要引號、縮排用空格
• 把同一份報告分別試 html、typst、docx、revealjs
• 需要 PDF 時先用 format: typst
• 想同時輸出多格式時，在 format: 下各列一行並用 default
• 共用選項放頂層；只給單一格式的選項縮排放在格式名稱下

內容筆記

程式碼格是什麼

程式碼格讓 Quarto 文件不只是排版文字。它以三個反引號加大括號內的語言名稱開頭，以三個反引號結尾。渲染時 Quarto 執行程式碼，把結果放在它的正下方。

R 版：

```{r}
temps <- c(18, 21, 24, 19, 23)
mean(temps)
```

輸出：

[1] 21

Python 版：

```{python}
temps = [18, 21, 24, 19, 23]
sum(temps) / len(temps)
```

輸出：

21.0

格選項（cell options）

預設輸出會同時顯示程式碼與結果。這對教學很好，但給主管的報告大概只需要圖表。格選項讓你逐格控制。

格選項放在格子的最上方，每行以 #|（井字號加直線）開頭，語法與 YAML 標頭相同，都是 key: value：

```{python}
#| echo: false
plt.plot(temps)
```

最常用的選項：

execute:
  echo: false

動手試： 在你自己的 .qmd 貼上下面的文件（需要 Python 與 matplotlib），先渲染看到圖；再在格子第一行加 #| echo: false 重新渲染；然後改試 #| eval: false 看有什麼不同。

---
title: "Weekly Temperatures"
---

```{python}
import matplotlib.pyplot as plt

temps = [18, 21, 24, 19, 23, 26, 25]
plt.plot(range(1, 8), temps, marker="o")
plt.xlabel("Day")
plt.ylabel("Temperature (°C)")
plt.show()
```

預期結果： 預設顯示程式碼與折線圖；加 echo: false 後只剩圖；改 eval: false 後只剩程式碼、沒有圖（因為沒有執行）。

小測：報告要顯示圖表、但不要顯示畫圖的程式碼，該加哪個選項？答案是 #| echo: false（eval: false 是不執行；include: false 連結果都藏起來）。

練習：把報告修整到可分享

下面這份報告可以運作，但顯示了畫圖程式碼、圖也沒有圖說：

---
title: "Weekly Temperatures"
---

The average temperature this week was:

```{python}
temps = [18, 21, 24, 19, 23, 26, 25]
sum(temps) / len(temps)
```

```{python}
import matplotlib.pyplot as plt

plt.plot(range(1, 8), temps, marker="o")
plt.xlabel("Day")
plt.ylabel("Temperature (°C)")
plt.show()
```

動手試：

1. 隱藏畫圖的程式碼，但保留圖。
2. 把畫圖的格子標籤設為 fig-temps。
3. 圖說設為 Daily temperatures。

三項都是第二個格子的格選項，各佔一行、以 #| 開頭、放在格子最上方；你需要 echo、label、fig-cap，圖說文字要加引號。

參考答案：

---
title: "Weekly Temperatures"
---

The average temperature this week was:

```{python}
temps = [18, 21, 24, 19, 23, 26, 25]
sum(temps) / len(temps)
```

```{python}
#| echo: false
#| label: fig-temps
#| fig-cap: "Daily temperatures"
import matplotlib.pyplot as plt

plt.plot(range(1, 8), temps, marker="o")
plt.xlabel("Day")
plt.ylabel("Temperature (°C)")
plt.show()
```

加碼：把結果放進句子裡（行內程式碼）

可以在句子中間執行一小段程式碼，稱為行內程式碼（inline code）：寫一個反引號、大括號中的語言、程式碼、再一個反引號：

The average temperature was `{python} sum(temps) / len(temps)` degrees.

R 則改用 {r}，例如 `{r} mean(temps)`。渲染時程式碼會被換成結果，所以句子永遠與資料一致。

關鍵詞

• code cell（程式碼格）：以 ```{語言} 開頭的可執行區塊。
• cell option（格選項）：放在格子最上方、以 #| 開頭的設定行。
• echo / eval / include：分別控制是否顯示程式碼 / 是否執行 / 程式碼與結果是否都顯示。
• label 與 fig-cap：替圖取名（fig- 開頭）與加圖說，讓圖變成有編號、有圖說的 Figure。
• execute:：YAML 標頭中為整份文件統一設定格選項的區塊。
• inline code（行內程式碼）：嵌在句子中、渲染後被結果取代的程式碼。

可執行要點

• 寫一個 R 或 Python 格，確認結果出現在下方
• 只給讀者看圖時，加 #| echo: false
• 要圖有編號與圖說：同時加 #| label: fig-xxx 與 #| fig-cap: "..."
• 全文件都不要顯示程式碼時，用 execute: 下的 echo: false
• 用 `{python} 運算式` 或 `{r} 運算式` 把數字直接嵌進句子

內容筆記

Callout（提示框）

Markdown 處理基本需求，Quarto 補上技術文件需要的功能。你在本課程一路看到的彩色方框（note、tip、warning）就是 callout，用來吸引讀者注意不能錯過的內容。寫法是三個冒號、大括號中的 callout 類型、你的文字、再以三個冒號結尾：

::: {.callout-tip}
Render often. It's the fastest way to catch mistakes.
:::

Quarto 有五種 callout：note、tip、important、warning、caution，各有自己的顏色與圖示。要給 callout 標題，就在開頭放一個 ## 標題。

動手試： 在你自己的 .qmd 貼上下面這份文件，渲染後可看到五種 callout，再試著改類型或標題：

---
title: "Callout Types"
---

::: {.callout-note}
A **note** adds helpful background.
:::

::: {.callout-tip}
## Save time

A **tip** shares a better way to do something. This one has a custom title.
:::

::: {.callout-important}
**Important** information the reader needs.
:::

::: {.callout-warning}
A **warning** about a common mistake.
:::

::: {.callout-caution}
**Caution** before doing something risky.
:::

預期結果：五個不同顏色與圖示的方框；tip 那個顯示自訂標題「Save time」。

交叉參照（Cross-References）

長報告常寫「如圖 3 所示」。若在前面多加一張圖，後面每個編號都會變，你得手動全部修改。交叉參照幫你自動編號。分兩步：

1. 替圖加標籤。 程式碼產生的圖，加格選項如 #| label: fig-temps。圖的標籤一定以 fig- 開頭。
2. 參照它。 在文字任何地方輸入 @ 加標籤，如 @fig-temps。

@fig-temps shows the temperature rising through the week.

```{r}
#| label: fig-temps
#| fig-cap: "Daily temperatures"
plot(temps, type = "b")
```

參照可以放在圖之前或之後，因為 Quarto 在渲染時才把它們配對。渲染後，@fig-temps 會變成一個顯示 Figure 1 的連結，圖說則顯示 Figure 1: Daily temperatures。在它上面再加一張圖，兩處編號都會自動更新。

動手試： 貼入下面文件並渲染，確認 @fig-temps 變成「Figure 1」連結、且與圖下方圖說的編號一致：

---
title: "Weekly Temperatures"
---

@fig-temps shows the temperature rising through the week.

```{r}
#| label: fig-temps
#| fig-cap: "Daily temperatures"
#| echo: false
temps <- c(18, 21, 24, 19, 23, 26, 25)
plot(temps, type = "b", xlab = "Day", ylab = "Temperature (°C)")
```

小測：圖的格選項是 #| label: fig-sales，在文字中要怎麼參照？答案是 @fig-sales（不是 Figure 1，也不是 {#fig-sales}，更不是手打 Figure 1）。

表格與表格交叉參照

幾乎每份報告都需要表格。Markdown 的寫法：欄位之間用 |（直線），標題列下方放一列破折號：

| Region | Sales |
|--------|------:|
| North  |   120 |
| South  |    95 |
| West   |   143 |

: Sales by region {#tbl-sales}

重點細節：

• 破折號列分隔標題與資料。破折號右側加冒號（------:）表示該欄靠右對齊，適合數字。
• 欄位不必對齊得很整齊：Quarto 只看 |，排整齊只是讓原始碼好讀。
• 表格下方以 : 開頭的那一行是圖說（caption）。加上 {#tbl-sales} 就給表格一個標籤，之後可用 @tbl-sales 參照，跟圖一樣。

動手試： 貼入下面文件（原課程此練習場會即時更新），為 East 區新增一列，或把別的欄位改成靠右：

---
title: "Quarterly Sales"
---

@tbl-sales shows sales for each region.

| Region | Sales | Change |
|--------|------:|--------|
| North  |   120 | Up     |
| South  |    95 | Down   |
| West   |   143 | Up     |

: Sales by region {#tbl-sales}

邊欄內容（Margin Content）

Quarto 的 HTML 頁面右側有寬闊的邊欄，可放旁註、小圖或某個數字背後的公式。這讓主文維持好讀、細節又近在手邊。把內容包在 ::: {.column-margin} 裡，Quarto 就會把它放在上方那段文字旁邊的邊欄：

The average temperature this week was 22.3 °C, up from
20.1 °C the week before.

::: {.column-margin}
The average of $n$ readings:

$$
\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i
$$
:::

渲染後的頁面如下：主文欄正常顯示兩段關於本週平均氣溫的文字，右側邊欄則是一則灰色小字「The average of n readings:」，下面是平均數公式（x 上有橫線，等於 n 分之一乘以 x_i 從 i=1 到 n 的總和）。

這裡用到 Quarto 的數學語法：在錢字號之間寫 LaTeX 記號。兩側各一個 $（如 $n$）把數學放在句子內；兩側各兩個 $$（如上面的 $$ 行）讓公式獨立成行。公式不只能放邊欄，在文件任何地方、任何格式都能用。

小測：想讓公式放在使用它的那段文字旁邊的邊欄，要用 ::: {.column-margin} 包住（不是公式後加 {#margin}，也不是 ::: {.callout-note}）。

練習：加 callout 與交叉參照

下面這份報告需要兩個收尾：

---
title: "Weekly Temperatures"
---

The chart below shows the temperature rising through the week.

Readings from Sunday are estimates.

```{r}
#| label: fig-temps
#| fig-cap: "Daily temperatures"
#| echo: false
temps <- c(18, 21, 24, 19, 23, 26, 25)
plot(temps, type = "b", xlab = "Day", ylab = "Temperature (°C)")
```

動手試：

1. 把 The chart below 這幾個字換成對圖的交叉參照（格子已標為 fig-temps）。
2. 把句子 Readings from Sunday are estimates. 放進 warning callout。

提示：交叉參照是 @ 加標籤，即 @fig-temps；warning callout 以單獨一行的 ::: {.callout-warning} 開頭、以單獨一行的 ::: 結尾，句子放中間。

參考答案：

---
title: "Weekly Temperatures"
---

@fig-temps shows the temperature rising through the week.

::: {.callout-warning}
Readings from Sunday are estimates.
:::

```{r}
#| label: fig-temps
#| fig-cap: "Daily temperatures"
#| echo: false
temps <- c(18, 21, 24, 19, 23, 26, 25)
plot(temps, type = "b", xlab = "Day", ylab = "Temperature (°C)")
```

關鍵詞

• callout：彩色提示框；類型 note、tip、important、warning、caution。
• fenced div：以 ::: 包住內容的語法，callout 與邊欄都屬於這一類。
• cross-reference（交叉參照）：用 @標籤 引用圖、表等，由 Quarto 自動編號。
• 標籤前綴：fig- 圖、tbl- 表、sec- 章節、eq- 公式。
• .column-margin：把內容放進 HTML 頁面右側邊欄的 class。
• $ / $$：行內數學／獨立成行的公式（LaTeX 記號）。

可執行要點

• 用 ::: {.callout-warning} 標示一則重要警語，並試著加 ## 標題
• 替某張圖加 #| label: fig-xxx，並在文字中用 @fig-xxx 參照
• 寫一個 markdown 表格，加上 : 圖說 {#tbl-xxx} 並參照它
• 把一個公式放進 ::: {.column-margin}（需在自己電腦預覽 HTML）
• 記住 {} 內順序：ID → class → 屬性

內容筆記

取得 Quarto

你在模擬器裡練過的一切，在自己電腦上做法相同。Quarto 是一個負責渲染文件的命令列程式。最簡單的取得方式，是用已內建它的編輯器，所以不必另外安裝：

本課以 Positron 示範。若要讓 R 或 Python 程式碼格能執行，還需要安裝 R 或 Python，以及 R 的 rmarkdown 套件或 Python 的 jupyter 套件。只有文字與 markdown 的文件則不需要其他東西。

建立並預覽文件

建立文件並預覽只要幾次點擊。原課程是點擊截圖的互動模擬，這裡依序展開四步：

步驟 1：開新檔案。 點 Positron 左上角的 New 按鈕（旁邊是 Open 按鈕；此時 Console 是空的 Python 控制台）。

步驟 2： 打開的 New 選單有 New File、New Folder from Template、New Folder from Git、New Window 等項目，點 New File...。

步驟 3：選檔案類型。 Positron 問你要哪種檔案，清單有 Text File、R File、Python File、Jupyter Notebook、Quarto Document、Quarto Project，選 Quarto Document。

步驟 4：預覽。 文件在編輯器中開啟後，點編輯器左上方的 Preview。

模擬中的文件內容如下（在你自己的 Positron 貼上或自行加入也行）：

---
title: "My First Document"
format: html
---

## Hello, Quarto

This document mixes text and code. When you preview it, Quarto
runs the code and shows the result right below it.

```{python}
total = 2 + 3
print(f"The total is {total}")
```

完成後的結果： Positron 渲染文件，並把結果顯示在 Viewer 窗格，緊鄰你的原始檔。程式碼已執行，輸出出現在程式碼下方（內容為「The total is 5」）。你修改原始檔再按 Preview，Viewer 就會更新。

試試更有趣的文件

想預覽更豐富的內容？把下面其中一份複製進新的 Quarto 文件，存成 temps.qmd，按 Preview。它用到 callout、交叉參照與程式碼格畫的圖，都是本課練習過的東西。

R 版（需要 rmarkdown 套件）：

---
title: "Weekly Temperatures"
format: html
---

## Summary

The daily highs for the week are in @fig-temps. The warmest reading was **26 °C**.

::: {.callout-note}
Readings from Sunday are estimates.
:::

```{r}
#| label: fig-temps
#| fig-cap: "Daily high temperatures"
#| echo: false
temps <- c(18, 21, 24, 19, 23, 26, 25)
plot(temps, type = "b", xlab = "Day", ylab = "Temperature (°C)")
```

Python 版（需要 jupyter 與 matplotlib 套件）：

---
title: "Weekly Temperatures"
format: html
---

## Summary

The daily highs for the week are in @fig-temps. The warmest reading was **26 °C**.

::: {.callout-note}
Readings from Sunday are estimates.
:::

```{python}
#| label: fig-temps
#| fig-cap: "Daily high temperatures"
#| echo: false
import matplotlib.pyplot as plt

temps = [18, 21, 24, 19, 23, 26, 25]
plt.plot(range(1, 8), temps, marker="o")
plt.xlabel("Day")
plt.ylabel("Temperature (°C)")
plt.show()
```

日常工作流程的正確順序（原課程為排序題）：

1. 建立新的 Quarto 文件並存成 .qmd
2. 寫文字與程式碼
3. 按 Preview
4. 在 Viewer 窗格檢查結果

從終端機使用 Quarto

回頭看剛才模擬的最後一個畫面：當你按 Preview，Positron 會在底部打開 Terminal 分頁並執行類似下面的指令：

quarto preview first-qmd.qmd --no-browser --no-watch-inputs

Preview 按鈕其實就是 quarto preview 指令的捷徑，外加兩個選項：

• --no-browser：讓結果顯示在 Positron 的 Viewer 窗格，而不是開啟網頁瀏覽器。
• --no-watch-inputs：不要每次存檔就重新渲染，Viewer 只在你再按 Preview 時才更新。如果你希望每次存檔都更新，勾選 Preview 旁的 Render on Save。

你也可以在任何終端機自己輸入 Quarto 指令，搭配任何編輯器都能用：

# Render and open a live preview that updates when you save
quarto preview report.qmd

# Render to the format(s) in the YAML header
quarto render report.qmd

# Render to a specific format
quarto render report.qmd --to docx

Run Cell 與 Preview 的差別

在 Positron，每個程式碼格上方都有 Run Cell 連結，寫作時很方便：不必等整份文件，可以一次試一個格子。但 Run Cell 與 Preview 在不同的地方執行你的程式碼，彼此不共用結果。Run Cell 把程式碼送到 Console；Preview 則在 Terminal 執行 quarto preview，那是另一個獨立程式、會開啟自己的 session。

這造成一個經典的意外。假設你在 Console 探索，並在那裡載入資料：

import pandas as pd
sales = pd.read_csv("sales.csv")

文件中有一個格子是 sales.head()。你按 Run Cell 成功了，因為 sales 存在於 Console。然後你按 Preview，卻失敗並出現 NameError: name 'sales' is not defined。因為 Preview 的全新 session 從沒看過你的 Console，所以那裡沒有 sales。R 也一樣，錯誤訊息類似 object 'sales' not found。

小測：Run Cell 成功、Preview 卻說 model 沒定義，最可能的原因是你在 Console 建立了 model，但文件中沒有任何格子建立它（不是沒存檔，也不是 Preview 不能跑程式碼格）。

渲染成其他格式

在自己的電腦上，Quarto 能產出所有格式，不只 HTML。要切換，就像在模擬器那樣，改 YAML 標頭的 format：

---
title: "Quarterly Sales Report"
format: docx
---

預覽後，Quarto 會在 .qmd 旁邊寫出 report.docx。HTML 與 PDF 的預覽在 Viewer 窗格開啟；Word 這類格式則在它自己的應用程式中開啟。

若文件在 format 下列了多個格式，Preview 只會顯示第一個。Positron 有兩個命令處理其他格式。用 Ctrl/Cmd + Shift + P 打開 Command Palette（命令面板）執行：

和 Preview 一樣，它們會替你在 Terminal 執行 Quarto；例如 Quarto: Render Document 執行的就是 quarto render。

小測：文件在 format 下同時列了 html 與 docx，按 Preview 只得到 HTML，要怎麼同時拿到 Word 檔？從 Command Palette 執行 Quarto: Render Document（再按一次 Preview 或把檔案存成 .docx 副檔名都沒有用）。

關鍵詞

• Positron：Posit 的編輯器，內建 Quarto 與 Quarto 擴充功能。
• Preview：按鈕，等於在 Terminal 執行 quarto preview（加 --no-browser --no-watch-inputs）。
• Viewer 窗格：Positron 中顯示預覽結果的區域。
• quarto preview：寫作用，持續執行並在存檔時刷新。
• quarto render：完稿用，產出最終檔後結束；可加 --to docx 指定格式。
• Terminal vs Console：Quarto 指令只能在 Terminal；Console 只懂 R／Python。
• Run Cell：把單一格子送到 Console 執行；與 Preview 的 session 不共用。
• Command Palette：Ctrl/Cmd + Shift + P，執行 Quarto: Preview Format… 或 Quarto: Render Document。

可執行要點

• 安裝 Positron（或確認 RStudio 內建 Quarto 可用）
• 建立 New > New File... > Quarto Document，存成 .qmd 後按 Preview（或 Ctrl/Cmd + Shift + K）
• 把 temps.qmd 範例貼進去，確認圖與 callout 出現
• 把所有 library()／import 與資料讀取都寫進文件的格子，並放在使用前
• 以 Preview 作為「文件是否自足」的最終檢查
• 需要 Word／PDF：改 format，多格式時用 Quarto: Render Document；PDF 先用 typst

內容筆記

你學過的內容

• Quarto 是什麼、渲染如何把 .qmd 變成成品，以及它如何從 R Markdown 發展而來
• Quarto 文件的三個部分：YAML 標頭、markdown 文字、程式碼格
• 如何用 markdown 排版文字，並用 YAML 選項與輸出格式控制文件
• 如何加入 R 與 Python 程式碼格，並用格選項控制輸出
• 如何使用 callout、交叉參照、表格與邊欄內容
• 如何在 Positron 與終端機中建立、預覽與渲染文件

更深入或本課未涵蓋的功能，請查 Quarto 官方文件。

Quarto 速查表

YAML 標頭（單元 4）

---
title: "Report Title"
author: "Your Name"
date: today
format:
  html:
    number-sections: true
  docx: default
execute:
  echo: false
---

Markdown（單元 3）

## Section heading

**bold**, *italic*, `code`

- Bulleted item
1. Numbered item

[Link text](https://quarto.org)
![Caption](image.png){fig-alt="Description for screen readers"}

程式碼格（單元 5）

```{r}
#| label: fig-sales
#| fig-cap: "Monthly sales"
#| echo: false
plot(sales)
```

Quarto 功能（單元 6）

::: {.callout-tip}
A callout: note, tip, important, warning, or caution.
:::

@fig-sales shows the trend.

| Region | Sales |
|--------|------:|
| North  |   120 |

: Sales by region {#tbl-sales}

渲染方式（單元 7）

綜合練習（Keep Practising）

原課程最後提供一個自由練習場。請你在自己的 .qmd 貼上下面的起點，試著把學過的全部組合起來：一個標題、幾個編號章節、一個 callout、以及一張有圖說並用交叉參照引用的圖。

---
title: "My Quarto Document"
author: "Your Name"
format:
  html:
    number-sections: true
---

## Introduction

Write something here.

預期結果：渲染後章節標題自動編號；你加入的 callout 以彩色方框顯示；@fig-xxx 變成「Figure 1」連結，圖下方有「Figure 1: 圖說」。

下一步（Next Steps）

• 動手做真的： 打開 Positron，建立 Quarto 文件，寫下你現在正在處理的東西
• 讀官方指南： Quarto Guide 更深入地涵蓋本課每項功能，還有更多
• 找靈感： Quarto Gallery 有文件、簡報、網站、書籍、儀表板的範例與原始碼
• 試新格式： 把 format: html 改成 revealjs，把文件變成投影片

關鍵詞

• .qmd：Quarto 原始檔。
• YAML 標頭：--- 之間的 key: value 設定。
• 程式碼格／格選項：```{r} 區塊與 #| 設定行。
• callout / 交叉參照 / 邊欄：::: {.callout-}、@fig-／@tbl-*、::: {.column-margin}。
• render / preview：完稿 vs 寫作時的預覽。

可執行要點

• 用速查表自己寫一份含 YAML、markdown、程式碼格、callout、交叉參照的 .qmd
• 把你手邊真實的分析包成一份 Quarto 文件並 Preview
• 把 format: html 改成 revealjs 看看簡報效果
• 逛 Quarto Gallery，挑一個想模仿的範例

內容筆記

Positron 是什麼

Positron 是 Posit 的「次世代」資料科學 IDE：單一、多語言（polyglot）的環境，同時處理 Python 與 R，並建立在開源基礎之上。

用過 RStudio 的人會覺得大部分地方很熟悉：Console（主控台）、Plots（圖表）、Variables（變數）、資料檢視，都在預期的位置。差別在於 Positron 把 Python 與 R 視為「平等公民」，並且採用與 VS Code 同一套開源基礎，因此彈性大、能隨你的需求成長。

這張是剛開啟 Positron 時的畫面：最左是 Explorer，中間是 Welcome 分頁與下方的 Console，最右是 Variables 與 Plots 區。

設計理念：四個關鍵字

與 RStudio、VS Code 的關係

Positron 位在兩者之間：借用 RStudio 的資料科學使用體驗，加上 VS Code 靈活、可擴充的基礎。

關鍵詞

• Positron：Posit 的次世代、多語言資料科學 IDE。
• IDE：整合開發環境，把編輯器、主控台、圖表、檔案管理放在同一個視窗。
• Polyglot：多語言；此處指同時支援 Python 與 R。
• Code OSS：VS Code 背後的開源核心，Positron 與 VS Code 共用。
• P3M（Posit Public Package Manager）：Positron 預設的 extensions 來源（第 4 單元詳述）。
• Data Explorer：Positron 內建的資料檢視工具（原文僅列名稱，用法本單元未說明）。

可執行要點

• 到 positron.posit.co/download.html 下載並安裝 Positron
• 開啟後辨認出 Console、Variables、Plots 的位置，確認和 RStudio 的習慣差不多
• 記住定位：RStudio 的資料科學體驗 + VS Code 的彈性基礎

內容筆記

先認識整個視窗

第一次開啟 Positron，畫面看起來很擁擠，但其實只分成四個區域，各自對應工作流程的一環：管理專案、寫程式、執行、理解回傳結果。能叫出這四個名字，後面的課程就容易對上。

預設配置是：Manage 在視窗最左側、Write 在中央偏上、Run 在 Write 的正下方、Understand 在最右側。

四個區域

Manage：Activity bar 是視窗最左邊的一條圖示列，緊鄰它的是 Side bar。點選 Activity bar 上的圖示，就會切換 Side bar 顯示的內容。

Write：腳本、notebook、文件各以一個分頁開在編輯器裡（例如開著一支 R 腳本 testing.R），大部分撰寫工作在這裡完成。

Run：位於編輯器下方的面板，上方有一排分頁，包括 Console、Terminal、Problems、Output、Ports、Debug Console。

Understand：右側面板上方有分頁（Session、Connections、Help、History、Viewer 等，下一單元詳述）；Session 分頁內有 Variables 與 Plots 兩個區塊。

區域如何串成工作流程

流程是：在左側管理專案 → 在中央撰寫程式 → 在正下方執行 → 在右側理解結果。視線大致由左到右、由上到下，每一步的位置都很靠近下一步。

顯示／隱藏任一區域

不必一直開著所有區域。視窗右上角有三個版面切換圖示，可分別開關：左側的 side bar、下方的 panel、右側的 panes。

小練習：這件事屬於哪個區域？

Command Palette（指令面板）

在四個區域之外，做幾乎任何事最快的方法就是 Command Palette：

• 快捷鍵：Cmd+Shift+P（macOS）／Ctrl+Shift+P（Windows/Linux）
• 或點視窗上方的搜尋列，選 Show and Run Commands
• 然後輸入想做的事並執行，不必在選單裡翻找

幾乎所有指令、設定、動作都能從這裡抵達，所以是「第一個值得學的捷徑」。後面課程會用它來切換主題、開啟設定、管理 sessions。

關鍵詞

• Activity bar（活動列）：視窗最左側的一條圖示列，用來切換 Side bar 內容。
• Side bar（側邊欄）：緊鄰 Activity bar，顯示目前選取的檢視（如 Explorer）。
• Editor（編輯器）：中央撰寫腳本、notebook、文件的區域。
• Console / Terminal：編輯器下方，執行 Python/R 與 shell 指令的地方。
• Command Palette：用輸入文字搜尋並執行指令的面板。

可執行要點

• 開啟 Positron，指出 Manage、Write、Run、Understand 各在視窗哪個位置
• 練習用視窗右上角的三個圖示顯示／隱藏左側 side bar、下方 panel、右側 panes
• 按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows）開啟 Command Palette 並搜尋一個指令

內容筆記

Activity bar 與 Primary side bar

Activity bar 預設是視窗最左側一條垂直的圖示列。每個圖示會在緊鄰的 Primary side bar 開啟不同的檢視；點圖示，側邊欄內容就跟著切換。

編輯器與 Console：寫 vs. 跑

兩者初學容易混淆，要點是：編輯器用來「寫」程式，Console 用來「執行」程式。

從編輯器執行一行時，那行會被送到 Console 並在那裡執行。把游標放在腳本的某一行，按 Cmd+Enter（macOS）／Ctrl+Enter（Windows/Linux） 即可：

# 用 Cmd/Ctrl + Enter 送到 Console 執行
summary(mtcars$mpg)

（補充）這個「在腳本中逐行執行、結果出現在 Console」的操作，和 RStudio 的 Ctrl+Enter 習慣相同。

右側面板：Secondary side bar 的四個分頁

預設在右側的面板是 Positron 資料科學工具的所在，以頂端分頁分組：Session、Help、History、Viewer（畫面中還可看到 Connections 分頁，本課未說明）。

Session 分頁：

History 分頁：

Viewer 分頁：

Help 分頁（內容為 Positron 文件、社群論壇、cheat sheets 的連結）沒有放圖，用文字描述即可。

（補充）若以 RStudio 對照：Variables 約略對應 Environment 分頁，Plots／Help／Viewer／History 在 RStudio 也有同名面板；Positron 把它們收進同一個右側面板的分頁中。

小練習：分頁配對

關鍵詞

• Activity bar：最左側圖示列，切換 Primary side bar 顯示的檢視。
• Primary side bar：緊鄰 Activity bar 的側邊欄，顯示 Explorer、Search 等。
• Secondary side bar：預設在右側的面板區，含 Session、Help、History、Viewer 分頁。
• Variables / Plots：Session 分頁內，分別列出環境物件與收集圖表。
• To Console / To Source：History 中，把指令重新執行／貼回腳本。
• Posit Assistant：Positron 內建的 AI 助理。

可執行要點

• 逐一點 Activity bar 的圖示，確認各自開啟什麼；再點一次作用中圖示試試收起 side bar
• 在腳本寫 summary(mtcars$mpg)，按 Cmd/Ctrl+Enter，看 Console 輸出
• 打開右側 Session、Help、History、Viewer 四個分頁，各看一次
• 要用 Data Connections 前，先到 Settings 開啟 dataConnections.enabled 並重新載入

內容筆記

Extensions（擴充功能）

Extensions 為 Positron 增加功能，從語言支援、主題到生產力工具都有。到 Activity bar 的 Extensions 檢視（圖示像一疊方塊）瀏覽與安裝。

安裝步驟：開啟 Extensions 檢視 → 搜尋想要的 → 在結果上按 Install。裝好後該項目會出現齒輪圖示，並列在「已安裝」清單中。

Color Themes（色彩主題）

Positron 內建多款主題，隨時可切換；選到某個主題時介面顏色立即改變，所以可以先預覽再決定。

內建主題舉例：Light（預設）、Dark、Tomorrow Night Blue、Light High Contrast、Dark High Contrast。

開啟主題選單有兩種方式：

Keyboard Shortcuts（鍵盤快捷鍵）

從 RStudio 轉來不需要重學所有快捷鍵，Positron 可以把快捷鍵重新對應成你熟悉的。

開啟 RStudio keybindings：

1. 開啟設定：Cmd+,（macOS）／Ctrl+,（Windows/Linux），或在 Command Palette 執行 Preferences: Open Settings。
2. 搜尋 workbench.keybindings.rstudioKeybindings，勾選核取方塊。
3. 重新啟動 Positron 才會生效。

檢視或修改單一快捷鍵： Command Palette 執行 Preferences: Open Keyboard Shortcuts → 以名稱搜尋指令（例如 Run Selection）→ 雙擊它的快捷鍵 → 按下想指定的新按鍵。

自訂版面（Customizing Your Layout）

面板不是固定死的，可依工作習慣重排，也能隨時回到整齊的起點。

• 預設版面（Preset layouts）：開 Command Palette，執行 Customize Layout 相關指令（搜尋 layout），在內建配置間切換，例如以 Posit Assistant 為優先的版面、或適合 notebook 工作的版面。
• 自行移動：拖曳面板的分頁，停靠到新位置；或在 Activity bar 圖示上按右鍵，隱藏它或改變位置。
• 重置：版面亂掉時，在 Command Palette 執行 View: Reset View Locations，全部恢復預設。

指令／設定對照

這些都能從 Command Palette 或 Settings 找到，想改外觀或行為，搜尋一下就到。

關鍵詞

• Extension：擴充功能，加語言支援、主題、工具。
• P3M：Posit Public Package Manager，Positron 預設的 extensions 來源。
• Open VSX：開源、中立的 extensions 市集；目錄與 P3M 相同。
• Bootstrapped extension：隨 Positron 附帶、自動安裝的 extension（如 Posit Publisher）。
• RStudio keybindings：內建設定，啟用一批 RStudio 快捷鍵（需重啟）。
• User profile：保存你的設定、快捷鍵與版面的使用者設定檔。

可執行要點

• 開啟 Extensions 檢視，搜尋並安裝一個你需要的 extension
• 用 Preferences: Color Theme 預覽並選一個主題
• 若從 RStudio 轉來：Settings 搜尋 workbench.keybindings.rstudioKeybindings 勾選並重啟
• 改任何快捷鍵前，先看 When 欄位與衝突警告
• 試著拖曳一個面板，再用 View: Reset View Locations 還原

內容筆記

選擇 Interpreter

interpreter picker（interpreter 選擇器） 顯示 Console 目前跑的語言與版本，位於視窗上方的 action bar 最右上角，會顯示類似 R 4.5.3 或 Python 3.12。

操作：點它 → 開啟 Positron 偵測到的 interpreter 清單 → 選你要的 → 指示文字隨之更新。

重啟與切換 Session

有時想要乾淨的起點，或想同時並排跑 Python 與 R。三種操作：

情境判斷：該用哪一招？

情境：你整個早上都在 R session 做實驗，現在腳本給出的結果和你第一次跑時不同，懷疑是先前實驗留下的變數干擾。

關鍵詞

• Interpreter：執行程式的語言與版本。
• Session：interpreter 的一個執行實例，保存變數、套件、歷史。
• Interpreter picker：視窗右上方 action bar 的選擇器，顯示並切換語言版本。
• Restart：重啟 session，得到乾淨狀態但清空記憶體。

可執行要點

• 點右上角 interpreter picker，看 Positron 偵測到哪些 R 與 Python 版本
• 另開一個 Python（或 R）session，並在 Console 的 session 清單中切換
• 練習重啟 session；重啟前先確認重要內容已存檔
• 遇到結果怪怪的，先重啟 session、從頭重跑腳本

內容筆記

1. Positron 是什麼（第 1 單元）

Posit 的次世代、多語言（Python + R）資料科學 IDE，建立在與 VS Code 相同的開源核心 Code OSS 上。相較 RStudio：基礎更彈性；相較 VS Code：資料科學工具（plots、variables、viewer、Data Explorer）是內建的。

2. 四個區域（第 2 單元）

工作流程：管理 → 撰寫 → 執行 → 理解。視窗右上角三個圖示可顯示／隱藏左側 side bar、下方 panel、右側 panes。

3. 核心面板（第 3 單元）

• Activity bar 切換 side bar 的檢視：Explorer、Search、Source Control、Run and Debug、Extensions、Packages、Posit Assistant、Data Connections（預覽功能，需啟用 dataConnections.enabled）。
• 編輯器是「寫」，Console 是「跑」；Cmd/Ctrl+Enter 把游標所在行送進 Console。
• 右側分頁：Session（Variables＋Plots）、Help、History（To Console／To Source）、Viewer（Quarto 報告、Shiny 等應用或文件）。

速查表：想做什麼，去哪裡

4. 讓它成為你的（第 4 單元）

5. Interpreter 與 Sessions（第 5 單元）

• Interpreter ＝ 語言＋版本；session ＝ 它的一次執行，保存變數、套件、歷史。
• 右上角 interpreter picker 選擇；可重啟（清空記憶體）、另開 session、在 Console 的 session 清單切換。
• Python 與 R 可並行各跑一個 session。

關鍵詞

• Code OSS、Polyglot、P3M、Command Palette、Session / Interpreter：定義見第 1、2、4、5 單元筆記。

可執行要點

下面是課程建議的後續步驟：

• 用 Positron 開一個自己的專案並從頭跑到尾：開資料夾 → 選 interpreter → 執行腳本 → 檢查 Variables 與 Plots
• 設定成自己慣用的樣子：選主題、（從 RStudio 轉來的話）開 RStudio keybindings、排好面板
• 把官方文件放在手邊：Layout（positron.posit.co/layout.html）、Keyboard shortcuts（positron.posit.co/keyboard-shortcuts.html）、Extensions（positron.posit.co/extensions.html）、Managing interpreters（positron.posit.co/managing-interpreters.html）

內容筆記

先預覽、再載入

專案資料夾裡有一個檔案（下載來的、別的工具匯出的、同事給的），你想先知道裡面有什麼。直覺是寫程式讀進來，但其實不用——Positron 可以直接把檔案秀給你看。

Data Explorer 是 Positron 內建的表格資料檢視工具，可打開資料檔與記憶體中的 data frame，以快速、類試算表的介面檢視，不必離開 IDE。（對熟 RStudio 的人：相當於 View() 的強化版，而且連檔案都能直接開。）

打開資料檔

Data Explorer 背後由 DuckDB 驅動，可直接開多種表格格式；CSV 和 Parquet 最常用，但只是其中兩個例子：

支援清單持續增加，以官方 Data Explorer 文件為準（positron.posit.co/data-explorer.html）。

操作：在 Explorer（側邊欄的檔案樹）中選取該檔案。因為它是支援的資料格式，Positron 會用 Data Explorer 開啟，而不是純文字編輯器。（原文有一段動畫示範這個動作，步驟即上述：在檔案樹點資料檔 → 自動在 Data Explorer 開啟。）

Data Explorer 的三個部分

三個部分合起來，幾秒就能對資料集有感覺：

下圖是 weather.csv（1,460 列、8 欄）的實際畫面：Summary panel 逐欄列出 date、city、temp_high_f、temp_low_f、precip_in、humidity_pct、wind_mph、condition 的型別圖示、分布小圖與缺值百分比（數值欄約 1–2% 缺值）；Data Grid 顯示每列資料，缺值格顯示 NULL；上方動作列有 Clear Column Sorting、Convert to Code、File Options、Open as Plain Text File；底部狀態列寫著列數與欄數。

小結

• 預覽是「低成本」認識資料集的方式，之後再決定怎麼載入。
• 哪個部分做什麼：Data Grid 看列、Summary panel 看每欄的剖面、Filter bar 聚焦子集——全都不會碰原始檔案。

關鍵詞

• Data Explorer：Positron 內建的表格資料檢視器，可開檔案或記憶體中的 data frame。
• Data Grid：Data Explorer 的列欄格線，可捲動、依欄排序。
• Summary panel：逐欄顯示型別、缺值、分布的摘要面板。
• Filter bar：縮小檢視範圍的篩選控制，不改原檔。
• Convert to Code：把目前的排序／篩選檢視轉成 Python、R 或 SQL 程式碼。
• Open as Plain Text File：切換成原始純文字檢視。
• DuckDB：Data Explorer 讀取檔案時使用的引擎。

可執行要點

• 在 Positron 的 Explorer 選一個 CSV 或 Parquet，確認它在 Data Explorer 開啟
• 先看 Summary panel：找出缺值多、型別不對、類別怪異的欄位
• 試著排序與篩選，再按 Convert to Code 取得可重現的程式碼
• 需要看原始文字時，用 Open as Plain Text File 切換

內容筆記

從檔案到變數

預覽適合快速看一眼；當你要真正處理資料（清理、轉換、建模），就把它載入 session 的變數。

Python（用 polars；也可用 pandas）：

import polars as pl

weather = pl.read_csv("weather.csv")

把 read_csv 換成 read_parquet 即可讀 Parquet。完成後 weather 就是 session 中的物件。

R（用 readr）：

library(readr)

weather <- read_csv("weather.csv")

讀 Parquet 用 arrow::read_parquet()，或用 base R 的 read.csv()。同樣，weather 成為 session 中的物件。

在 Variables pane 看見它

read 指令一跑完，新物件就出現在畫面右側的 Variables pane（這是你目前 session 中所有物件的即時檢視）。它提供三件事：

以 weather 為例，摘要是「1460 rows × 8 columns」，展開後每欄一列：date（Date）、city（字串，1460 筆）、temp_high_f、temp_low_f、precip_in、humidity_pct、wind_mph（皆為數值 double，1460 筆，缺值以 NA 顯示）、condition（字串）。

在 Data Explorer 打開已載入的物件

Variables pane 給摘要；想要完整的類試算表檢視，就把 data frame 在 Data Explorer 打開（與上一單元預覽檔案用的是同一個工具）。

最簡單：在 Variables pane 找到該 data frame，點它旁邊的資料圖示（一個格線／表格形狀的小圖示），就會在 Data Explorer 開啟。也可以用程式碼：

%view weather

View(weather)

開啟後分頁標題是 Data: weather，內容有 Summary panel（每欄的直方圖與缺值百分比）與可捲動的 Data Grid，上方動作列有 Clear Column Sorting 與 Convert to Code。

關鍵詞

• Variables pane：顯示目前 session 所有物件與摘要的即時面板。
• %view：Python 中在 Data Explorer 開啟物件的魔術指令。
• View()：R 中對應的函式（RStudio 使用者熟悉，Positron 中會開 Data Explorer）。
• 資料圖示：Variables pane 中 data frame 旁的小表格圖示，點下即開 Data Explorer。

可執行要點

• 用 read_csv（R 或 polars）把一個檔案讀成 weather 類變數
• 在 Variables pane 展開，核對列數、欄數與各欄型別
• 分別用資料圖示和 View()／%view 開 Data Explorer
• 記得重啟 session 後要重新載入資料

內容筆記

Data Connections 做什麼

資料不只存在檔案，很多在資料庫與資料倉儲。Data Connections 是 Positron 主側邊欄的一個檢視，可：儲存資料庫／資料倉儲連線、瀏覽內容（catalog、schema、table、view、column）、在 Data Explorer 預覽表格、產生 Python／R 連線程式碼。

開箱即支援：DuckDB、SQLite、PostgreSQL、Snowflake、Databricks、Redshift，以及任何已安裝本機 ODBC 驅動程式的資料庫。儲存連線時，密碼、token、連線字串存放在作業系統的 secret storage，而非明文。

連到本機 DuckDB

DuckDB 很適合入門：在本機執行、不需架伺服器，整個資料庫就是你電腦上的一個檔案，所以沒有憑證要管理。

1. 開啟 Data Connections 檢視（activity bar 上的資料庫圖示），按頂端的 +（Add Connection）。
2. 在 Add Data Connection 對話框，按 DuckDB 旁邊的 Connect。
3. 為連線命名（範例：Weather Data），按 Browse 選資料庫檔案（範例：weather.duckdb）。
4. 按 Save。

連線出現在樹狀清單中，可供瀏覽。原文有一段動畫示範整個流程：新增連線、選 DuckDB、命名、瀏覽選檔、儲存，接著展開連線經 Tables 到 weather 表與其欄位，再於 Data Explorer 開啟該表——展開與預覽的步驟見下一節。

連線會被儲存，下次開 Positron 仍在，不必重設。

瀏覽與預覽

連線儲存後變成可瀏覽的樹，不用寫任何 SQL：

1. 展開連線以開啟它。綠點表示連線是活的。
2. 展開 Tables（或 Views）看資料庫內容。
3. 展開某張表可看其 Columns（含資料型別）與 Indexes。
4. 對表雙擊（或右鍵選 Open in Data Explorer），即在 Data Explorer 預覽。

若資料庫有多個 schema，樹中會在表之上多一層 schema；本例的簡單 DuckDB 只有一個 schema，Positron 會直接顯示其 tables 與 views。

用完後收合連線即斷線；若還有該連線開啟的 Data Explorer 分頁，連線會維持到最後一個分頁關閉。

在程式中使用連線：Connect With

瀏覽用來熟悉環境；要在腳本或 notebook 查詢時，Data Connections 能幫你寫連線程式碼：

1. 對連線按右鍵，選 Connect With，再選 Python 或 R。
2. 在對話框檢視產生的程式碼。
3. 按 Copy 複製到剪貼簿、Create Script 在新檔開啟、或 Connect 在目前 console 執行。

DuckDB 產生的程式碼很短，大致如下：

import duckdb

con = duckdb.connect("weather.duckdb")

library(DBI)

con <- dbConnect(duckdb::duckdb(), "weather.duckdb")

關鍵詞

• Data Connections：儲存／瀏覽資料庫連線的側邊欄檢視（預覽功能）。
• dataConnections.enabled：啟用此功能的設定鍵。
• Add Connection（+）：新增連線按鈕。
• Read Only：唯讀勾選（DuckDB、SQLite）。
• Connect With：右鍵選單，產生 Python／R 連線程式碼。
• Include Secrets：把憑證直接寫入產生的程式碼（需確認，不建議）。
• DuckDB：單檔、本機執行的分析型資料庫。

可執行要點

• 在 Settings 啟用 dataConnections.enabled 並重新載入 Positron
• 新增一個 DuckDB 連線（命名、Browse 選檔、Save），建議維持 Read Only
• 展開 Tables，雙擊一張表在 Data Explorer 預覽
• 右鍵 Connect With 取得 Python／R 程式碼，用 Create Script 開成腳本
• 除非必要，不要勾 Include Secrets

內容筆記

圖表進 Plots pane

資料載入後，通常先產生圖。執行畫圖程式時，Positron 會攔截並顯示在右側的 Plots pane。連互動圖也一樣：凡 Positron 判斷為「像圖」的輸出（如 plotly 圖、leaflet 地圖）都進 Plots pane，與靜態圖並列。

import seaborn as sns

sns.scatterplot(weather, x="temp_low_f", y="temp_high_f", hue="city")

library(ggplot2)

ggplot(weather, aes(temp_low_f, temp_high_f, color = city)) +
  geom_point()

下圖是 Python 版的結果：以 temp_low_f 為 x、temp_high_f 為 y 的散佈圖，依城市（Seattle、Denver、Miami、Chicago）上色，整體呈明顯正相關；上方是 Plots 工具列，右側是歷史縮圖條，列有這張 seaborn 圖和先前的一張 ggplot2 圖。

Plots pane 保存整個 session 的圖表歷史，可前後切換並匯出想要的那張：

App 與報告進 Viewer

非圖的輸出，由 Viewer pane 顯示：App 與文件型的網頁內容——平常會用瀏覽器開的東西。經典例子是在 Positron 內執行 Shiny app；渲染後的 Quarto 與 R Markdown 報告也在這裡。

注意：決定去哪個 pane 的不是「是不是 HTML」；圖型的 HTML 輸出（如 plotly、leaflet）進 Plots pane。Viewer 專收行為像 App 或文件的輸出，可直接捲動、點擊、互動，不必離開 IDE。（原文動畫示範：在 Viewer 中調整 Shiny 的輸入控制項，圖即時更新。）

表格：靜態與互動

靜態表格：以純文字列印到 console，適合快速看摘要或前幾列。

weather.head()

輸出為 console 的等寬文字表格：先印 shape: (5, 8)，再列欄名、各欄型別（str、f64、i64）與前五列資料。

互動表格：以 HTML 在 Viewer 渲染，而非 console 純文字。下例用 great_tables 格式化；R 可用 gt 與 DT，其中 DT 另有捲動、排序、搜尋。

from great_tables import GT

GT(weather.head(10))

分類練習（改寫）

關鍵詞

• Plots pane：顯示圖表（含互動圖）並保存歷史的面板。
• Viewer pane：顯示 App 與文件型網頁輸出。
• 靜態表格：純文字列印在 console。
• 互動表格：HTML 表格（great_tables、gt、DT）在 Viewer 渲染。
• Shiny：R／Python 的互動式網頁 App 框架。

可執行要點

• 畫一張圖，練習在 Plots pane 前後翻、Zoom、Copy、Save
• 用 gt 或 DT（R）或 great_tables（Python）做表，確認在 Viewer 出現
• 用 leaflet 或 plotly 畫互動圖，確認它進的是 Plots pane
• 記住那條規則：圖進 Plots、文字進 console、App／文件進 Viewer

內容筆記

Positron 的資料工作流程

哪個功能在哪裡（速查表）

各單元重點回顧

• 第 1 單元：Data Explorer 預覽 .csv、.tsv、.parquet、.xlsx、壓縮檔；Data Grid／Summary panel／Filter bar；Convert to Code。
• 第 2 單元：read_csv（R 的 readr、Python 的 polars）等讀檔；Variables pane 反映即時 session、重啟即清空；%view／View()。
• 第 3 單元：啟用 dataConnections.enabled；Add Connection 存連線（憑證放 OS secret storage）；展開 Tables、雙擊預覽；Connect With 產生 duckdb.connect() 或 dbConnect(duckdb::duckdb(), ...) 程式碼。
• 第 4 單元：Plots pane 的歷史與 Zoom／Copy／Save；Viewer 收 App 與文件型輸出；靜態表格在 console、互動表格在 Viewer。

下一步

• 用你自己的資料集走完整個流程：預覽、載入，並做一張圖與一張表。
• 透過 Data Connections 連上工作中使用的資料庫，用 Connect With 起一支腳本。
• 這些工具仍在演進，常查官方文件：Data Explorer（positron.posit.co/data-explorer.html）與 Data Connections（positron.posit.co/data-connections.html）。

（補充）原課程第 5 單元是在 Positron 內動手實作的 capstone，網頁無文字內容，本筆記未涵蓋；建議自己用上面「下一步」第一項當作練習。

關鍵詞

• Data Explorer：檔案與 data frame 的類試算表檢視器。
• Variables pane：session 物件即時清單。
• Data Connections：資料庫連線管理（預覽功能）。
• Connect With／Convert to Code：兩個「產生程式碼」的入口，前者產生連線、後者重現檢視。
• Plots pane／Viewer／console：三個輸出去處。

可執行要點

• 對一個新資料檔，養成「先預覽、再決定怎麼載入」的習慣
• 載入後用 Variables pane 核對維度與型別
• 把資料庫連線存進 Data Connections，用 Connect With 產生腳本
• 分析時依規則找輸出：圖→Plots、App／報告／HTML 表格→Viewer、列印→console

內容筆記

腳本與 session 的關係

直接在 Console 打幾行程式碼適合快速試算，但真正的分析會寫在腳本（script）裡：像 analysis.py、analysis.R 這種可儲存、可重跑、可分享的純文字檔。

核心心智模型：

從腳本執行程式碼，就是把它送到目前「作用中的（active）」interpreter session——也就是 Console 顯示的那一個，所以程式碼建立的變數就存在那個 session 裡。切到 Console 直接輸入變數名稱即可看到它。

三種執行方式

不必每次都從頭跑到尾。Positron 提供三種粒度。以下用原課的示範腳本為例（Python）：

x = 5
y = 10
print(x + y)

1. 執行一個陳述式（Run one statement）

游標放在任一行上，按 Cmd+Enter（Mac）或 Ctrl+Enter（Windows/Linux）。Positron 會把「目前這個陳述式」送到 Console 執行，然後把游標移到下一個陳述式；連續按同一個快捷鍵，就能一步一步走完整份腳本。

2. 執行選取範圍（Run a selection）

用滑鼠反白一段程式碼，再按同一個快捷鍵 Cmd/Ctrl+Enter，只有反白的部分會被執行（一次全部送進 Console）。適合重跑幾行相關的程式碼，而不想逐句按。

3. 執行整個檔案（Run the whole file）

點編輯器動作列（editor action bar，位於編輯器左上方）的播放鈕（play button，三角形圖示），或按 Cmd+Shift+Enter（Mac）／Ctrl+Shift+Enter（Windows/Linux），整份腳本從頭跑到尾，輸出都出現在 Console。

速查表

可執行要點

• 把分析寫在腳本檔裡，不要只在 Console 打指令
• 邊寫邊測時用 Cmd/Ctrl+Enter 一個陳述式一個陳述式跑
• 要重跑某幾行時，先反白再按 Cmd/Ctrl+Enter
• 腳本完成後用播放鈕或 Cmd/Ctrl+Shift+Enter 從頭到尾跑一次確認
• 跑完切到 Console 輸入變數名稱，確認變數確實在 session 裡

內容筆記

腳本還是 Notebook？

上一單元談腳本；notebook 是另一種組織工作的方式：不是一個程式碼檔，而是一串儲存格（cells），把程式碼、文字、輸出混在同一份文件。兩者沒有誰比較好，只是適合的工作不同。

原課的分類練習：每晚重跑的資料管線、排程報表工作、要保持簡單以便版本控制的小清理步驟 → 腳本；用圖表探索新資料集、不必執行就能讀的分析報告、混合敘述文字／程式碼／圖的文件 → notebook。

Positron Notebook 編輯器

Positron 內建專為資料科學設計的原生 notebook 編輯器，是 .ipynb 的預設編輯器；你在 Positron 已經在用的東西（Variables 窗格、Data Explorer、內嵌說明）在裡面都能用。

建立 notebook 的步驟：

1. 點左上角的 New 下拉選單
2. 選 New Notebook
3. Positron 自動啟動一個 kernel，馬上可寫程式
4. 想換語言或版本，用 notebook 工具列的 kernel picker（kernel 選擇器） 切換

Python 與 R 的 kernel 都可使用。

儲存格：程式碼、Markdown 與輸出

工作循環很簡單：在儲存格寫程式碼 → 執行 → 輸出直接顯示在該儲存格下方。表格、圖、列印結果都會內嵌呈現（原課示範：在 Python 儲存格寫繪圖程式碼、按 Cmd+Enter 執行，圖就出現在儲存格正下方）。

要加敘述，就插入 markdown 儲存格：可寫標題、項目符號、連結；執行該格後會轉成排版好的文字。這就是把一堆程式碼變成可讀分析的關鍵。操作步驟：點新增 markdown 儲存格的按鈕 → 輸入標題與一句話 → 執行該格，內容即渲染成格式化文字。

可執行要點

• 要排程或從頭到尾重跑的工作寫成腳本；探索與寫報告用 notebook
• 用 New > New Notebook 建 notebook，確認 kernel 是想用的語言／版本
• 熟記 Shift+Enter（跑完往下）與 Cmd/Ctrl+Enter（跑完留原地）
• 用 markdown 儲存格寫標題與結論，讓同事不用執行也能讀
• 若覺得 .ipynb 的版本控制 diff 太雜，考慮改用 .qmd

內容筆記

一個專案一個資料夾

實際工作中，腳本與 notebook 應從一開始就有組織良好的家：一個專案一個資料夾，程式碼、資料、輸出放一起。

在 Positron，工作區（workspace）就是你開啟的資料夾；裡面有什麼（程式碼、資料、環境、Git 歷史），Positron 就處理什麼。開啟資料夾後一切都以它為範圍：Explorer 顯示它的檔案、Console 在該資料夾啟動、相對路徑在其中解析。

New Folder from Template

Positron 能替你建好結構良好的專案資料夾。開啟左上角 New 下拉選單（或右上角 Folder Selector），選 New Folder from Template。New 選單內容依序為：New File、New Folder from Template、New Folder from Git、New Window。

對話框引導三個選擇：

1. 選範本：Python Project、R Project、Jupyter Notebook 或 Empty Project
2. 命名資料夾並選擇存放位置
3. 設定選項：用哪個 interpreter、是否建立環境、是否初始化 Git repository

完整流程（以建立附虛擬環境的 Python 專案為例）：開 New 選單 → New Folder from Template → 選 Python Project → 取名 → 接受預設值 → Positron 把新專案開成工作區。R Project 範本流程相同，只差環境那一項。

完成後新資料夾已有一些骨架：

可重現的環境

「專屬環境」值得理解：它解決每位資料科學家遲早會碰到的問題——兩個專案需要同一套件的不同版本。

專案的環境（environment）是屬於該專案的一組隔離套件。每個專案取得它需要的確切版本，為某專案安裝東西不會弄壞別的專案。

Python：venv

Python 專案範本預設建立虛擬環境（.venv 資料夾）。Positron 用標準 venv 工具建構，若已安裝 uv 則用 uv。無論哪種，Positron 都會自動把此環境選為專案的 interpreter，所以你安裝的套件會裝進專案、而非全系統。視窗上方的 interpreter 選擇器會顯示目前環境名稱，讓你隨時知道哪個環境在作用。

my-project/
├── .venv/          # 專案自己的套件與 interpreter
├── .gitignore
└── my-script.py

R：renv

R 專案範本在設定時提供 renv 核取方塊。renv 給專案一個私有套件庫，加上一份鎖定檔（lockfile，renv.lock），記錄你用的確切套件版本，讓別人能重建你的環境。

my-project/
├── renv/           # 專案私有套件庫
├── renv.lock       # 確切套件版本，用於可重現
├── .Rprofile       # 專案開啟時啟用 renv
└── my-script.R

重點對照

關鍵詞

• Workspace（工作區）：你在 Positron 開啟的資料夾
• 環境（environment）：專案專屬、隔離的一組套件
• venv／.venv：Python 虛擬環境；有 uv 時改用 uv 建
• renv／renv.lock：R 的私有套件庫與版本鎖定檔
• Folder Selector：右上角顯示並切換開啟資料夾的按鈕

可執行要點

• 每個新專案用 New > New Folder from Template 建立，而不是空資料夾
• Python 專案保留預設的 .venv，並確認 interpreter 選擇器顯示的是專案環境
• R 專案若需要嚴格可重現（要給別人跑或日後重建），勾選 renv
• 新建專案時順手勾選初始化 Git repository

內容筆記

為什麼要版本控制

你大概手動發明過版本控制：analysis_final.R、analysis_final_v2.R、analysis_final_REALLY.R。Git 用真正的歷史取代這團混亂：它是版本控制系統，記錄專案隨時間的快照；每個快照是可檢視、比較、回復的存檔點，也讓協作變得可管理。

四個詞撐起整個流程：

建立 repository

若用範本建專案時勾選了 Initialize Git repository，就已完成。對既有資料夾，Positron 一鍵搞定：

1. 在活動列（activity bar）開啟 Source Control 檢視（分支線條圖示，見下圖）
2. 按 Initialize Repository

操作後，Positron 建立隱藏的 .git 目錄，Source Control 檢視切換為顯示專案的未追蹤（untracked）檔案，並開始追蹤你在專案中的每個變更。

Stage、Commit、Push

日常循環：編輯檔案後，Source Control 檢視會列出所有有變更的檔案。下圖標註了該檢視各區域：

各區域功能：

步驟：

1. Review（檢視）：點任一檔案，看並排的 diff（差異比對）
2. Stage：按檔案旁的 + 按鈕，選出要快照的檔案
3. Commit：輸入簡短描述並按 Commit；成功後變更清單清空

Push 到遠端

目前的 commit 只存在你的機器。要備份與分享，就把 repository push 到遠端（remote）：託管在 GitHub、GitLab、Bitbucket 等服務的副本。你的機構可能有偏好的主機，Git 流程在各家都相同。

用 GitHub：第一次 push 只需一鍵——Source Control 檢視中的 Publish Branch 按鈕（藍色按鈕，帶雲端上傳圖示）；它會引導你登入，並替你建立遠端 repository。

用其他主機：先在該服務建一個空的 repository，再到 Positron 連接：開啟 Source Control 檢視的 … 選單 → Remote > Add Remote → 貼上 repository URL。之後 push 的方式各處相同。

第一次 push 之後，按鈕會變成 Sync：把你的新 commit 推上去，同時把協作者的新內容拉下來。

日常循環順序

Review 變更（diff）→ Stage 要快照的檔案 → Commit 並附簡短訊息 → Push 到遠端。

關鍵詞

• Git：記錄專案快照的版本控制系統
• Repository：專案資料夾加歷史（.git）
• Stage／Commit／Push：挑變更／存快照／上傳遠端
• Remote（遠端）：GitHub、GitLab、Bitbucket 上的副本
• Publish Branch／Sync：首次推送並建立遠端／之後的雙向同步
• .gitignore：列出 Git 應忽略的檔案

可執行要點

• 確認終端機 git --version 有輸出
• 新專案勾選 Initialize Git repository；舊資料夾用 Source Control 的 Initialize Repository
• 養成「review diff → stage → commit」的小步快跑習慣
• commit 訊息寫成未來的自己看得懂的描述
• 大型或敏感資料先寫進 .gitignore 再 commit
• 要備份分享時用 Publish Branch（GitHub）或 Remote > Add Remote（其他主機），之後用 Sync

內容筆記

日常工作流程

任何新工作都可套用這個五步循環：

1. 開專案：用 New Folder from Template 取得資料夾，內含專屬環境、.gitignore，以及（選用）Git repository
2. 寫並執行程式：用 Cmd/Ctrl+Enter 逐個陳述式執行腳本，再用播放鈕跑整個檔案
3. 在 notebook 探索：想讓結果與敘述緊貼產生它的程式碼時，用儲存格
4. Commit：檢視變更、stage 要放進快照的檔案、附清楚訊息 commit
5. Push：Publish Branch 把 repository 放上 GitHub；之後 Sync 讓本機與遠端同步

速查表

各單元重點回顧

• 腳本（第 1 單元）：腳本是程式碼住的地方，session 才是跑的地方；從腳本執行的程式碼送進 Console 同一個 session，變數也在那裡。
• Notebook（第 2 單元）：用於探索與敘述；腳本用於管線與重用。Positron 原生編輯器是 .ipynb 預設編輯器，支援 Python 與 R kernel，輸出內嵌，Variables 窗格與 Data Explorer 照常運作。
• 專案與環境（第 3 單元）：工作區就是開啟的資料夾；Python 範本預設建 .venv，R 範本可選 renv（renv.lock）。
• Git（第 4 單元）：commit 是快照；用 .gitignore 排除大型或敏感檔案；先決條件是已安裝 Git。

下一步（原課建議）

• 挑一件真實工作，用對的方式起頭：用範本建新資料夾，第一天就帶環境與 Git
• 小而頻繁地 commit，訊息要讓未來的自己看得懂
• 隨時參考 Positron 官方文件（隨工具演進）：Positron Notebook Editor（positron.posit.co/positron-notebook-editor.html）、Folder Templates（positron.posit.co/folder-templates.html）、Git Version Control（positron.posit.co/git.html）、Keyboard Shortcuts（positron.posit.co/keyboard-shortcuts.html）

可執行要點

• 挑一個真實專案，用 New Folder from Template 重建它
• 背熟三個快捷鍵：Cmd/Ctrl+Enter、Cmd/Ctrl+Shift+Enter、Shift+Enter
• 完成第一次 commit 並用 Publish Branch 推上 GitHub
• 閱讀上述四份官方文件
• 自己完成第 5 單元的動手實作（需在 Positron 內進行）