Add argument "format" to "distill::article" in order to use distill format in pkgdown articles

[pneuvial]

I would like to use pkgdown to build an html article with the (very nice) distill format.

As per the documentation of pkgdown::build_articles, "By default, pkgdown builds all articles with rmarkdown::html_document() by setting the template parameter." As suggested I have tried to override this by adding

pkgdown:
  as_is: true

to the yaml metadata of the default distill vignette, leading to the following minimal vignette:

---
title: "Untitled"
description: |
  A new article created using the Distill format.
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
date: "`r Sys.Date()`"
output: distill::distill_article
pkgdown:
  as_is: true
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)

Distill is a publication format for scientific and technical writing, native to the web.

Learn more about using Distill for R Markdown at https://rstudio.github.io/distill.

When running `pkgdown::build_articles` I get the following error:

```r
> pkgdown::build_articles()
-- Building articles ------------------------------------------------------------------------------------
Reading 'vignettes/test-distill-vignette.Rmd'
-- RMarkdown error --------------------------------------------------------------------------------------
Error in html_document_base(smart = smart, self_contained = self_contained,  : 
  formal argument "template" matched by multiple actual arguments

This is consistent with the documentation of pkgdown::build_articles: the output_format "must accept template, theme, and self_contained in order to work with pkgdown", and it is not the case for distill::article which forces format="default".

My understanding is that adding an argument format to distill::article would address this issue.

> packageVersion("distill")
[1] ‘1.1’

[jjallaire]

Based on my knowledge of distill and pkgdown I don't think that this will work (as distill needs it's own template). You could try forking distill and experimenting and let me know what you find, but I'd be quite surprised if you got the desired result.

[cderv]

To give more context on the current behavior and error:

I dont think the issue is with a format argument missing in distill::distill_article(). The issue lies in the fact that pkgdown will use a custom template to render article (in order to fit with the site template).

The doc of ?build_article mentions this briefly here:

If you need to override the output format, or set any options, you'll need to add a pkgdown field to your yaml metadata:

pkgdown:
  as_is: true

This will tell pkgdown to use the output_format (and options) that you have specified. This format must accept template, theme, and self_contained in order to work with pkgdown.

distill::distill_article() does not accept another argument template because it uses (and needs) its own template. Unfortunately, it does not error nicely with a message to say that because, if you pass a template argument in distill::distill_article() it will be passed to html_document_base() as a duplicate. hence the error you see as two arguments with the same name has been passed.

[cderv]

@jjallaire should we check for template argument passed to distill::distill_article() as I understand distill needs its own template and that can't be changed ? We could error early with a nice message as it will error inside html_document_base() anyway. (because we pass template = "default" already, for pandoc_mathjax_args I think)