davidcarayon/quarto-inrae-extension

Quarto extension for INRAE Templates

Quarto templates for INRAE

The goal of this quarto extension is to provide a wide range of quarto-based formats for INRAE engineers and researchers. These are an unofficial and opiniated templates.

Related work

• The {InraeThemes} R package for ggplot2 and bootstrap themes
• The inrae-project-website extension for research project website templates

Prerequisites

To make the full use of these templates, you will need :

• 2 fonts defined in INRAE's design system : Raleway and Avenir Next Pro Cn that can be downloaded here
• A LaTeX installation if you are using the beamer format
• Of course, Quarto installed (> 1.4.0)

Installing in a new project

You will need to do this to get all the folders with all the templates, assets and prefilled quarto templates :

quarto use template davidcarayon/quarto-inrae-extension

Note: Previous versions of this extension can still be downloaded using GitHub release tags :

quarto use template davidcarayon/[email protected]

Installing for an existing project

You may also use this format with an existing project to download only the _extensions folder (not recommended).

quarto add davidcarayon/quarto-inrae-extension

How to use it

You can use the any of the template_*.qmd templates which all have an inrae-* format pre-configured.

You will also find a _quarto.yml file to use if you want to use custom projects (manuscripts, websites, books). These projects will use the index.qmd file.

Of course, this extension offers more features than you will typically need, so you can delete all the unnecessary qmd files.

These formats and designs are opiniated. Feel free to modify them to suit your needs in _extensions/davidcarayon/inrae. All suggestions and PR's are warmly welcomed.

To customise your formats, see the relevant documentations :

• Html and office documents (html/revealjs/docx/pptx) : Quarto's documentation
• Typst documents (pdf) : Typst's documentation
• LaTeX documents (beamer) : LaTeX's Beamer documentation
• Quarto projects (manuscript, website, book) : Quarto's documentation

Standalone documents

Documents

• inrae-html : Provides an html document that can be hosted online (quarto-pub, github/lab pages, etc.). See Publishing in Quarto's documentation
• inrae-typst : Generates a PDF document using the Typst engine, a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use.
• inrae-docx : Generates a word document, typically to share for revisions

Slides

• inrae-revealjs : Generates HTML slides that can be hosted online (quarto-pub, github/lab pages, etc.). See Publishing in Quarto's documentation
• inrae-beamer : Generates PDF beamer slides using LaTeX
• inrae-pptx : Generates a Powerpoint presentation, typically to... whatever.

NB : Some obscure error may occur when rendering Beamer if you are using 2023's version of texlive. If so, I can only suggest to follow this article to try and go back to 2022's version.

Projects

If you wish to use one of the 3 project formats, you can edit the _extensions/davidcarayon/inrae/_extension.yml to comment/uncomment your desired output :

  ## Project definition
  project:
    project:
      type: default
     #type: website
     #type: manuscript
     #type: book
    format: inrae-html

• manuscript : Quarto manuscript projects provide a framework for writing and publishing scholarly articles. See more here
• website : Quarto Websites are a convenient way to publish groups of documents. They can also be used as easy to deploy research project websites. See more here
• book : Quarto Books are combinations of multiple documents (chapters) into a single manuscript while not breaking cross-references. They can be typically used for complex reports. See more here

Real-life examples

• RevealJS presentation of the SK8 project (FR) : slides and code
• RevealJS presentation prepared for a training on phylogenetic methods : slides
• Quarto website filled with html docs and revealjs slides, all based on this extension, with a few tweaks : documents.migale.inrae.fr

Changelog

quarto-inrae-extension 1.0.0

• Cleaned the extension file tree
• new Typst format to replace the laggy LaTeX format for PDF reports
• Better documentation
• New feature : Projects (Manuscripts / websites / books)

quarto-inrae-extension's Issues

Picture file can't be found during pdf compilation

I added your extension to my project directory, and rendered via command line: quarto render --to inrae-pdf

I got the following error:

compilation failed- error
Unable to load picture or PDF file '_extensions/inrae/ressources/photo.png'.

