When would be a good time to start new projects in Quarto rather than Rmarkdown?

[rgayler]

Following on from #424

Assuming a researcher who is modestly competent and comfortable with the Rmarkdown ecosystem and just wants to do more reproducible research (rather than Quarto development), when would be a good time for them to start new projects with Quarto rather than Rmarkdown?

I presume from the answer to #424 that at some time developments/bug-fixes will turn up in Quarto before they turn up in Rmarkdown packages. If quarto already does everything that Rmarkdown can do, then people might as well start using Quarto immediately. On the other hand, if there is some essential (to some researcher) Rmarkdown package functionality that is currently missing from Quarto, then they should obviously wait.

Could you provide some guidance on where the current Quarto ecosystem gaps are (relative to the Rmarkdown ecosystem) to allow researchers to decide whether Quarto is ready for them yet?

Thanks.

[jjallaire]

Our current plan is to announce Quarto v1.0 at rstudio::conf (end of July). Our goal at that point is to provide unambiguous guidance that it's a good time to switch. The threshold for that is of course that Quarto be effectively a superset of R Markdown. In many contexts (normal documents, presentations, websites, books, blogs) I think Quarto is currently a superset (and the differences will continue to become more pronounced). Here are the areas where Quarto currently falls short (they are all priorities to remedy before the conference):

1. No ability to create custom formats
2. Related to this, no equivalent of the rticles package for Journal publications
3. No equivalent of flexdashboard for interactive dashboards

Our hope is that all these will be in place for the conference or shortly thereafter.

All of that said, I should emphasize that switching is not imperative. While we don't plan on major feature initiatives in R Markdown and related packages, we are going to continue to maintain them (smaller improvements and bug fixes) for a long time to come. Furthermore, since Rmd files can in most cases be rendered without modification by Quarto, you can continue using R Markdown and the switching cost will still be minimal whenever you decide to do it.

[harrelfe]

I have been using Quarto for all of 5 days. I am already able to do much of what I need and I really like the output and the use of separate lines for chunk options. My current advice is to switch now unless you need a feature not yet implemented in Quarto.

The only things I need to do that I haven't figured out yet are

• getting a format that looks like rmformats::rmdreadthedown with its floating toc on the left (Quarto currently doesn't have tocs working on the left)
• using Quarto with blog articles in an existing Netlify site that are created using hugo and its academic theme (my blog uses a version of hugo that is about a year or so old)

[bryanpmayfield]

I am in the same boat as my primary use case/workflow is producing analyses that I then convert to manuscripts by chaining together R Markdown documents via purl. I have (somewhat apprehensively) switched over to using .qmd documents now, and I am learning about 1-2 things per day that are either different or not quite possible in Quarto (compared to R Markdown).

One small example is data frame printing. The workaround covered there is sufficient but I had to spend a tiny bit of time figuring it out as it wasn't covered in the documentation (at least not that I saw).

So, specifically in response to the question, Quarto does not do "everything that R Markdown can do." I'm also not sure that is the ultimate goal for Quarto, so if that is a prerequisite to switching, the time to switch may never arrive. As you alluded to, what is deemed "essential" to any given researcher is highly variable and with the many nuances and capabilities of R Markdown, I doubt that it will be possible for the Quarto team to address every single one of these.

Therefore, I'm not sure (speaking strictly as a researcher focused on generating manuscripts for submission to peer-reviewed journals) that there will be a black and white answer as to when (or if, for that matter) it would be best to switch to Quarto. It seems to me that the decision will be person/researcher specific.

[jjallaire]

Note that we just added support for a df-print option (defaults to kable but all of the other normal option are available, see https://quarto.org/docs/computations/r.html#data-frames)

[jjallaire]

Hi @harrelfe great to see you here!

We do support toc-location: left but I believe that this currently works only for websites and books but not individual documents. @dragonstyle Is that correct? How hard would it be for us to add this for individual documents?

For the Hugo/Netlify scenario, the instructions here should work: https://quarto.org/docs/output-formats/hugo.html. Basically, make sure you are using Hugo page bundles (directory per post) and the just make a .qmd with format: hugo

[dragonstyle]

You’re right toc-location: left is currently limited to only websites. I think it is someing we should support, however, so I will take another look at getting it supported for standalone documents…

[harrelfe]

Thanks to both of you. I think I got format: hugo working; it's just that the output format is very simple, not like a regular Quarto report. I wonder if there is such a thing as extending the yaml header to include hugo academic tags and a full array of Quarto options for more enhanced blog articles. Regarding toc on left, it would also be nice to have a fixed left panel like rmdformats::rmdreadthedown where author and date stay on the bottom, title on the top, and floating toc in the middle.

[dragonstyle]

FYI, I've added added support for toc-location: left in standalone documents. It was a little more involved than I expected but it should be working as of v0.9 build 215.

[jwang-lilly]

For a quarto html document, Is there any way to display the main toc on the left margin and subsection on the right margin? Similar to this quarto book.

[dragonstyle]

For a simple HTML document there is not - you can place the TOC on the left, but it will display the complete TOC (versus placing subsection details on the right).

[jjallaire]

Yeah, in order to get all of the fancy Quarto stuff you need to be using Quarto CSS, which is in turn not compatible w/ the Hugo CSS. So for Hugo the best we can do is produce clean Hugo compatible markdown and from there hope that the Hugo theme does nice things with it. Note that YAML in the document should be preserved (so if you include hugo academic tags they will pass through.

[alexpghayes]

Thanks for the clarification!

Do you think there will ever be the option to build Hugo-like themes for Quarto itself?

[jjallaire]

It's basically Quarto websites: https://quarto.org/docs/websites/. There are lots and lots of options for theming and custom page layout. There is also a listings feature. So I'd say while Quarto can't create entirely arbitrary HTML like Hugo does, you can accomplish a substantial percentage of the same things (up to 100% for sites that are mostly about presenting articles, blog posts, docs, etc.)

[harrelfe]

I'm finding the formatting in Quarto to make it more than worthwhile to change my workflow with Hugo/Netlify to have .qmd fiiles rendered to html, adding the manual .markdown file to specify Hugo tags, creation date, and summary for the blog main page. I just lose disqus which isn't that good anyway and brings in a lot of adds. I activate hypothesis in my new blog articles to provide better commenting and am starting to add a Comments link at the top of the article to help people use hypothesis or refer them to a pre-existing discussion board. Example: https://www.fharrell.com/post/rpo

[harrelfe]

Update: I've converted to use a quarto web site and no longer use Hugo. The new approach works better and is easier to maintain.

[hakyim]

Do you still use netlify, though?