Skip to content

quarto-quickstart.md

Latest commit

 

History

History
338 lines (229 loc) · 12.8 KB

quarto-quickstart.md

File metadata and controls

338 lines (229 loc) · 12.8 KB

Quarto Quickstart

A practical guide to using this template — install Quarto, build the site, add chapters, and switch between full and selective publishing.

1. What this template gives you

  • A Quarto website project (3-level collapsible sidebar) configured for long-form books.
  • Two render profiles: full (entire book) and selection (subset for previews / drafts).
  • A custom Lua filter (opencode-prompt.lua) that turns special code blocks (opencode, agent, skill, bash) into styled cards with a copy button.
  • Companion CSS (styles.css) with light/dark variants for the semantic blocks.
  • Two style guides under docs/style-guides/ covering Quarto callouts and content modules.

The template is structure-only — you bring the chapters.

2. Install Quarto

Quarto runs on macOS, Linux, and Windows.

# macOS
brew install --cask quarto

# Linux (deb/rpm available on the download page)
# Windows: use the installer from quarto.org

Verify:

quarto --version

If you intend to render PDFs, also install a TeX distribution. The simplest way is:

quarto install tinytex

For Chinese / CJK PDF output you will additionally need LuaLaTeX and CJK fonts (e.g. Noto Serif CJK SC, Noto Sans CJK SC). HTML output has no such requirement.

3. Project layout

your-book/
├── _quarto.yml             # main config (shared settings, format, filters)
├── _quarto-full.yml        # profile: render the whole book
├── _quarto-selection.yml   # profile: render a subset
├── opencode-prompt.lua     # Lua filter for semantic code blocks
├── styles.css              # custom CSS (callouts, code block styling, dark mode)
├── index.md               # landing page
├── images/                 # shared images, including book-logo.png
├── chapters/
│   └── chapter-template/   # one folder per chapter
│       ├── index.md       # chapter cover (title, learning goals, intro)
│       ├── section-1.md   # one file per section
│       ├── section-2.md
│       └── summary.md     # chapter summary
├── docs/
│   ├── quarto-quickstart.md          # this file
│   ├── semantic-code-blocks.md       # how the Lua filter works
│   └── style-guides/
│       ├── callout-style-guide.md
│       └── content-module-guide.md
└── scripts/
    └── new-chapter.sh      # scaffold a new chapter (see §7)

_quarto.yml holds settings that apply to every build (theme, fonts, filters, crossref labels, language). The two profile files supply the bits that change between builds: which files are rendered (project.render) and what shows in the sidebar (website.sidebar.contents).

4. Render and preview

The two commands you will use most:

# Live preview with auto-reload — best for writing
quarto preview

# One-shot build into _book/
quarto render

Preview opens a local server and rebuilds whenever you save a .md. Render produces static HTML in the output directory.

Other useful invocations:

# Render only HTML
quarto render --to html

# Build with a specific profile (see §5)
quarto render --profile selection

# Render a single file (fast iteration)
quarto render chapters/chapter-template/section-1.md

# Preview without opening a browser, on a fixed port
quarto preview --no-browser --port 5455

Output goes to _book/ by default (configured via project.output-dir in _quarto.yml). To serve the built site locally without quarto preview:

npx serve _book -p 8080
# or
python -m http.server 8080 -d _book

5. Profiles: full vs selection

This template uses Quarto's profile system to keep one source tree producing different outputs.

Profile File Use when
full _quarto-full.yml Default. Render the entire book.
selection _quarto-selection.yml Preview a subset, share a sample, draft mode.

_quarto.yml declares the default profile:

profile:
  default: full

So quarto render and quarto preview use full unless you override:

quarto render --profile selection
quarto preview --profile selection

What lives in a profile file

Each profile must define two things:

  1. project.render — the list (or globs) of source files to compile.
  2. website.sidebar.contents — the sidebar tree for those files.

Everything else (theme, CSS, filters, crossref labels) stays in _quarto.yml and is shared.

Editing the selection profile

Open _quarto-selection.yml and replace the chapter-template entries with the files you actually want in the preview. Anything not listed in project.render is skipped, and anything not listed in sidebar.contents is hidden from navigation.

Tip: keep the lists in the two files in sync conceptually — if a chapter exists in project.render but not in sidebar.contents, it builds but is unreachable from the sidebar.

6. Adding content

Frontmatter conventions

Every .md starts with YAML frontmatter that supplies the title:

---
title: "Chapter 1: Getting Started"
---

For sections:

---
title: "1.1 First Section"
---

Do not add a leading # Heading after the frontmatter — Quarto already renders the title. Adding one creates a duplicate H1.

Writing chapters

Inside a chapter folder, the typical files are:

  • index.md — chapter cover: title, learning objectives, short intro.
  • section-1.md, section-2.md, … — one per section.
  • summary.md — wrap-up.

You can also add experiment.md, exercises.md, cases.md, etc. — there is nothing magical about the names; what matters is that they appear in the active profile.

Images

Put chapter-specific images under chapters/chapter-N/images/ and reference them with relative paths:

