Skip to content
Snippets Groups Projects
Commit 84f3df6a authored by GD's avatar GD
Browse files

improve quarto presentation and include revealjs slides

parent ea4c3a1e
Branches
No related tags found
No related merge requests found
Pipeline #542 passed
---
title: "Website template using Quarto"
title: "Quarto: markdown-based document creation/edition"
subtitle: "Static website generator and more"
---
This is a Quarto website using Markdown files to write contents.
<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License (CC BY 4.0)</a>
## What is Quarto?
Per the Quarto [official website](https://quarto.org):
......@@ -23,35 +28,58 @@ Per the Quarto [official website](https://quarto.org):
- [Create websites](https://quarto.org/docs/websites/) based on (R|Q)markdown files
- [Full documentation](https://quarto.org/docs/guide/)
- [Detailed tutorials](https://quarto.org/docs/guide/)
- [Full documentation](https://quarto.org/docs/reference/)
- [R Interface to 'Quarto' Markdown Publishing System](https://quarto-dev.github.io/quarto-r/)
---
### Under the hood
:::: {.columns}
::: {.column width="70%"}
[pandoc](https://pandoc.org/): "a universal document converter"
:::
::: {.column width="30%"}
![Pandoc supported formats](img/pandoc_format.jpg){width=40%}
:::
::::
## Creating a website with quarto
- Command line: `quarto create-project <my_website_name> --type website`
Command line:
- Rstudio `new project` -> `quarto website`
```bash
quarto create-project <my_website_name> --type website
```
## Rendering your website from Markdown sources
Rstudio:
- Command line:
+ only build: `quarto render <my_website_name>`
+ build + preview: `quarto preview <my_website_name>`
`new project` -> `quarto website`
![Rstudio project types](img/rstudio_new_project.jpg){fig-align="center"}
### Quarto markdown files
- Rstudio: `Render` button to build + preview
- Use Quarto markdown (`.qmd`) files to write your contents, following the [standard Markdown syntax](https://quarto.org/docs/authoring/markdown-basics.html) with the additional features to **run computations**, similarly to [Rmarkdown](https://rmarkdown.rstudio.com/).
- R console:
+ only build: [`quarto::quarto_render()`](https://quarto-dev.github.io/quarto-r/reference/quarto_render.html)
+ build + preview: [`quarto::quarto_preview()`](https://quarto-dev.github.io/quarto-r/reference/quarto_preview.html)
- Also natively render Rmarkdown (`.Rmd`) files and Jupyter notebook (`.ipynb`) files.
### Rendering your website from notebook sources
- Command line:
+ only build: `quarto render <path/to/my_website_name>`
+ build + preview: `quarto preview <path/to/my_website_name>`
## Quarto markdown files
- Rstudio: `Render` button to build + preview (when editing any notebook file)
+ run a local server that updates the website when any notebook (`.qmd`, `.Rmd`, `.ipynb`) file is edited (but not any included markdown `.md` file)
Use Quarto markdown (`.qmd`) files to write your contents, following the [standard Markdown syntax](https://quarto.org/docs/authoring/markdown-basics.html) with the additional features to run computations, similarly to [Rmarkdown](https://rmarkdown.rstudio.com/).
- See also [`quarto`](https://quarto-dev.github.io/quarto-r/) R package: [`quarto::quarto_render()`](https://quarto-dev.github.io/quarto-r/reference/quarto_render.html) and [`quarto::quarto_preview()`](https://quarto-dev.github.io/quarto-r/reference/quarto_preview.html)
### Running computations
### Running computations inside (Q|R)markdown sources
You can include code chunks between ```` ```{r} ```` and ```` ``` ```` markers (with the name of the language between `{ }`), and the code as well as its output will be included, e.g. in R:
......@@ -60,7 +88,11 @@ x <- seq(0, 10, 0.1)
plot(x, cos(x))
```
[R](https://quarto.org/docs/computations/r.html), [Python](https://quarto.org/docs/computations/python.html) and [Julia](https://quarto.org/docs/computations/julia.html) programming languages are supported, e.g. in Python:
[R](https://quarto.org/docs/computations/r.html), [Python](https://quarto.org/docs/computations/python.html) and [Julia](https://quarto.org/docs/computations/julia.html) programming languages are supported.
---
Another example in Python:
```{python}
a = []
......@@ -69,11 +101,123 @@ for i in range(10):
print(a)
```
> Note:
>
> - Running R codes requires the `knitr` R package.
> - Running Python codes requires the `reticulate` R package when using Rstudio, and the `jupyter` Python package when using the command line interface.
### Requirements for computation
- Running R codes requires the `knitr` R package.
- Running Python codes requires the `reticulate` R package when using Rstudio, and the `jupyter` Python package when using the command line interface.
### Additional tips
You can include markdown (`.md`) files inside `.qmd` file with the following `{{< include my_file.md >}}`.
You can include markdown (`.md`) files inside any (Q|R)markdown file with the following
`{{< include my_file.md >}}`
### Configuring your quarto project
:::: {.columns}
::: {.column width="40%"}
File `_quarto.yml`
More complicated example: [quarto website config](https://github.com/quarto-dev/quarto-web/blob/main/_quarto.yml)
:::
::: {.column width="60%"}
```yml
project:
type: website
website:
title: "Quarto Website Template"
navbar:
left:
- href: index.qmd
text: Home
- about.qmd
- href: presentation/slides_presenting_quarto.qmd
text: Presentation
format:
html:
theme: cosmo
css: styles.css
toc: true
```
:::
::::
### Website and content organization
- All notebooks (`.qmd`, `.Rmd`, `.ipynb`) in any sub-directory are rendered in the website (e.g. `subdir/myfile.Rmd` automatically rendered to `subdir/myfile.html`)
- Other content are automatically included in the website file tree (e.g. included images)
## Automatic gitlab pages setup
### CI setup
`.gitlab-ci.yml` file for automatic gitlab pages generation:
```yml
pages:
image: registry.gitlab.com/quarto-forge/docker/quarto
script:
- quarto render --execute --to html --output-dir public
artifacts:
paths:
- public
```
### Docker images
- [`rocker`](https://rocker-project.org/): "Docker Containers for the R Environment"
```yml
image: rocker/rstudio
```
- [Quarto container](https://gitlab.com/quarto-forge/docker)
```yml
# Python
image: registry.gitlab.com/quarto-forge/docker/python
# R
image: registry.gitlab.com/quarto-forge/docker/rstats
# both
image: registry.gitlab.com/quarto-forge/docker/polyglot
```
## Other type of contents
### Documents
- [pdf](https://quarto.org/docs/output-formats/pdf-basics.html)
- [html](https://quarto.org/docs/output-formats/html-basics.html)
- [book](https://quarto.org/docs/books/)
- [interactivity](https://quarto.org/docs/interactive/): [Observable JS](https://quarto.org/docs/interactive/ojs/), [shiny app](https://quarto.org/docs/interactive/shiny/), [Jupyter Widgets](https://quarto.org/docs/interactive/widgets/jupyter.html) or [htmlwidgets](https://quarto.org/docs/interactive/widgets/htmlwidgets.html)
### Customization
- [css](https://quarto.org/docs/visual-editor/content.html#css-styles) and local `styles.css` file
- [extensions](https://quarto.org/docs/extensions/): template for journal articles, presentations, web pages
Example: <https://computo.sfds.asso.fr/published-paper-tsne/>
### Alternatives
R-based:
- [Rmarkdown](https://rmarkdown.rstudio.com/) + [`knitr`](https://yihui.org/knitr/) R package with LaTeX style or CSS style, but file per file rendering (requires to manually manage multiple files rendering into a website)
- [`pkgdown`](https://pkgdown.r-lib.org/), [`blogdown`](https://pkgs.rstudio.com/blogdown/), [`bookdown`](https://pkgs.rstudio.com/bookdown/) R packages for Rmarkdown-based document generation (with a specific aim)
Other:
- [Hugo](https://gohugo.io/) static website generator based on markdown (restricted to web content creation, multiple community templates)
- [jekyll](https://jekyllrb.com/) static website generator
- and more...
......@@ -8,6 +8,8 @@ website:
- href: index.qmd
text: Home
- about.qmd
- href: presentation/slides_presenting_quarto.qmd
text: Presentation
format:
html:
......
img/pandoc_format.jpg

82.4 KiB

img/rstudio_new_project.jpg

46.5 KiB

......@@ -2,6 +2,4 @@
title: "Quarto Website Template"
---
This is a Quarto website using Markdown files to write contents.
{{< include README.md >}}
presentation/img/pandoc_format.jpg

82.4 KiB

presentation/img/rstudio_new_project.jpg

46.5 KiB

---
author: "Ghislain Durif (<https://gdurif.perso.math.cnrs.fr/>)"
institute: "LBMC -- CNRS"
date: "2022/11/23"
toc: true
format:
revealjs:
toc-depth: 2
slide-level: 3
smaller: true
scrollable: true
theme: dark
execute:
echo: true
warning: false
---
{{< include ../README.md >}}
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment