index.qmd

title	subtitle	format
Welcome to Quarto	A scientific and technical publishing system built on Pandoc	html include-in-header docs/download/_download.html

## Introduction Quarto^[®]{.trademark}^ is an [open-source](https://github.com/quarto-dev/quarto-cli) scientific and technical publishing system built on [Pandoc](https://pandoc.org). Quarto documents are authored using [markdown](https://en.wikipedia.org/wiki/Markdown), an easy to write plain text format. In addition to the core capabilities of Pandoc, Quarto includes: 1. Embedding code and output from Python, R, and JavaScript via integration with [Jupyter](https://jupyter.org/), [Knitr](https://yihui.org/knitr/), and [Observable](https://github.com/observablehq/). 2. A variety of extensions to Pandoc markdown useful for technical writing including cross-references, sub-figures, layout panels, hoverable citations and footnotes, callouts, and more. 3. A project system for rendering groups of documents at once, sharing options across documents, and producing aggregate output like [websites](docs/websites/website-basics.qmd) and [books](docs/books/book-basics.qmd). 4. Authoring using a wide variety of editors and notebooks including [JupyterLab](docs/tools/jupyter-lab.qmd), [RStudio](docs/tools/rstudio.qmd), and [VS Code](docs/tools/vscode.qmd). 5. A [visual markdown editor](docs/visual-editor/) that provides a productive writing interface for composing long-form documents. To get a quick flavor of what you can create with Quarto, check out the [Gallery](docs/gallery/) of examples. The overall design of Quarto is influenced heavily by [R Markdown](https://rmarkdown.rstudio.com/), however unlike R Markdown the architecture is language agnostic. In its current iteration, Quarto can render plain markdown, Jupyter Notebooks, and Knitr documents. ## Hello, Quarto Here's a simple example of a markdown document that includes a cross-referenced figure generated by [Matplotlib](https://matplotlib.org/): --- title: "Matplotlib Demo" author: "Norah Smith" date: "May 22nd, 2021" format: html: code-fold: true jupyter: python3 --- ## Polar Axis For a demonstration of a line plot on a polar axis, see @fig-polar. ```{{python}} #| label: fig-polar #| fig-cap: "A line plot on a polar axis" import numpy as np import matplotlib.pyplot as plt r = np.arange(0, 2, 0.01) theta = 2 * np.pi * r fig, ax = plt.subplots(subplot_kw={'projection': 'polar'}) ax.plot(theta, r) ax.set_rticks([0.5, 1, 1.5, 2]) ax.grid(True) plt.show() ``` Here's what the document looks like when rendered by Quarto: {.border .preview-image fig-alt="This is an example of a Quarto document with one section containing one data visualization. At the top of the document in larger text is the title ('Matplotlib Demo'). On the following line in normal-sized text is the author (Norah Smith), and underneath that is the document date (May 22, 2021). Underneath that in large text is the section title, 'Polar Axis'. Afterwards, there is a line of text: 'For a demonstration of a line plot on a polar axis, see fig.1'. Under that is a triangle pointing at the word 'Code', indicating a code-fold button. Below this is a plot of a straight line in polar coordinates. There is a large black circle containing 4 smaller concentric gray circles with 4 axes overlaid on it. Angle measurements are indicated on the largest outer circle, starting at 0 degrees on the right side of the circle and continuing around the circle in 45 degree increments; 90 degrees is labeled at the top of the circle, 180 degrees is labeled at the left of the circle, and 270 degrees is labeled at the bottom of the circle. There are four axes on this circle, each of which are straight lines that run from one side of the circle through the origin. One axis begins at 0 degrees, goes through the origin, and ends at 180 degrees. The next starts at 45 degrees and ends at 225 degrees. Another one starts at 90 degrees and ends at 270 degrees. The last starts at 135 degrees and ends at 315 degrees. Each of the four gray concentric circles has a label on their border between the 0 degree and 45 degree marks indicating the length of their radius. From smallest to largest, the circles are labeled 0.5, 1, 1.5, and 2.0. There is a blue line that starts at the origin (the intersection of the four axes) and spirals outward. Below this plot is the caption: 'Figure 1: A line plot on a polar axis.'"} You can render documents using the `quarto` command line tool: ``` bash quarto render matplotlib-demo.qmd ``` Embedded code blocks (in this case some Python code that generates a plot) are run by Quarto, and their output is included in the final document generated by Pandoc. Note that we use the file extension `.qmd` to indicate that this isn't a plain markdown file but rather one with embedded computations to be run by Quarto. Don't worry if all the mechanics of this example aren't obvious, the main takeaway is that Quarto enables you to enhance [Pandoc markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) documents with features useful for scientific and technical communication including executable code, cross-references, and much more. ::: callout-note While this example demonstrates rendering a `.qmd` markdown file, Quarto can also directly render existing computational document formats like Jupyter Notebooks (.ipynb) and R Markdown (.Rmd). ::: ## Getting Started ``` include docs/download/_download.md ``` [Installation](docs/getting-started/installation.qmd) will get you up and running with Quarto (including additional dependencies required for computational documents). [Quarto Basics](docs/getting-started/quarto-basics.qmd) will help you learn the core mechanics of rendering markdown as well as how to specify document formats and options. [Running Code](docs/computations/running-code.qmd) explains how to work with Jupyter and Knitr based computational documents in more depth. [JupyterLab](docs/tools/jupyter-lab.qmd), [RStudio](docs/tools/rstudio.qmd), and [VS Code](docs/tools/vscode.qmd) help you create an optimal workflow in your code editing tool(s) of choice. [Visual Editor](docs/visual-editor/) describes how to use Quarto's visual interface for composing long-form markdown documents. [Gallery](docs/gallery/) provides examples of articles, reports, presentations, interactive documents, websites, and books using various formats.