`.qmd`) meant to be used with [Quarto CLI](https://quarto.org).
#### Quarto Flavor Tips & Tricks
#### Quarto flavor
[Quarto](https://quarto.org/) is a new and exciting open-source scientific and technical publishing system, which can extend the range of output formats from your Literate.jl-formatted scripts.
Literate.jl will produce a `.qmd` file, which can be used as input to Quarto CLI to produce a variety of output formats, including HTML, PDF, Word and RevealJS slides.
!!! warning "Experimental feature"
Quarto markdown output is marked as and experimental feature since it has not been
Syntax tips:
widely tested. Quarto-specific syntax may change before Literate version 3 depending on
- `# `(hashtag followed by a space) at the beginning of a line will be stripped and anything that follows will rendered as a markdown, e.g., `# # Header level 1` in your script will be rendered as `# Header level 1` in your .qmd file (ie, it will show as a header). Use this for adding the YAML header at the top or any Markdown blocks in the Quarto guide.
what the community wants and/or needs. If you use this flavor non-interactively (such as
- `##|`(two hashtags followed by a pipe) at the beginning of a line will strip the first hashtag and interpret the remainder of the line as part of the code block. This is useful to provide Quarto commands in computation blocks, e.g., `##! echo: false` would be rendered as `#| echo: false` and would tell Quarto not to "echo" the outputs of the execution (see [Guide: Executions options](https://quarto.org/docs/computations/execution-options.html) for more commands).
automatically building documentation) it is recommended to pin Literate to a good known
- Make sure to always provide the YAML header and specify IJulia kernel when executing the file by Quarto, e.g.,
version.
[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system,
which can extend the range of output formats from your Literate.jl-formatted scripts.
Literate.jl will produce a `.qmd` file, which can be used as input to Quarto CLI to produce
a variety of output formats, including HTML, PDF, Word and RevealJS slides.
##### Literate + Quarto syntax tips
- `# `(hashtag followed by a space) at the beginning of a line will be stripped and anything
that follows will rendered as a markdown, e.g., `# # Header level 1` in your script will
be rendered as `# Header level 1` in your .qmd file (ie, it will show as a header). Use
this for adding the YAML header at the top or any Markdown blocks in the Quarto guide.
- `##|`(two hashtags followed by a pipe) at the beginning of a line will strip the first
hashtag and interpret the remainder of the line as part of the code block. This is useful
to provide Quarto commands in computation blocks, e.g., `##! echo: false` would be
rendered as `#| echo: false` and would tell Quarto not to "echo" the outputs of the
execution (see [Guide: Executions
options](https://quarto.org/docs/computations/execution-options.html) for more commands).
- Make sure to always provide the YAML header and specify IJulia kernel when executing the
file by Quarto, e.g.,
```
```
# ---
# ---
# title: "My Report"
# title: "My Report"
# jupyter: julia-1.9
# jupyter: julia-1.9
# ---
# ---
```
```
Notice how all lines are escaped with a `# ` so Literate.jl knows to strip the hashtags and render it as markdown (see [Authoring Tutorial](https://quarto.org/docs/get-started/authoring/vscode.html#multiple-formats) for more examples)
Notice how all lines are escaped with a `# ` so Literate.jl knows to strip the hashtags
- If any markdown components (eg, headers) are not rendering correctly in your Quarto outputs, make sure they are surrounded by empty lines (e.g., add an empty line before and after the header) to help Quarto parse them correctly
and render it as markdown (see [Authoring
Tutorial](https://quarto.org/docs/get-started/authoring/vscode.html#multiple-formats) for
more examples)
- If any markdown components (e.g. headers) are not rendering correctly in your Quarto
outputs, make sure they are surrounded by empty lines (e.g., add an empty line before and
after the header) to help Quarto parse them correctly
- Run `quarto check` to ensure all is installed correctly (you will need Python, Jupyter, and IJulia kernel, see [Getting Started](https://quarto.org/docs/get-started/computations/vscode.html))
- Run `quarto check` to ensure all is installed correctly (you will need Python, Jupyter,
- Make sure you have the right header specifying which IJulia kernel to use (e.g. `jupyter: julia-1.9`), otherwise Quarto will use the default Python kernel
- Convert your Literate.jl script to a `.qmd` file, e.g. `literate("my_script.jl", flavor = Literate.QuartoFlavor())`
- Make sure you have the right header specifying which IJulia kernel to use (e.g. `jupyter:
- Run Quarto CLI to produce your desired output format, e.g. `quarto render my_script.qmd --to html`
julia-1.9`), otherwise Quarto will use the default Python kernel.
- Convert your Literate.jl script to a `.qmd` file, e.g.
