skills /quarto-design

Python Referenced

quarto-design

Create beautiful Quarto documents including academic articles (Distill-inspired), data blog posts with modern styling, and RevealJS presentations. Use when users request Quarto content, .qmd files, academic papers, blog posts, presentations, or modern styled documents.

Quarto Design Skill

Description: Create professional Quarto documents with three distinct styles: academic articles (Distill-inspired for research papers), data blogs (modern web design for technical writing), and RevealJS presentations (conference-ready slides).

When to use: When users request:

Academic papers or research articles (→ Academic Article style)

Blog posts, tutorials, or technical documentation (→ Data Blog style)

Presentations or slide decks (→ RevealJS style)

Any request mentioning "Quarto" or ".qmd files"

Prerequisites

Required tools: Quarto CLI (installed via bash_tool if needed)

Installation:

hljs bash

# macOS/Linux
brew install quarto

# Or download from https://quarto.org/docs/get-started/

Bundled Resources

References (references/)

Load these when implementing specific document types or needing detailed guidance:

troubleshooting.md - Common issues and solutions for Quarto documents

quick-reference.md - YAML headers, slide layouts, and common patterns

Assets (assets/)

Production-ready Quarto templates and examples to copy:

academic/ - Academic article templates with Distill-inspired design

article.qmd - Complete academic article template (HTML)

distillish.scss - Academic theme stylesheet (wider 1050px layout)

refs.bib - BibTeX bibliography example

paper-pdf.qmd - Basic PDF output template

academic-pdf.qmd - Enhanced PDF template with KOMA-Script, professional tables, math environments

blog/ - Data blog post templates with modern styling

post.qmd - Blog post template

blog.scss - Blog theme stylesheet

presentation/ - RevealJS presentation templates

presentation.qmd - Slide deck template

custom.scss - Presentation theme

presentation-template.qmd - Standalone presentation template

index.qmd - Landing page template

custom.scss - Reusable custom theme

site.scss - Website theme stylesheet

_quarto.yml - Project configuration example

Core Quarto Concepts

Document Formats

Quarto supports multiple output formats from a single source:

HTML: Web pages, documentation sites, interactive content

PDF: Academic papers, reports (requires LaTeX)

RevealJS: Modern HTML presentations

MS Word/PowerPoint: Office compatibility

YAML Front Matter Structure

Every .qmd file starts with YAML metadata:

hljs yaml

---

title: "Document Title"
subtitle: "Optional subtitle"
author: "Author Name"
date: "2025-10-18"
format: html
---

Document Type 1: Academic Articles (Distill-Inspired)

Overview

Use this style for:

Research papers and academic articles

Technical reports with citations

Documents needing margin notes and figures

Publications requiring DOI and author affiliations

Key Features

Distill-inspired layout: Balanced body column (1050px) optimized for modern screens

Serif typography: Source Serif 4 for body, Inter for UI elements

Margin notes: Side annotations like the original Distill framework (HTML only)

Academic metadata: Full author affiliations, ORCID, DOI support

Citation support: BibTeX bibliography with inline citations

Figure captions: Margin or side placement options (HTML only)

Responsive figures: Full-width layout classes for optimal readability

Wider container: 1600px max-width for better screen utilization

⚠️ IMPORTANT: HTML vs PDF Features

Margin notes (::: {.column-margin}) are HTML-only - do NOT use in PDF documents

Side figures (fig-cap-location: margin) are HTML-only - use fig-cap-location: bottom for PDFs

Use article.qmd for HTML output with margin features

Use academic-pdf.qmd for PDF output without margin features

CRITICAL: Common Pitfalls to Avoid

⚠️ SCSS Layer Boundaries Required

SCSS files MUST include /*-- scss:defaults --*/ and /*-- scss:rules --*/ boundaries

Without these, Quarto will fail with "doesn't contain at least one layer boundary" error

See TROUBLESHOOTING.md for details

⚠️ Use page-layout: full Not article

Modern screens need page-layout: full with max-width: 1600px

Old page-layout: article creates excessive white space (760px body on 1920px screens)

Update both YAML (page-layout: full) and SCSS (main.content max-width: 1050px)

⚠️ Figures Too Small by Default

Add figure layout classes (.page-full, .body-outset) to SCSS

Ensure figure img { width: 100%; height: auto; } for proper scaling

Without this, figures appear tiny and unreadable

See TROUBLESHOOTING.md for complete solutions

File Structure

Required files:

article.qmd - Main document
distillish.scss - Academic theme stylesheet
refs.bib - BibTeX bibliography (optional but recommended)

Complete Example

File: article.qmd

hljs yaml

---

title: "An Empirical Study of Widgets"
subtitle: "Evidence from Multi-Region Field Trials"
author:
  - name: "A. Researcher"
    orcid: 0000-0002-1825-0097
    email: a.researcher@example.edu
    affiliations:
      - name: "Dept. of Economics, Example University"
        address: "123 College Ave, City, Country"
  - name: "B. Analyst"
    affiliations:
      - name: "Institute for Advanced Widgets"
date: 2025-10-18
abstract: |
  We investigate widget performance across regions using matched differences-in-differences.
  Results indicate substantial heterogeneity by baseline infrastructure and seasonality.
