The shell is often called the “terminal” on macOS, by which people mean Terminal.app. One way to launch is via Spotlight Search. Type Command + space and start typing “terminal”
There are no fewer than 4 possible shells you can end up in. Unless you know better, you almost certainly want to be in a Git Bash shell, which you conveniently installed during the setup of Git. To open it, Open the Start menu and type “Git Bash” into the search bar. The icon for Git Bash and the words “Git Bash Desktop App” will appear. Click on the icon or the words “Git Bash Desktop App” to open Git Bash.
Might depend on the flavor, but I assume as a Linux user, you know how to at least open the shell.
Some basic commands to try out:
pwd (print working directory). Shows directory or “folder” you are currently operating in.
ls (list files). Shows the files in the current working directory. This is equivalent to looking at the files in your Finder/Explorer/File Manager.
cd (change directory). Allows you to navigate through your directories by changing the working directory of your shell. Examples:
# show content$ lsa b# navigate to folder a$ cd a# navigate back to parent$ cd ..# go to home directory$ cd ~
($ indicates an input line, # a comment and everything else shows an output)
echo display a line of text. This is convenient if you need to write something quickly to a new file
Quarto by itself is a tool used in the shell. To get help, use quarto --help
quarto--help
Usage: quarto
Version: 1.3.361
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
create-project [dir] - Create a project for rendering multiple documents
convert <input> - Convert documents to alternate representations.
pandoc [args...] - Run the version of Pandoc embedded within Quarto.
run [script] [args...] - Run a TypeScript, R, Python, or Lua script.
add <extension> - Add an extension to this folder or project
install [target...] - Installs an extension or global dependency.
publish [provider] [path] - Publish a document or project. Available providers include:
check [target] - Verify correct functioning of Quarto installation.
help [command] - Show this help or the help of a sub-command.
For each command, you can get additional help like so
quarto render --help
Usage: quarto render [input] [args...]
Version: 1.3.361
Description:
Render files or projects to various document types.
Options:
-h, --help - Show this help.
-t, --to - Specify output format(s).
-o, --output - Write output to FILE (use '--output -' for stdout).
--output-dir - Write project output to DIR (path is project relative)
-M, --metadata - Metadata value (KEY:VALUE).
--site-url - Override site-url for website or book output
--execute - Execute code (--no-execute to skip execution).
-P, --execute-param - Execution parameter (KEY:VALUE).
--execute-params - YAML file with execution parameters.
--execute-dir - Working directory for code execution.
--execute-daemon - Keep Jupyter kernel alive (defaults to 300 seconds).
--execute-daemon-restart - Restart keepalive Jupyter kernel before render.
--execute-debug - Show debug output for Jupyter kernel.
--use-freezer - Force use of frozen computations for an incremental file render.
--cache - Cache execution output (--no-cache to prevent cache).
--cache-refresh - Force refresh of execution cache.
--no-clean - Do not clean project output-dir prior to render
--debug - Leave intermediate files in place after render.
pandoc-args... - Additional pandoc command line arguments.
--log <level> - Path to log file
--log-level <level> - Log level (info, warning, error, critical)
--log-format <format> - Log format (plain, json-stream)
--quiet - Suppress console output.
--profile - Active project profile(s)
Commands:
help [command] - Show this help or the help of a sub-command.
Examples:
Render Markdown: quarto render document.qmd
quarto render document.qmd --to html
quarto render document.qmd --to pdf --toc
Render Notebook: quarto render notebook.ipynb
quarto render notebook.ipynb --to docx
quarto render notebook.ipynb --to pdf --toc
Render Project: quarto render
quarto render projdir
Render w/ Metadata: quarto render document.qmd -M echo:false
quarto render document.qmd -M code-fold:true
Render to Stdout: quarto render document.qmd --output -
You can achieve the same in both cases by writing help instead of --help. We recommend you stick with the latter, since it is a standard way of obtaining help for a cli tool.
Exercise 3
Find the right command to check if your Quarto installation is ok and run it to detect potential problems
Install TeX support
It might be, that you do not have a TeX distribution installed, which is needed to create PDF documents. To check, run the following command.
quarto list tools
The output could look something like this:
[✓] Inspecting toolsTool Status Installed Latest chromium Not installed --- 869685 tinytex Not installed --- v2023.06
The output suggests, that TinyTeX is not installed, which is the recommended engine for Quarto. However, this does not necessarily mean, that you do not already have a TeX eninge on your computer. If you regularly work in LaTeX, you should be fine. If not, or if you want to use TinyTex instead, run the following
quarto install tool tinytex
If you eventually find that you do not have the latest version of TinyTeX installed, you can update it like so
quarto update tinytex
Footnotes
The terminology can become a bit confusing in this area. An extremely elaborate try to disentangle all terms can be found in this askubuntu thread.↩︎