Should the file path be relative to the .tex file in the /ressources directory rather than to the quarto project directory? Sorry, I'm a latex beginner. I'm using Linux.

output file index.log attached below.

Full quarto output:

pandoc 
  to: latex
  output-file: index.tex
  standalone: true
  toc: true
  number-sections: true
  top-level-division: chapter
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  
metadata
  crossref:
    chapters: true
  documentclass: scrreprt
  papersize: letter
  classoption:
    - DIV=11
    - numbers=noendperiod
  header-includes:
    - '\KOMAoption{captions}{tableheading}'
  block-headings: true
  sansfont: Raleway
  mainfont: Avenir Next LT Pro
  toc-title: Sommaire
  geometry:
    - top=25mm
    - left=25mm
    - right=25mm
    - bottom=25mm
  bibliography:
    - Mybook.bib
  title: 'My Book'
  date: 4/21/2023
  author: Me
  description: 'My Book description'
  
running xelatex - 1
  This is XeTeX, Version 3.14159265-2.6-0.999991 (TeX Live 2019/Debian) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
updating tlmgr

updating existing packages

compilation failed- error
Unable to load picture or PDF file '_extensions/inrae/ressources/photo.png'.
<to be read again> 
                   }
l.204 ..._extensions/inrae/ressources/photo.png}}}
                                                  % 

index.log

Error rendering template.qmd

I downloaded a zip of the latest git commit, and in the extracted directory, I did the following on the command line:

quarto render template.qmd --to inrae-pdf

And got the following error:

compilation failed- error
Misplaced \crcr.

Output file template.log attached below.

Full quarto output:

processing file: template.qmd                                                                                                                                                  
  |..............                                                        |  20%
  ordinary text without R code

  |............................                                          |  40%
label: unnamed-chunk-2
  |..........................................                            |  60%
  ordinary text without R code

  |........................................................              |  80%
label: unnamed-chunk-4 (with options) 
List of 1
 $ echo: logi FALSE

  |......................................................................| 100%
  ordinary text without R code


output file: template.knit.md

pandoc 
  to: latex
  output-file: template.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  
metadata
  documentclass: scrreprt
  classoption:
    - DIV=11
    - numbers=noendperiod
  papersize: letter
  header-includes:
    - '\KOMAoption{captions}{tableheading}'
  block-headings: true
  sansfont: Raleway
  mainfont: Avenir Next LT Pro
  toc-title: Sommaire
  geometry:
    - top=25mm
    - left=25mm
    - right=25mm
    - bottom=25mm
  title: Titre de la présentation
  subtitle: Sous-titre de la présentation
  author:
    - name: '**Premier auteur**'
      orcid: 0000-xxxx-xxxx-xxxx
      email: [email protected]
      url: 'https://lien-site.fr'
    - name: Second auteur
      email: [email protected]
      orcid: 0000-xxxx-xxxx-xxxx
  date: today
  date-format: long
  
running xelatex - 1
  This is XeTeX, Version 3.14159265-2.6-0.999991 (TeX Live 2019/Debian) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
updating tlmgr

updating existing packages

compilation failed- error
Misplaced \crcr.
\endarray ->\crcr 
                  \egroup \egroup \@arrayright \gdef \@preamble {}
l.272 ...olor{inraefonce}{\sffamily \insertauthor}
                                                  \par

template.log

ERROR with self-contained output

Hello David,
Thank you very much for your template. It is very useful for our slides.

I observed some errors that seem to be linked but I did not find the origin (perhaps self_contained) :

• chalkboard doesn't work (ERROR: Reveal plugin 'RevealChalkboard is not compatible with self-contained output)
• youtube social embeds fail
• {.fragment .highlight-red}

I finally fixed that by adding self-contained: false in my header.
Do you have an opinion on these problems?

Thanks again for your work!

2 suggestions for the doc

Hi!

First of all, awesome work. Having everyone at Inrae using the same style for their report would be awesome.

I would like to make 2 suggestions for the GitHub repo:

• Add a link to an online html report made using the extension
• Add a code chunk showing how the YAML header should look like

Thanks for your work!