keywords: [widgets, causal inference, field experiments]
doi: "10.1234/example.doi"
bibliography: refs.bib
link-citations: true
format:
  html:
    theme: [default, distillish.scss]
    page-layout: full          # Use 'full' for better screen usage (not 'article')
    max-width: 1400px           # Control overall container width
    toc: true
    toc-title: "Contents"
    toc-location: right
    number-sections: true
    code-tools: true
    code-link: true
    fig-cap-location: margin
    tbl-cap-location: top
    smooth-scroll: true
    anchor-sections: true
    include-in-header:
      text: |
        <link rel="preconnect" href="https://fonts.googleapis.com">
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link href="https://fonts.googleapis.com/css2?family=Source+Serif+4:opsz,wght@8..60,400;8..60,600;8..60,700&family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
---


## Introduction

Distill-inspired articles emphasize readability, margin notes, and clear structure [@doe2020widgets].
We estimate the canonical model $y_{it} = \alpha_i + \gamma_t + \beta D_{it} + \varepsilon_{it}$.^[Standard errors clustered by site.]

::: {.column-margin}
**Note.** Margin asides are great for context, references, or short proofs.
:::

## Methods

We analyze multi-region panel data using matched DiD and event-study specifications [@angrist2009mostly].

::: callout-note
**Hypothesis 1.** Widgets perform better in high-demand seasons.
:::

### Data

```{r}
#| echo: false
# R code chunk example
x <- 1:5
mean(x)

Event Study

hljs {python}

# Python chunk example
import numpy as np
np.mean([1,2,3])

Results

Table: Summary statistics.

Group	Mean	SD
A	5.1	1.2
B	4.7	1.4

::: {.column-margin}

Schematic of the widget pipeline.

{fig-alt="Pipeline diagram"} Figure. Our pipeline from ingestion to evaluation. :::

::: callout-important Result. We reject the null at 1% across all specifications. :::

Discussion

We find substantial heterogeneity by baseline infrastructure and seasonality. See robustness in Appendix.

References


**File: `distillish.scss`**
```scss
/*-- scss:defaults --*/
/* IMPORTANT: Quarto requires these layer boundaries */

/* Type & palette */
:root {
  --font-serif: "Source Serif 4", ui-serif, Georgia, "Times New Roman", serif;
  --font-sans:  "Inter", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;

  --ink-900: #111827;
  --ink-700: #374151;
  --ink-500: #6b7280;

  --brand-600: #4f46e5; /* subtle indigo accent */
  --ring: rgba(79,70,229,.35);
}

/*-- scss:rules --*/
html, body {
  background: #ffffff;
  color: var(--ink-800, #1f2937);
  scroll-behavior: smooth;
}

body {
  font-family: var(--font-serif);
  font-size: 1.05rem;
  line-height: 1.65;
  max-width: 100%;
}

/* IMPROVED: Wider layout for better screen usage and readability */
.quarto-container {
  max-width: 1600px !important;
  margin: 0 auto;
}

/* IMPROVED: Increased from 760px to 1050px for better readability */
main.content {
  max-width: 1050px;
  padding: 2rem 3rem 3rem;
  margin: 0 auto;
}

article {
  max-width: 1600px;
  margin: 0 auto;
}

/* Floating ToC on the right; keep airy */
#TOC.toc-active {
  background: #fff;
  border: 1px solid rgba(2,6,23,.06);
  border-radius: 12px;
  box-shadow: 0 6px 18px rgba(2,6,23,.06);
  padding: 0.8rem 0.8rem 0.9rem;
}
#TOC .toc-title { font-weight: 700; color: var(--ink-900); }
#TOC a { text-decoration: none; border-bottom: none; }

/* Title block: academic byline look */
.quarto-title-block {
  margin-bottom: 1.8rem;
}
.quarto-title h1, .quarto-title .title {
  font-family: var(--font-serif);
  font-weight: 700;
  letter-spacing: -0.01em;
  color: var(--ink-900);
  font-size: clamp(1.9rem, 1.4rem + 1.8vw, 2.6rem);
  line-height: 1.15;
}
.quarto-title .subtitle { color: var(--ink-500); margin-top: .25rem; }
.quarto-title .quarto-title-authors { margin-top: .6rem; }
.quarto-title .quarto-title-affiliations { color: var(--ink-500); }

/* Abstract block */
.abstract, .abstract > p {
  background: #fbfbff;
  border: 1px solid rgba(79,70,229,.12);
  border-radius: 12px;
  padding: 1rem 1.1rem;
  box-shadow: 0 6px 20px rgba(15,23,42,.04);
}
.abstract > .abstract-title {
  font-family: var(--font-sans);
  font-weight: 700;
  color: var(--ink-900);
  margin-bottom: .35rem;
}

/* Headings: serif with subtle rule under h2 to echo Distill */
h2 {
  font-family: var(--font-serif);
  font-weight: 700;
  color: var(--ink-900);
  margin-top: 2.2rem;
  padding-bottom: .2rem;
  border-bottom: 1px solid rgba(2,6,23,.08);
}
h3 {
  font-family: var(--font-serif);
  font-weight: 600;
  color: var(--ink-700);
  margin-top: 1.6rem;
}

