diff --git a/quarto/intro.qmd b/quarto/intro.qmd new file mode 100644 index 0000000..1ece5d1 --- /dev/null +++ b/quarto/intro.qmd @@ -0,0 +1,190 @@ +# Introduction to Quarto + +## What is Quarto + +### The Quarto CLI + +0. In order to use Quarto you need to install Quarto first. The + easiest way is to get the package for your desired platform + directly from + [https://quarto.org/docs/get-started/](https://quarto.org/docs/get-started/). + If you need the most recent version you can also get the source + code from the + [quarto-cli](https://github.com/quarto-dev/quarto-cli) git + repository. + +1. After Quarto is installed on your system you can get an overview of + all subcommonds when you type `quarto help` (followed by pressing + ENTER) in a terminal: + +``` + Usage: quarto + Version: 1.4.553 + + Description: + + Quarto CLI + + Options: + + -h, --help - Show this help. + -V, --version - Show the version number for this program. + + Commands: + + render [input] [args...] - Render files or projects to various document types. + preview [file] [args...] - Render and preview a document or website project. + serve [input] - Serve a Shiny interactive document. + create [type] [commands...] - Create a Quarto project or extension + use [target] - Automate document or project setup tasks. + add - Add an extension to this folder or project + update [target...] - Updates an extension or global dependency. + remove [target...] - Removes an extension. + convert - Convert documents to alternate representations. + pandoc [args...] - Run the version of Pandoc embedded within Quarto. + typst [args...] - Run the version of Typst embedded within Quarto. + run [script] [args...] - Run a TypeScript, R, Python, or Lua script. + install [target...] - Installs a global dependency (TinyTex or Chromium). + uninstall [tool] - Removes an extension. + tools - Display the status of Quarto installed dependencies + publish [provider] [path] - Publish a document or project to a provider. + check [target] - Verify correct functioning of Quarto installation. + help [command] - Show this help or the help of a sub-command. +``` + +There are many Quarto subcommands available. You can get more details +about each subcommand when you type `quarto help` in the +terminal: e.g. `quarto render help` provides detailed information +about rendering files or projects to various document types - +including some usage examples at the end. + +## Authoring + +### Render vs preview + +The `quarto render` and `quarto preview` commands are used to generate +output from a Quarto (.qmd) document. + +The `quarto render` command generates output in all formats specified +in your YAML header (e.g., pdf, html, word) or in your command line with +the option `--to`, while the `quarto preview` command only generates +output in a format suitable for viewing in a web browser. + +In a typical workflow, you would use the `quarto preview` command to +view the output of your document as you are working on it. + +```bash +quarto preview my.qmd +``` + +This command will start a local web server and open a web browser to +view the output of the document. The web server will automatically +update the output as you make changes to the document. + +Once you are ready to produce your final output you can use the +`quarto render` command. + +```bash +quarto render my.qmd +``` + +## Computations + +Quarto lets you perform computations within your notebook. This is +typically done using code blocks denoted by three backticks followed +by the language you're using in curly brackets. + +````{.markdown} +```{{python}} +1 + 1 +``` +```` + +Quarto supports computations in several languages: + +- [Python](https://quarto.org/docs/computations/python.html) +- [R](https://quarto.org/docs/computations/r.html) +- [Julia](https://quarto.org/docs/computations/julia.html) +- [Observable](https://quarto.org/docs/computations/ojs.html) + +Additional languages can also be supported through other Jupyter +kernels (see Engines below). See this page for a list of [Jupyter +kernels](https://gist.github.com/chronitis/682c4e0d9f663e85e3d87e97cd7d1624). + +The languages and packages used in your computations must be available +in your `render` environment, and are often installed through other +means, for example using `conda` or a container platform. + +Loaded packages and variables defined within a code block are also +accessible from other code blocks, including inline code blocks. For +example, here we create a figure within a div (`:::`) and reference +the `x` variable in both the figure caption and text body. + +````{.markdown} +:::{#fig-plot-alt} + +```{{r}} +x <- 1:10 +y <- x^2 + +plot(x, y) +``` + +A plot of $x$ against it's square (n = `{r} length(x)`). +::: + +This paragraph refers to @fig-plot-alt for a plot of $y=x^2$ +based on `{r} length(x)` points. +```` + +The output of computations can be controlled using [execution +options](https://quarto.org/docs/computations/execution-options.html). +These can be set for the whole document in the yaml front-matter at +the top of the document, e.g., + +````{.yml} +--- +title: My Experiment +execute: + echo: false +--- +```` + +Alternatively, execution options can be specified within each code +block, e.g., + +````{.markdown} +```{{python}} +#| echo: false +#| output: asis +print(""" +## Introduction + +This is Markdown text. +""") +``` +```` + +Computations can also be used to dynamically generate Markdown or HTML +content by using the `output` format `asis`. For example, document +sections can be dynamically generated from an input file. + +## Document types + +Quarto can generate a number of document output types, including PDF, +HTML, and MS Word. The output format can be set on the command line +via the `--to` option, or by setting the `format` option in the yaml +configuration. For instance, the following header configuration will +generate PDF output: + +````{.yml} +--- +format: pdf +--- +```` + +### Presentation + +In addition to regular document formats, there is support for formats +that will generate presentations, including `revealjs` (HTML), `pptx` +(PowerPoint) and `beamer` (LaTeX/PDF).