diff --git a/README.md b/README.md
index 9ad1d61b55b0907ca06c92e32967b4d16fe2538a..13287bbab0fa6e66901b09a05e75be2b20b834f4 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,12 @@
---
-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%"}
+{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`
+
+{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...
diff --git a/_quarto.yml b/_quarto.yml
index 365bef618f2ca0502abb48f9a1b76d3534d8397f..5c32fd7702f946e3c2f6a193c816d781002a01e0 100644
--- a/_quarto.yml
+++ b/_quarto.yml
@@ -8,6 +8,8 @@ website:
- href: index.qmd
text: Home
- about.qmd
+ - href: presentation/slides_presenting_quarto.qmd
+ text: Presentation
format:
html:
diff --git a/img/pandoc_format.jpg b/img/pandoc_format.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..d345d6430eaf13e854735d23a9f41c56b60a9651
Binary files /dev/null and b/img/pandoc_format.jpg differ
diff --git a/img/rstudio_new_project.jpg b/img/rstudio_new_project.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..385f7b5eb82c28773dbb9c341163ec7040735fe5
Binary files /dev/null and b/img/rstudio_new_project.jpg differ
diff --git a/index.qmd b/index.qmd
index c82ccd25be023cb2562e1bd9413882b0cd1d0ca7..3ce5cdef03c98c7cbeae8105586d9f7c7777beaf 100644
--- a/index.qmd
+++ b/index.qmd
@@ -2,6 +2,4 @@
title: "Quarto Website Template"
---
-This is a Quarto website using Markdown files to write contents.
-
{{< include README.md >}}
diff --git a/presentation/img/pandoc_format.jpg b/presentation/img/pandoc_format.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..d345d6430eaf13e854735d23a9f41c56b60a9651
Binary files /dev/null and b/presentation/img/pandoc_format.jpg differ
diff --git a/presentation/img/rstudio_new_project.jpg b/presentation/img/rstudio_new_project.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..385f7b5eb82c28773dbb9c341163ec7040735fe5
Binary files /dev/null and b/presentation/img/rstudio_new_project.jpg differ
diff --git a/presentation/slides_presenting_quarto.qmd b/presentation/slides_presenting_quarto.qmd
new file mode 100644
index 0000000000000000000000000000000000000000..38a2a01dcd5ada77e7798fbae689bb0ea913b17b
--- /dev/null
+++ b/presentation/slides_presenting_quarto.qmd
@@ -0,0 +1,18 @@
+---
+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 >}}