-
Notifications
You must be signed in to change notification settings - Fork 309
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
6 additions
and
61 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,76 +1,21 @@ | ||
<!-- -*- mode: gfm -*- --> | ||
|
||
# Quarto | ||
|
||
Quarto is an academic, scientific, and technical publishing system built on [Pandoc](https://pandoc.org). | ||
|
||
In addition to the core capabilities of Pandoc, Quarto includes: | ||
|
||
1. Support for embedding output from R and Python via integration with knitr and Jupyter. | ||
1. Support for embedding output from Julia, Python, and R via integration with [Jupyter](https://jupyter.org/) and [knitr](https://yihui.org/knitr/) . | ||
2. A project system for rendering groups of documents at once. | ||
3. Flexible ways to specify rendering options, including project-wide options and per-format options. | ||
4. Cross references for figures, tables, equations, sections, listings, proofs, and more. | ||
5. Sophisticated layout for panels of figures, tables, and other content. | ||
6. Automatic installation of required LaTeX packages when rendering PDF output. | ||
|
||
Quarto is currently in alpha development, so not generally recommended for everyday use! Documentation on using Quarto will be available soon. | ||
|
||
## Installation | ||
|
||
You can install an alpha-build of the Quarto CLI (command-line interface) from here: | ||
|
||
<https://github.com/quarto-dev/quarto-cli/releases/tag/v0.1.35> | ||
|
||
You can verify that Quarto has been installed correctly with: | ||
|
||
``` bash | ||
$ quarto help | ||
``` | ||
|
||
To install the development version of the Quarto CLI, git clone this repo then run the configure script for your platform (`linux`, `macos`, or `windows`). | ||
|
||
``` bash | ||
$ git clone https://github.com/quarto-dev/quarto-cli | ||
$ cd quarto-cli | ||
$ ./configure-macos.sh | ||
``` | ||
|
||
## Usage | ||
|
||
You can use the `quarto render` command to render plain markdown, R Markdown, or a Jupyter notebook: | ||
|
||
``` bash | ||
$ quarto render plain.md | ||
$ quarto render rmarkdown.Rmd | ||
$ quarto render jupyter.ipynb | ||
$ quarto render jupyter.md | ||
``` | ||
|
||
Note that the last variation renders a [Jupyter Markdown](https://jupytext.readthedocs.io/en/latest/formats.html#jupytext-markdown) document, which is pure markdown representation of a Jupyter notebook. A markdown file is denoted as Jupyter markdown via the inclusion of a `jupyter` entry in YAML front matter indicating the Jupyter kernel or Jupytext configuration for the document (e.g. `jupyter: python3`). | ||
|
||
See `quarto render help` for additional documentation on using the `render` command. | ||
|
||
### Formats | ||
|
||
Quarto uses Pandoc front-matter to define which format to render and what options to use for that format. For example, this document defines HTML and PDF output (where HTML is the default because it is listed first): | ||
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 it's current iteration, Quarto can render plain markdown, Rmd documents, and Jupyter Notebooks. | ||
|
||
``` yaml | ||
--- | ||
title: "My Document" | ||
author: "Jane Doe" | ||
toc: true | ||
toc-depth: 2 | ||
format: | ||
html: | ||
fontsize: 14 | ||
margin-left: 100px | ||
margin-right: 100px | ||
html-math-method: katex | ||
pdf: | ||
documentclass: report | ||
margin-left: 30mm | ||
margin-right: 30mm | ||
--- | ||
``` | ||
Quarto is currently in alpha development, so not generally recommended for everyday use! | ||
|
||
All pandoc formats (see `pandoc --list-output-formats`) are supported. | ||
For additional documentation, see the [Quarto Wiki](https://github.com/quarto-dev/quarto-cli/wiki). | ||
|
||
The YAML metadata provided for each format may include any pandoc [metadata variables](https://pandoc.org/MANUAL.html#variables) or [command-line defaults](https://pandoc.org/MANUAL.html#default-files). All YAML metadata can be provided globally for all formats (as illustrated with `toc` and `toc-depth` above) or on a per-format basis. |