Merge pull request #63 from NBISweden/quarto-intro

Quarto intro

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        <type> [target]       - Automate document or project setup tasks.          
+    add        <extension>           - Add an extension to this folder or project         
+    update     [target...]           - Updates an extension or global dependency.         
+    remove     [target...]           - Removes an extension.                              
+    convert    <input>               - 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 <SUBCOMMAND> 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).