Feature request: Use CSS resource from URL

[eddelbuettel]

A first test is a winner; I just converted a short and simple package FAQ vignette. Copying water.css (taken from minidown as usual) into the vignettes/ directory works, but I am wondering if we can do one better and support e.g. this:

<!--
%\VignetteEngine{simplermarkdown::mdweave_to_html}
%\VignetteIndexEntry{Littler FAQ}
-->
---
title: Littler FAQ
author: Dirk Eddelbuettel
date: 27 Oct 2021
css: "https://cdn.jsdelivr.net/npm/water.css@2/out/water.css"
---

Thoughts? Yay? Nay? Stoopid? Don't be afraid to call it out as silly and close it.

[eddelbuettel]

Turns out I misunderstood that the css file is embedded into the generated html file.

I guess the feature request still (sort-of) works because the html files would be smaller, at the cost of an external link.

[djvanderlaan]

I agree that this part needs some work. Not only for CSS but also for specifying templates. It would be really nice if something like

---
template: System.file("templates/pretty_template.html", "simplermarkdown.templates")
---

would be possible.

Currently a standalone document is generated. There are two reasons for that. First, that was the easiest way to get a css-file in the vignette directory working. These are not automatically copied to the inst/doc directory when building the vignettes, so would be unavailable for a built vignette. Second, don't know if there are guidelines for this, but when using an external CSS file would cause issues with systems that are not connected to the internet.

As for your example, what does simplermarkown (or actually pandoc this case as simplermarkdown does nothing with the header) do? Does it include the css you reference to into the resulting document or does it keep an external reference?

[djvanderlaan]

To answer my last question: it does include the CSS in the resulting document. However, it uses <style type="text/css; charset=utf-8">; the charset= trips up firefox and chromium resulting in the css not being used. This seems to be a bug in pandoc; can't imagine someone else running into this issue; so I'll have a look.

[djvanderlaan]

This seems to be fixed in more recent pandoc versions (I was using the default ubuntu 20.04 version). So with a recent pandoc version your request already seems to be working.

[eddelbuettel]

Thanks for all the follow-ups.

My first attempt did indeed not work (font stayed an un ugly default) so I added the respective instruction from your sample css file to the water.css copy I used. That worked. External resource may eventually be slicker.

You do not have to include the CSS if you don't want to. There is a optional fiile .install_extras you can use to copy resources from vignettes/ to inst/doc (described in the usual place: last line of Section 1.4). But I am not sure if your package wants to be in the business of creating that file. But maybe something to mention and/or document.

My first trial ballon went well. I actually converted the first package to this with two (very) simple vignettes. Yay!

[djvanderlaan]

Had another look at this yesterday. I have got a test version working that accepts things like

---
css: simplermarkdown.styles::pretty_css()
---

However, that only works for CSS (and probably latex includes) not for templates, as templates cannot be specified in the header of the markdown file. The header generates variables that can be used by the templates. The template itself can only be specified as a command line argument of the pandoc call. So my solution is only a partial solution as people will probably also want to specify a template.

For non-vignette users of simplermarkdown: they can just specify the correct arguments to pandoc. I don't think it is necessary to provide more than that; except perhaps documentation on how to do this.

For vignette writers specifying the arguments is more difficult. So either simplermarkdown has to read the header and construct the appropriate call to pandoc from that; or vignette writers have to use a Makefile in which the can control the call to pandoc. I guess giving users an example Makefile might actually be enough. That would keep simplermarkdown simple.

Don't know what that means for the CSS solution above: that can also be done in the command line. On the other hand, if a user can specify the CSS or include a latex header that would take care of the styling on a majority of cases.