Skip to content
Snippets Groups Projects
Select Git revision
  • 84f3df6a0eff85bd9a3b2774583114c90a6d03b9
  • main default protected
2 results

quarto_website_template

  • Clone with SSH
  • Clone with HTTP
  • title: "Quarto: markdown-based document creation/edition"
    subtitle: "Static website generator and more"

    This is a Quarto website using Markdown files to write contents.

    Creative Commons License
    This work is licensed under a Creative Commons Attribution 4.0 International License (CC BY 4.0)

    What is Quarto?

    Per the Quarto official website:

    Quarto is an open-source scientific and technical publishing system built on Pandoc

    • Create dynamic content with Python, R, Julia, and Observable.
    • Author documents as plain text markdown or Jupyter notebooks.
    • Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.
    • Author with scientific markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more.

    Documentation

    Under the hood

    :::: {.columns}

    ::: {.column width="70%"} pandoc: "a universal document converter" :::

    ::: {.column width="30%"} Pandoc supported formats :::

    ::::

    Creating a website with quarto

    Command line:

    quarto create-project <my_website_name> --type website

    Rstudio:

    new project -> quarto website

    Rstudio project types

    Quarto markdown files

    • Use Quarto markdown (.qmd) files to write your contents, following the standard Markdown syntax with the additional features to run computations, similarly to Rmarkdown.

    • 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>
    • 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)
    • See also quarto R package: quarto::quarto_render() and quarto::quarto_preview()

    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:

    x <- seq(0, 10, 0.1)
    plot(x, cos(x))

    R, Python and Julia programming languages are supported.


    Another example in Python:

    a = []
    for i in range(10):
        a.append(2*i)
    print(a)

    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 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

    :::

    ::: {.column width="60%"}

    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:

    pages:
      image: registry.gitlab.com/quarto-forge/docker/quarto
      script:
        - quarto render --execute --to html --output-dir public
      artifacts:
        paths:
          - public

    Docker images

    • rocker: "Docker Containers for the R Environment"
    image: rocker/rstudio
    # 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

    Customization

    • css and local styles.css file
    • extensions: template for journal articles, presentations, web pages

    Example: https://computo.sfds.asso.fr/published-paper-tsne/

    Alternatives

    R-based:

    • Rmarkdown + 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, blogdown, bookdown R packages for Rmarkdown-based document generation (with a specific aim)

    Other:

    • Hugo static website generator based on markdown (restricted to web content creation, multiple community templates)

    • jekyll static website generator

    • and more...