![Caption](images/diagram.png){#fig-diagram}

See @fig-diagram.

Shared assets (book logo, cover) live in the top-level images/ folder.

7. Adding a new chapter

The bundled helper script makes scaffolding a chapter quick:

./scripts/new-chapter.sh 2 "Chapter Title"

The first argument is just the chapter number — the script prefixes it with chapter- to produce the directory name (e.g. chapters/chapter-2/).

It will:

  1. Create chapters/chapter-2/ by copying the entire chapters/chapter-template/ directory, which includes a starter index.md, section-1.md, section-2.md, and summary.md (plus an empty images/ folder). Delete or rename any files you don't need.
  2. Print the YAML snippets you need to paste into _quarto-full.yml (and optionally _quarto-selection.yml).

Manual workflow — equivalent if you do not use the script:

  1. mkdir -p chapters/chapter-2/images

  2. Create index.md, section-1.md, section-2.md, summary.md with frontmatter as shown above.

  3. In _quarto-full.yml, append to project.render:

    - chapters/chapter-2/index.md
- chapters/chapter-2/section-*.md
- chapters/chapter-2/summary.md

  4. In the same file, extend website.sidebar.contents:

    - section: chapters/chapter-2/index.md
  contents:
    - chapters/chapter-2/section-1.md
    - chapters/chapter-2/section-2.md
    - chapters/chapter-2/summary.md

  5. Run quarto preview to verify it shows up in the sidebar.

8. Style guides and conventions

The template ships with two reference documents under docs/style-guides/:

  • callout-style-guide.md — when to use which callout (note, tip, warning, important, caution), syntax, and conversion rules from older blockquote styles.
  • content-module-guide.md — patterns for concept definitions, file paths, structural diagrams (directory trees, tables, configs), step-by-step instructions, and worked examples.

These were written for a Chinese-language book and use Chinese examples, but the patterns translate directly. Use them as a checklist when drafting or reviewing chapters.

For the custom code blocks (opencode, agent, skill, bash), see semantic-code-blocks.md.

9. Common configuration tweaks

Section numbering

Manual numbering in titles (第 1 章, 1.1 …, Chapter 1, 1.2 …) collides with Quarto's auto-numbering. The template ships with number-sections: false. If you prefer Quarto-driven numbers, flip it on and remove the manual prefixes from your title: fields.

Crossref prefixes

_quarto.yml localizes crossref prefixes:

crossref:
  fig-prefix: "图"
  tbl-prefix: "表"
  eq-prefix: "公式"
  sec-prefix: "节"

Change these to English (Figure, Table, Equation, Section) for English-language books.

Mermaid

Inside .md source files, use the plain ```mermaid fence — Quarto will render it to an SVG diagram on the client side:

```mermaid
flowchart LR
  A --> B --> C
```

If you need a numbered/captioned figure for cross-referencing, wrap the fence in a labeled div:

::: {#fig-flow}
```mermaid
flowchart LR
  A --> B --> C
```

Diagram caption goes here.
:::

See @fig-flow.

Note: the executable ```{mermaid} form (with curly braces) only works inside .qmd source files, because Quarto requires .qmd for files containing executable code. This template uses plain .md files.

Building a PDF

The template ships with a starter PDF profile, _quarto-pdf.yml, alongside the HTML profiles. To build a PDF:

quarto render --profile pdf

Output is written under _book/ (a .pdf file alongside the HTML — Quarto picks an output name based on the project title).

Required tools:

  • A TeX distribution. The simplest is TinyTeX, which Quarto can install for you: 
    quarto install tinytex
  • LuaLaTeX (provided by TinyTeX and full TeX Live distributions).

If you already have TinyTeX from a prior year, run quarto install tinytex --update (or ~/Library/TinyTeX/bin/.../tlmgr update --self --all) to refresh — cross-year tlmgr operations fail with a "remote repository has newer release" error.

CJK font caveat. Because _quarto.yml defaults to lang: zh, the PDF profile uses documentclass: ctexbook and references CJKmainfont: "PingFang SC". You will need a Chinese-capable font installed on the build machine:

  • macOS: PingFang SC, Songti SC, and Heiti SC are pre-installed.
  • Linux / CI: install Noto Serif CJK SC and Noto Sans CJK SC (e.g. apt install fonts-noto-cjk) and set CJKmainfont: "Noto Serif CJK SC".

For an English-only book, switch documentclass to scrreport and remove the CJK font keys (the profile contains a commented block showing how).

Lua filter caveat. The shipped opencode-prompt.lua filter emits RawBlock html only — those custom block types (opencode, agent, skill, bash) will appear as plain code in PDF output until the filter grows a LaTeX/PDF code path. For pure HTML books this does not matter; if you need styled blocks in PDF too, plan to extend the filter or strip those filters when rendering PDF.

Practical advice. Treat HTML as the primary deliverable and PDF as secondary: nail down chapter structure, sidebar, callouts, and code-block styling against quarto preview, and only stress-test PDF once content has stabilized. PDF iteration is much slower (LaTeX typesetting, font discovery, page-break tuning).

Adding extra format options

If you prefer everything in one file, you can fold a format.pdf: block into _quarto.yml instead of using a separate profile. The dedicated _quarto-pdf.yml is recommended because it keeps PDF-only options (engine, font names, document class) out of the HTML build path.

10. Troubleshooting

  • Preview not refreshing. Stop and restart quarto preview, or use --no-browser --port <new-port> to dodge a stuck cache.
  • Missing pages in sidebar. Check that the file is listed in both project.render and website.sidebar.contents of the active profile.
  • Duplicate titles in output. Remove leading # Heading lines from .md files; the YAML title: already provides the heading.
  • opencode / agent / skill / bash blocks render as plain code. The Lua filter is missing from _quarto.yml. Confirm the filters: - opencode-prompt.lua block is present and the .lua file is at the project root.

11. Where to go next

  • Skim docs/style-guides/callout-style-guide.md and docs/style-guides/content-module-guide.md before drafting your first chapter.
  • Read docs/semantic-code-blocks.md to understand the four custom block types.
  • Browse chapters/chapter-template/ for a working layout you can copy.
  • Quarto's full reference: https://quarto.org/docs/guide/.