/* Links */
a {
  color: var(--brand-600);
  text-decoration: none;
  border-bottom: 1px solid rgba(79,70,229,.25);
  transition: color .2s ease, border-color .2s ease;
}
a:hover { color: #4338ca; border-bottom-color: rgba(79,70,229,.5); }
a:focus { outline: 3px solid var(--ring); outline-offset: 2px; }

/* Figures: margin captions (Quarto handles placement) */
.figure, figure { margin: 1.2rem 0; }
figcaption {
  font-family: var(--font-sans);
  font-size: .92rem;
  color: var(--ink-500);
}

/* Figure layout classes (Distill-style) - prevents figures from being too small */
figure.page-full {
  width: 100%;
  max-width: 100%;
  margin: 2rem 0;
}

figure.body-outset {
  width: calc(100% + 200px);
  margin-left: -100px;
}

figure.page-outset {
  width: calc(100% + 400px);
  margin-left: -200px;
}

/* Ensure all images scale properly */
figure img {
  width: 100%;
  height: auto;
  display: block;
}

/* Tables: clean, numeric-friendly */
table {
  border-collapse: collapse; width: 100%;
  margin: 1rem 0;
  font-size: .98rem;
}
thead th {
  text-transform: uppercase;
  letter-spacing: .035em;
  font-family: var(--font-sans);
  font-weight: 700;
  color: var(--ink-700);
  border-bottom: 1px solid rgba(2,6,23,.1);
}
td, th { padding: .55rem .6rem; }
tbody tr:nth-child(even) { background: rgba(2,6,23,.025); }

/* Code: sober blocks, serif body + mono code */
code, pre, kbd, samp {
  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}
code {
  background: #f5f7ff;
  border: 1px solid rgba(79,70,229,.12);
  border-radius: 6px;
  padding: .12rem .34rem;
}
pre code {
  display: block;
  background: #0c1224;
  color: #e8ebfb;
  border-radius: 10px;
  padding: 1rem 1.1rem;
  box-shadow: inset 0 12px 28px rgba(0,0,0,.35);
}

/* Callouts: muted academic colors */
.callout { border-radius: 12px; }
.callout-note      { border-left: 5px solid #2563eb; background: #eef2ff; }
.callout-tip       { border-left: 5px solid #059669; background: #ecfdf5; }
.callout-important { border-left: 5px solid #b91c1c; background: #fef2f2; }

/* Margin notes/figures (Distill hallmark) */
.column-margin {
  font-family: var(--font-sans);
  color: var(--ink-700);
  font-size: .95rem;
}
.column-margin .figure img { width: 100%; border-radius: 8px; }

/* Footnotes: compact, readable */
.footnotes {
  border-top: 1px solid rgba(2,6,23,.08);
  margin-top: 2rem; padding-top: .8rem;
  font-size: .95rem;
}
.footnotes ol { padding-left: 1rem; }

/* Dark mode */
.quarto-dark {
  body { background: #0b1020; color: #e6e9f6; }
  main.content { box-shadow: none; }
  #TOC.toc-active { background: #0f152c; border-color: rgba(255,255,255,.08); }
  a { color: #a5b4fc; border-bottom-color: rgba(165,180,252,.35); }
  a:hover { color: #c7d2fe; }
  .abstract { background: #0f152c; border-color: rgba(165,180,252,.18); }
  h2 { border-bottom-color: rgba(255,255,255,.08); color: #f3f4f6; }
  thead th { border-bottom-color: rgba(255,255,255,.1); color: #e5e7eb; }
  tbody tr:nth-child(even) { background: rgba(255,255,255,.03); }
  code { background: rgba(255,255,255,.06); color: #eaeaff; border-color: rgba(255,255,255,.08); }
  pre code { background: #0b1020; }
  .callout-note { background: rgba(99,102,241,.12); }
  .callout-tip { background: rgba(16,185,129,.12); }
  .callout-important { background: rgba(239,68,68,.12); }
}

File: refs.bib (Example bibliography)

hljs bibtex

@article{doe2020widgets,
  title={Widgets in the Wild: A Field Study},
  author={Doe, Jane and Roe, Richard},
  journal={Journal of Widget Science},
  year={2020},
  volume={12},
  number={3},
  pages={123-145},
  doi={10.1000/jws.2020.123}
}

@book{angrist2009mostly,
  title={Mostly Harmless Econometrics: An Empiricist's Companion},
  author={Angrist, Joshua D and Pischke, Jörn-Steffen},
  year={2009},
  publisher={Princeton University Press}
}

Academic Article Patterns

Margin Notes

hljs markdown

Regular paragraph text in the main body.

::: {.column-margin}
**Side note.** Additional context or clarification appears in the margin.
:::

Margin Figures

hljs markdown

::: {.column-margin}
![Caption text](image.png){width=100%}
*Note.* Additional description if needed.
:::

Math Equations

hljs markdown

Inline math: $\beta = \frac{x}{y}$

Display math:
$$
y_{it} = \alpha_i + \gamma_t + \beta D_{it} + \varepsilon_{it}
$$

Footnotes

hljs markdown

Main text with citation.^[This is a footnote with standard errors clustered by site.]

Citations

hljs markdown

According to @doe2020widgets, the results show...

Multiple citations [@doe2020widgets; @angrist2009mostly].

Multiple Authors

hljs yaml

author:
  - name: "First Author"
    orcid: 0000-0002-1825-0097
    email: first@university.edu
    affiliations:
      - name: "Department, University"
        address: "Address"
  - name: "Second Author"
    affiliations:
      - name: "Another Institution"

Academic PDF Output (Enhanced)

For submission to journals or preprint archives, use the enhanced academic-pdf.qmd template which provides publication-quality output suitable for economics, statistics, and social science journals.

⚠️ PDF-SPECIFIC GUIDANCE:

DO NOT use margin notes (::: {.column-margin}) - these are HTML-only features

DO NOT use fig-cap-location: margin - use fig-cap-location: bottom for PDFs

DO NOT use side charts - place all figures inline within the text

PDF documents use standard single-column layout without margin annotations

Key Features of Enhanced PDF Template:

KOMA-Script (scrartcl) document class for professional typography

Palatino font (mathpazo) with matching mathematics

Professional tables with booktabs, dcolumn for decimal alignment

Standard layout - no margin features, optimized for print and journal submission

Comprehensive math packages (amsmath, amssymb, amsthm)

Custom environments for theorems, propositions, definitions

Better spacing with microtype, optimized margins (1.25" left/right)

Publication-ready with proper citations, footnotes, and appendices

Quick Start:

hljs bash

# Copy the enhanced template
cp assets/academic/academic-pdf.qmd my-paper.qmd

# Render to PDF
quarto render my-paper.qmd

The template includes example content showing regression tables, equations, appendices, and proper academic formatting. Customize the YAML front matter for your paper.

Academic PDF Output (Standard)

For submission to journals or preprint archives, you can also create PDFs from scratch. Quarto can generate beautiful PDFs that rival LaTeX documents.

Prerequisites: Install a LaTeX distribution:

macOS: brew install --cask mactex or BasicTeX

Linux: sudo apt-get install texlive-full

Windows: Install MiKTeX from https://miktex.org/

PDF-Ready YAML Configuration

File: paper.qmd (for PDF output)

hljs yaml

---

title: "An Empirical Study of Widgets"
subtitle: "Evidence from Multi-Region Field Trials"
author:
  - name: "A. Researcher"
    orcid: 0000-0002-1825-0097
    email: a.researcher@example.edu
    affiliation: 
      - name: "Dept. of Economics, Example University"
        address: "123 College Ave"
        city: "City"
        postal-code: "12345"
  - name: "B. Analyst"
    affiliation:
      - name: "Institute for Advanced Widgets"
date: today
abstract: |
  We investigate widget performance across regions using matched differences-in-differences.
  Results indicate substantial heterogeneity by baseline infrastructure and seasonality.
  
  **Keywords**: widgets, causal inference, field experiments
  
  **JEL Codes**: C23, D12, L86
thanks: "We thank seminar participants at Example University and anonymous reviewers for helpful comments."
bibliography: refs.bib
csl: apa.csl  # or chicago-author-date.csl, aea.csl, etc.
link-citations: true
format:
  pdf:
    documentclass: article
    classoption: [11pt, a4paper]
    geometry:
      - margin=1in
    fontfamily: mathpazo  # Palatino font
    fontsize: 11pt
    linestretch: 1.5  # 1.5 or 2 for double spacing
    number-sections: true
    toc: false
    colorlinks: true
    linkcolor: blue
    citecolor: blue
    urlcolor: blue
    keep-tex: true  # Keep .tex file for submission
    include-in-header:
      text: |
        \usepackage{setspace}
        \usepackage{booktabs}
        \usepackage{dcolumn}
        \usepackage{graphicx}
        \usepackage{float}
        \usepackage{amsmath}
        \usepackage{amssymb}
        \usepackage[labelfont=bf]{caption}
---


## Introduction

Your paper content here with professional PDF formatting...

Dual Output (HTML + PDF)

For maximum flexibility, configure both HTML and PDF outputs:

hljs yaml

---

title: "Research Paper Title"
author: "Author Name"
format:
  html:
    theme: [default, distillish.scss]
    toc: true
    toc-location: right
    number-sections: true
  pdf:
    documentclass: article
    geometry:
      - margin=1in
    fontsize: 11pt
    number-sections: true
    colorlinks: true
bibliography: refs.bib
---

Render both:

hljs bash

quarto render paper.qmd --to html
quarto render paper.qmd --to pdf

Or render all formats:

hljs bash

quarto render paper.qmd

PDF-Specific Formatting Options

Document Classes (common in economics/academia):

hljs yaml

format:
  pdf:
    documentclass: article  # Standard article
    # documentclass: scrartcl  # KOMA-Script (European style)
    # documentclass: memoir    # Book-length works

Journal-Specific Styles:

hljs yaml

format:
  pdf:
    # American Economic Association
    template: aea-template.tex
    csl: aea.csl
    
    # Nature/Science format
    documentclass: nature
    
    # Working paper style
    documentclass: article
    classoption: [12pt, letterpaper]

Fonts (professional options):

hljs yaml

format:
  pdf:
    fontfamily: mathpazo   # Palatino (classic)
    # fontfamily: libertinus # Modern, readable
    # fontfamily: lmodern    # Latin Modern (LaTeX default)
    # fontfamily: times      # Times New Roman
    # fontfamily: bookman    # Bookman

Spacing and Margins:

hljs yaml

format:
  pdf:
    linestretch: 2        # Double spacing
    geometry:
      - top=1in
      - bottom=1in
      - left=1.5in
      - right=1in
    indent: true          # Paragraph indentation

Table of Contents:

hljs yaml

format:
  pdf:
    toc: true
    toc-depth: 3
    toc-title: "Contents"
    lof: true  # List of figures
    lot: true  # List of tables

PDF Tables and Figures

Professional Tables:

hljs markdown

| Variable | Mean | SD | Min | Max |
|----------|------|----|----|-----|
| Income   | 45.2 | 12.3 | 18.0 | 95.0 |
| Age      | 38.5 | 10.2 | 22.0 | 65.0 |

: Summary Statistics {#tbl-summary}

See @tbl-summary for descriptive statistics.

Regression Tables (with code):

hljs markdown

```{python}
#| label: tbl-regression
#| tbl-cap: "OLS Regression Results"

import pandas as pd
from stargazer.stargazer import Stargazer

# Create regression table
results = [model1, model2, model3]
stargazer = Stargazer(results)
```

Figures:

hljs markdown

![Treatment Effect by Quarter](images/event_study.pdf){#fig-event width=80%}

As shown in @fig-event, the treatment effect increases over time.

PDF-Specific Features

Page Breaks:

hljs markdown

Content on page 1.

\newpage

Content on page 2.

Landscape Pages (for wide tables):

hljs markdown

\begin{landscape}

| Very | Wide | Table | With | Many | Columns |
|------|------|-------|------|------|---------|
| 1    | 2    | 3     | 4    | 5    | 6       |

\end{landscape}

Appendix:

hljs markdown

# Main Paper Content

# References {-}

\newpage

# Appendix {-}

## Appendix A: Additional Results {-}

Supplementary tables and figures...

Custom Headers/Footers:

hljs yaml

format:
  pdf:
    include-in-header:
      text: |
        \usepackage{fancyhdr}
        \pagestyle{fancy}
        \fancyhead[L]{Working Paper}
        \fancyhead[R]{\today}
        \fancyfoot[C]{\thepage}

Citation Styles for PDFs

Download CSL files from https://github.com/citation-style-language/styles

Common styles:

hljs yaml

csl: apa.csl                    # APA 7th edition
csl: chicago-author-date.csl    # Chicago style
csl: aea.csl                    # American Economic Association
csl: nature.csl                 # Nature journal
csl: harvard.csl                # Harvard referencing

Math and Equations

Inline math: $\beta_1 x_i + \epsilon_i$

Display equations:

hljs markdown

$$
y_{it} = \alpha_i + \gamma_t + \beta D_{it} + X_{it}'\delta + \varepsilon_{it}
$$ {#eq-did}

Equation @eq-did shows our DiD specification.

Aligned equations:

hljs markdown

\begin{align}
Y &= X\beta + \epsilon \\
\epsilon &\sim N(0, \sigma^2 I)
\end{align}

Common PDF Issues and Solutions

Issue: Long URLs breaking page margins

hljs yaml

format:
  pdf:
    include-in-header:
      text: |
        \usepackage{xurl}  # Better URL line breaking

Issue: Code blocks too wide

hljs markdown

```{python}
#| eval: false
#| code-line-numbers: false

# Keep code concise or use line breaks
very_long_function_name(
    parameter1=value1,
    parameter2=value2
)
```

Issue: Tables too wide

hljs markdown

Use `kable()` or `gt()` with `latex_options = c("scale_down")`

Issue: Figures not appearing

hljs markdown

- Use PDF, PNG, or JPG (not SVG for LaTeX)
- Check file paths are relative
- Ensure images exist before rendering

Rendering Commands

Render PDF:

hljs bash

quarto render paper.qmd --to pdf

Keep intermediate files (for debugging):

hljs bash

quarto render paper.qmd --to pdf --keep-tex

Verbose output (see LaTeX errors):

hljs bash

quarto render paper.qmd --to pdf --log-level debug

Academic PDF Template

Complete submission-ready example:

hljs yaml

---

title: "Your Paper Title"
subtitle: "Subtitle if needed"
author:
  - name: "First Author"
    email: "first@university.edu"
    affiliation: "University Name"
  - name: "Second Author"
    affiliation: "Other Institution"
date: "2025-10-18"
abstract: |
  Your abstract here (150-250 words).
  
  **Keywords**: keyword1, keyword2, keyword3
  
  **JEL Classification**: C23, D12
thanks: "Acknowledgments go here."
bibliography: references.bib
csl: apa.csl
format:
  pdf:
    documentclass: article
    classoption: [11pt, letterpaper]
    geometry:
      - margin=1in
    fontfamily: mathpazo
    fontsize: 11pt
    linestretch: 2
    number-sections: true
    toc: false
    colorlinks: true
    keep-tex: true
    include-in-header:
      text: |
        \usepackage{setspace}
        \usepackage{booktabs}
        \usepackage{dcolumn}
        \usepackage{float}
        \usepackage{amsmath}
        \usepackage{amssymb}
---


# Introduction

Your introduction here...

# Literature Review

Review of prior work [@author2023]...

# Data and Methodology

## Data

Description of data sources...

## Empirical Strategy

Our identification strategy follows @seminal2020...

# Results

## Main Results

Table @tbl-main presents our main findings...

## Robustness Checks

Alternative specifications...

# Conclusion

Summary and implications...

# References {-}

::: {#refs}
:::

\newpage

# Appendix {-}

## Appendix A: Additional Tables {-}

Supplementary material...

Tips for Academic PDFs

Use simple table syntax - Complex HTML tables won't render well in PDF
Keep code output clean - Hide or format code output for readability
Use PDF-compatible images - Convert SVGs to PDF or PNG
Test early - Render PDF frequently to catch formatting issues
Keep .tex file - Use keep-tex: true for journal submission requirements
Use standard LaTeX packages - Stick to well-supported packages
Preview before final - Check page breaks, widows/orphans, figure placement

Document Type 2: Data Blogs (Modern Web Design)

Overview

Use this style for:

Blog posts and tutorials

Technical documentation

Data science notebooks

Modern web content with interactive elements

Key Features

Modern MDX-inspired design: Hero sections, feature cards, badges

Sans-serif typography: Inter for readability

Interactive elements: Code tabs, collapsible sections, callout boxes

Gradients and shadows: Professional depth without clutter

Responsive grid layouts: Multi-column content organization

Dark mode support: Accessible across preferences

File Structure

Required files:

post.qmd or index.qmd - Main blog post
blog.scss - Modern blog stylesheet
Optional: _quarto.yml for multi-post blogs

Complete Example

File: post.qmd

hljs yaml

---

title: "Getting Started with Data Visualization"
subtitle: "A Modern Approach to Charting"
author: "Data Scientist"
date: "2025-10-18"
categories: [tutorial, visualization, python]
image: "thumbnail.png"
format:
  html:
    theme: [default, blog.scss]
    toc: true
    toc-location: right
    code-tools: true
    code-copy: true
    code-overflow: wrap
    df-print: paged
    smooth-scroll: true
---


::: hero
# Modern Data Visualization

Learn how to create beautiful, interactive charts with Python and Observable Plot.

<div class="hero-buttons">
  <a href="#getting-started" class="btn-primary">Get Started</a>
  <a href="https://github.com/example/repo" class="btn-secondary">View on GitHub</a>
</div>
:::

## Getting Started {#getting-started}

::: callout-tip
## Quick Tip
Use the code copy button to grab any code snippet instantly.
:::

### Installation

::: {.panel-tabset}
## pip
```bash
pip install plotly matplotlib seaborn

conda

hljs bash

conda install plotly matplotlib seaborn

poetry

hljs bash

poetry add plotly matplotlib seaborn

:::

Your First Chart

hljs {python}

#| code-fold: true
#| code-summary: "Show the code"

import plotly.express as px
import pandas as pd

# Create sample data
df = pd.DataFrame({
    'category': ['A', 'B', 'C', 'D'],
    'values': [23, 45, 56, 78]
})

# Create interactive bar chart
fig = px.bar(df, x='category', y='values',
             title='Sample Bar Chart')
fig.show()

Key Features

::: {.features} ::: {.feature-card}

🎨 Beautiful

Modern design that looks great everywhere :::

::: {.feature-card}

⚡ Fast

Optimized rendering for instant results :::

::: {.feature-card}

🔧 Flexible

Customize every aspect of your charts ::: :::

Advanced Topics

<details> <summary>Click to expand: Performance optimization</summary>

When working with large datasets:

Use data sampling for initial exploration

Enable caching with freeze: auto

Consider using Parquet format for data storage

</details>

::: callout-warning

Breaking Change

Version 2.0 introduces a new API. See the migration guide. :::

Conclusion

<span class="badge">Advanced</span> <span class="badge good">Recommended</span>

You're now ready to create stunning visualizations!

R

hljs r

library(tidyverse)
data <- read_csv('file.csv')

Julia

hljs julia

using CSV, DataFrames
data = CSV.read("file.csv", DataFrame)

:::


**Badges**
```markdown
<span class="badge">Tutorial</span>
<span class="badge good">Beginner-Friendly</span>
<span class="badge warn">Beta</span>
<span class="badge info">Updated</span>

Collapsible Details

hljs markdown

<details>
<summary>Advanced Configuration Options</summary>

Hidden content that expands on click:
- Option 1: Description
- Option 2: Description
- Option 3: Description

</details>

Code Folding

hljs markdown

```{python}
#| code-fold: true
#| code-summary: "Show the code"

# Hidden by default, click to expand
import matplotlib.pyplot as plt
plt.plot([1,2,3], [1,4,9])
plt.show()


## Document Type 3: RevealJS Presentations

### Overview

Use this style for:
- Conference presentations
- Lecture slides
- Business presentations
- Interactive demos

### Key Features

- **Modern slide design**: Clean layouts with subtle gradients
- **Title slide gradient**: Eye-catching opening
- **Multiple layouts**: Two-column, three-column, quote slides, image slides
- **Incremental reveals**: Animated list items and fragments
- **Speaker notes**: Hidden presenter information
- **Code highlighting**: Line-by-line code emphasis

### File Structure

**Required files**:
1. `presentation.qmd` - Main presentation
2. `custom.scss` - Presentation theme

### Complete Example

**File: `presentation.qmd`**
```yaml
---
title: "Modern Data Science"
subtitle: "Tools and Techniques for 2025"
author: "Your Name"
institute: "Your Organization"
date: today
format:
  revealjs:
    theme: [default, custom.scss]
    slide-number: true
    transition: slide
    transition-speed: fast
    highlight-style: github
    preview-links: true
    controls: true
    progress: true
    history: true
    center: true
    footer: "<span>Your Organization</span><span>{title}</span>"
    logo: images/logo.png
    css: extras.css
---

# Introduction {.section-header background-color="#1e3a5f"}

## About This Talk

::: incremental
- Modern data science landscape
- Key tools and frameworks
- Practical examples
- Best practices
:::

::: notes
Remember to introduce yourself and mention the agenda.
Ask if anyone has questions before starting.
:::

## Two-Column Layout

::: columns
::: column
### Left Side
- Point 1
- Point 2
- Point 3
:::

::: column
### Right Side
![Data pipeline](images/pipeline.png)
:::
:::

# Key Concepts {.section-header background-color="#2563eb"}

## Feature Cards

::: {.grid-3}
::: {.feature-card}
**Fast**  
Lightning-quick processing
:::

::: {.feature-card}
**Scalable**  
Handles any data size
:::

::: {.feature-card}
**Simple**  
Easy to learn and use
:::
:::

## Quote Slide

::: {.quote-slide}
> "The best way to predict the future is to invent it."
>
> — Alan Kay
:::

## Code Example

```{.python code-line-numbers="1-2|3-4|5"}
import pandas as pd
import numpy as np

data = pd.read_csv('large_dataset.csv')
result = data.groupby('category').mean()

Fragments

::: {.fragment} This appears first :::

::: {.fragment .fade-in} This fades in :::

::: {.fragment .highlight-red} This gets highlighted :::

Conclusion {.section-header background-color="#059669"}

Summary

Covered modern tools

Showed practical examples

Shared best practices

::: notes Thank the audience. Mention where slides will be available. Open for questions. :::


**File: `custom.scss`**
```scss
/*-- scss:defaults --*/
// Color palette
$body-bg: #f8f9fa;
$body-color: #333333;
$link-color: #4a90e2;
$link-color-hover: #357abd;
$presentation-heading-color: #1e3a5f;
$code-block-bg: #f5f5f5;
$code-color: #e83e8c;

// Typography
$presentation-font-size-root: 40px;
$presentation-heading-font: 'Inter', system-ui, -apple-system, sans-serif;
$presentation-font: 'Inter', system-ui, -apple-system, sans-serif;

/*-- scss:rules --*/
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');

.reveal {
  font-family: $presentation-font;
  color: $body-color;
  background: $body-bg;

  // Headings
  h1, h2, h3, h4, h5, h6 {
    font-family: $presentation-heading-font;
    letter-spacing: -0.02em;
    font-weight: 600;
  }

  h2 {
    color: $presentation-heading-color;
    border-bottom: 3px solid $link-color;
    padding-bottom: 0.5rem;
    margin-bottom: 1.5rem;
  }

  // Code styling
  code {
    background-color: #f0f0f0;
    padding: 0.2em 0.4em;
    border-radius: 3px;
    font-size: 0.85em;
  }

  pre code {
    background-color: $code-block-bg;
    padding: 1rem;
    border-radius: 8px;
    border-left: 4px solid $link-color;
  }

  // Emphasis
  strong {
    color: $presentation-heading-color;
    font-weight: 600;
  }

  em {
    color: #555;
    font-style: italic;
  }

  // Links
  a {
    color: $link-color;
    text-decoration: none;
    transition: color 0.2s;
    
    &:hover {
      color: $link-color-hover;
      text-decoration: underline;
    }
  }

  // Slides
  .slides section {
    transition: all 0.3s ease;
    text-align: left;
  }

  // Lists
  ul, ol {
    line-height: 1.8;
  }

  li {
    margin-bottom: 0.5rem;
  }
}

// Title slide gradient
.reveal .slide-background.title-slide {
  background: linear-gradient(135deg, #1e3a5f 0%, #4a90e2 100%);
}

.title-slide h1,
.title-slide h2,
.title-slide p {
  color: white !important;
  border: none !important;
}

/*-- Layout Utilities --*/
.columns {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 2rem;
  align-items: start;
}

.grid-3 {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1.5rem;
}

.quote-slide {
  display: grid;
  place-items: center;
  text-align: center;
  background: linear-gradient(135deg, #dbeafe, #eef2ff);
  border-radius: 1rem;
  padding: 3rem;
  height: 100%;
}

.quote-slide blockquote {
  font-size: 1.8rem;
  font-style: italic;
  color: $presentation-heading-color;
  border: none;
  margin: 0;
}

// Feature cards
.feature-card {
  background: white;
  border: 1px solid #e5e7eb;
  border-radius: 12px;
  padding: 1.5rem;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05);
  transition: transform 0.2s, box-shadow 0.2s;
  
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
  }
}

// Section headers
.section-header h1 {
  color: white;
  font-size: 3rem;
}

// Dark mode
.reveal.dark-mode {
  background: #1a202c;
  color: #e2e8f0;

  h1, h2, h3, h4, h5, h6 {
    color: #f7fafc;
  }

  code {
    background-color: #2d3748;
    color: #f7fafc;
  }

  .feature-card {
    background: #2d3748;
    border-color: #4a5568;
  }
}

Presentation Patterns

Section Divider

hljs markdown

# Major Section {.section-header background-color="#1e3a5f"}

Two Columns

hljs markdown

::: columns
::: column
Left content
:::

::: column
Right content
:::
:::

Three-Column Grid

hljs markdown

::: {.grid-3}
::: {.feature-card}
Content 1
:::

::: {.feature-card}
Content 2
:::

::: {.feature-card}
Content 3
:::
:::

Incremental Lists

hljs markdown

::: incremental
- Appears first
- Appears second
- Appears third
:::

Speaker Notes

hljs markdown

## Slide Content

::: notes
These notes only appear in speaker view.
Press 's' during presentation.
:::

Code Highlighting

hljs markdown

```{.python code-line-numbers="1-2|3-4"}
line 1
line 2
line 3
line 4


**Fragments**
```markdown
::: {.fragment}
Default fragment
:::

::: {.fragment .fade-in}
Fade in
:::

::: {.fragment .highlight-red}
Highlight red
:::

Best Practices

Choosing the Right Document Type

Use Academic Articles when:

Writing research papers or technical reports

Need citations and bibliography

Want margin notes and side figures

Targeting academic journals or preprints

Use Data Blogs when:

Creating tutorials or how-to guides

Building technical documentation

Writing blog posts or articles

Need modern web design with interactive elements

Use RevealJS when:

Presenting at conferences or meetings

Creating lecture slides

Building pitch decks

Need speaker notes and incremental reveals

File Organization

project/
├── _quarto.yml              # Project configuration
├── academic/                # Academic articles
│   ├── article.qmd
│   ├── distillish.scss
│   └── refs.bib
├── blog/                    # Blog posts
│   ├── post-1/
│   │   ├── index.qmd
│   │   └── blog.scss
│   └── post-2/
│       └── index.qmd
├── presentations/           # Slide decks
│   ├── talk-1.qmd
│   └── custom.scss
└── images/                  # Shared assets

Common Metadata Options

All document types:

hljs yaml

date: today  # or "2025-10-18"
toc: true
toc-location: right  # or left, body
number-sections: true
code-tools: true
code-copy: true
smooth-scroll: true

Academic articles only:

hljs yaml

bibliography: refs.bib
csl: apa.csl
link-citations: true
fig-cap-location: margin
abstract: |
  Your abstract text
keywords: [keyword1, keyword2]
doi: "10.1234/example"

Blog posts only:

hljs yaml

categories: [tag1, tag2]
image: "thumbnail.png"
code-fold: true
code-overflow: wrap
df-print: paged

Presentations only:

hljs yaml

slide-number: true
transition: slide  # or fade, zoom
footer: "Footer text"
logo: "logo.png"
preview-links: true

Rendering Commands

Preview (live reload):

hljs bash

quarto preview document.qmd

Render to HTML:

hljs bash

quarto render document.qmd

Render entire project:

hljs bash

quarto render

Render to PDF (requires LaTeX):

hljs bash

quarto render document.qmd --to pdf

Troubleshooting

Issue: Styles not applying

Solution: Ensure SCSS file is in same directory or properly referenced in YAML

Check YAML indentation (use spaces, not tabs)

Issue: Fonts not loading

Solution: Check internet connection for Google Fonts

Add font import in include-in-header section

Issue: Images not displaying

Solution: Use relative paths from document location

Ensure image files exist in specified location

Issue: Code not executing

Solution: Verify language kernel is installed (R, Python, Julia)

Check execute options in YAML

Issue: Citations not working

Solution: Verify refs.bib file exists and is referenced in YAML

Ensure citation keys match those in .bib file

Use @citationkey syntax for in-text citations

Output Instructions

When using this skill, Claude should:

Determine document type by asking or inferring from context:
Create complete, working files:
Include in YAML:
Add helpful comments:
Structure content appropriately:
Save files to /mnt/user-data/outputs/ with descriptive names
Provide clear instructions:

Quick Start Templates

Minimal Academic Article

hljs yaml

---

title: "Article Title"
author: "Author Name"
date: today
bibliography: refs.bib
format:
  html:
    theme: [default, distillish.scss]
    page-layout: full          # Important: use 'full' not 'article'
    max-width: 1600px          # Control container width (wider for modern screens)
    toc: true
    toc-location: right
---


## Introduction

Your content here.

Minimal Blog Post

hljs yaml

---

title: "Post Title"
author: "Author Name"
date: today
format:
  html:
    theme: [default, blog.scss]
    code-copy: true
---


Your content here.

Minimal Presentation

hljs yaml

---

title: "Presentation Title"
author: "Your Name"
date: today
format:
  revealjs:
    theme: [default, custom.scss]
---


# First Slide

Content here.

## Second Slide

More content.

Resources

Official Documentation: https://quarto.org/docs/

Gallery: https://quarto.org/docs/gallery/

RevealJS Guide: https://quarto.org/docs/presentations/revealjs/

Publishing: https://quarto.org/docs/publishing/

Extensions: https://quarto.org/docs/extensions/

Remember: The goal is to create beautiful, functional Quarto documents that match the requested style. Always provide complete working examples with all necessary files, and ensure users can immediately preview and customize the output.

Related Categories

← All Skills

Quarto Design Skill

References (references/)

Assets (assets/)

Document Formats

YAML Front Matter Structure

Overview

Key Features

CRITICAL: Common Pitfalls to Avoid

File Structure

Complete Example

Event Study

Academic Article Patterns

Academic PDF Output (Enhanced)

Academic PDF Output (Standard)

PDF-Ready YAML Configuration

Dual Output (HTML + PDF)

PDF-Specific Formatting Options

PDF Tables and Figures

PDF-Specific Features

Citation Styles for PDFs

Math and Equations

Common PDF Issues and Solutions

Rendering Commands

Academic PDF Template

Tips for Academic PDFs

Overview

Key Features

File Structure

Complete Example

Your First Chart

🎨 Beautiful

⚡ Fast

🔧 Flexible

Data Blog Patterns

Conclusion {.section-header background-color="#059669"}

Presentation Patterns

Choosing the Right Document Type

File Organization

Common Metadata Options

Rendering Commands

Troubleshooting

Minimal Academic Article

Minimal Blog Post

Minimal Presentation

Related Categories