How to build business reports with Quarto
How do you create the report look and feel that your leadership team expects? Christophe Dervieux at Posit joined us on Wednesday, March 27th to share how to style Quarto docs and send scheduled email updates to required stakeholders. Helpful resources: ️ Getting started with Quarto: https://quarto.org/docs/get-started ️ User guide: https://quarto.org/docs/guide ️ Github repo with this example: https://github.com/quarto-examples/quarto-business-report ️ Q&A Recording: https://youtube.com/live/bqk75igHo8M?feature=share ️ If you're interested in learning more about Posit Connect, pos.it/chat-with-us Timestamps: 02:00 - What is Quarto? 02:40 - How does Quarto work? (.md, .qmd or .ipynb as source files) 03:45 - How to get started with Quarto if you're new to it? 04:51 - Using Quarto from within RStudio 05:00 - Using Quarto within VSCode with extension & Jupyter Lab extension 05:37 - Visual Editor for Quarto 07:22 - Customer Tracker Report in RStudio IDE (using source code: https://github.com/quarto-examples/quarto-business-report) 10:39 - Making Quarto report downloadable as Excel doc (adding download button) 11:37 - Adding a table of contents to your Quarto report 12:23 - Spread Quarto graphics across page so that they go into margin 13:10 - Customizing theme in Quarto (Bootstrap 5) https://quarto.org/docs/output-formats/html-themes.html 14:45 - Increasing font size in Quarto report 17:10 - Customizing theme rules 21:16 - Publishing Quarto report to Posit Connect 22:35 - Scheduling Quarto report to automatically run 23:35 - Preview of default / non-customized email 23:58 - Customizing your Quarto email 26:52 - Customized email preview that Posit Connect can send 27:56 - Setting access controls for Quarto report on Connect and when you want emails to send Resources shared in Q&A session: Community discussion for ongoing Quarto questions: https://forum.posit.co/tag/quarto Quarto document language: https://quarto.org/docs/authoring/language.html babelquarto (for multilingual project, book, or website): https://docs.ropensci.org/babelquarto/ Quarto Manuscripts: https://quarto.org/docs/manuscripts/ Managing Execution in Quarto: https://quarto.org/docs/projects/code-execution.html Quarto Extensions: https://quarto.org/docs/extensions/ Project Profiles in Quarto: https://quarto.org/docs/projects/profiles.html Custom branding deeper dive: https://www.youtube.com/watch?v=V82BBU9ldcM Quarto Parameters: https://quarto.org/docs/computations/parameters.html Lua Development: https://quarto.org/docs/extensions/lua.html Quarto CLI Discussions on Github: https://github.com/quarto-dev/quarto-cli/discussions Data Science Hangout every Thursday at 12 ET: https://posit.co/data-science-hangout/ Get connected with others at your org using Posit: pos.it/connect-us There is no need to register; join us here on YouTube at the time above or you can add to your calendar using the link below: pos.it/team-demo We host these Workflow Demos on the last Wednesday of every month, so you can use the link above to add the recurring event as well. If you ever have ideas for topics or questions about them, you can comment below in YouTube!
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi everyone, so welcome to this workflow demo, to this new edition. So I'm Christophe D'Andreau, I'm working at Posit, I'm a software engineer and I'm working specifically on Quarto and also the R Markdown ecosystem. So today we'll be having a demo about how to use Quarto to build a business report, so we'll see some interesting topics and there will be a live QA session at the end of this quickly.
Thank you so much Christophe for joining us today. I had reached out to Christophe because I saw, I was going through our older videos on YouTube and saw his presentation on business reports with R Markdown from two years ago, it was really popular and wanted to update that for you all to show how you can build business reports with Quarto and some of the new functionality there. And so I know Christophe mentioned there's a live Q&A following the demo, I just wanted to let you know you can ask questions during the demo in YouTube here and we'll be monitoring that. We can also ask questions over on Slido and I'll share the link in the chat right now to where you could ask questions anonymously too. And so right after the demo it's going to automatically push you into that Q&A room, but if for any reason it doesn't, there will be a link to jump over there in the YouTube details below. But thank you all so much for joining us today and spending time with us. I'll turn it over to Christophe.
So we'll talk today about how to build a business report using Quarto. We'll first be trying to make a generic introduction to Quarto, like not going into detail but explain like what is Quarto, how does it work, and how you can use it. And then we'll be diving the example and the demo and building the HTML business report.
What is Quarto?
So what is Quarto? Quarto is a scientific and technical publishing system. Like it works with computation, with Python, R, Julia, ObservableJS, several languages. It works based on Markdown and it's based on Pandoc with many enhancements to Pandoc and it allows to produce like several types of output from single documents to presentation, website, books, or blogs, or more complex projects.
And how it works? It works like for our Markdown user around you, like it works kind of the same but it extends the way that our Markdown is working. It will leverage like multiple computation engines, so Anita, Jupyter mainly, but like maybe in the future others. And it could use like several type of input file, could be like regular MD file, so with no computation engine, or like QMD file, which is like for Quarto Markdown file, which is Markdown plus addition of computation cells. Or it could be also for Jupyter user, like more used to work in IPy1nb notebooks, like it could be like the entry source file of Pandoc.
So, different schematics show what happens, so computation happens, will transform into MD file, and then the MD file, if not the input, will be passed to Pandoc and then transformed to like output formats. But Quarto extends Pandoc, which is a universal converter to the format by adding many more features for like specifically for scientific and technical publishing, and lots of user-friendly feature. And it can produce like several type of output formats, like PDF, HTML works, like using different tools to do that.
So, if you're new to Quarto, how it does, the best way to start with Quarto documentation, we have a getting started session, and then we have a great user guide, so you can install Quarto as a standalone tool. And this is mainly how we use it. So, Quarto is first a core component, so it's a command line interface that drives all the rendering through the different tooling and all the coordination. And this is the only thing you need. So, if you're like working from plain Markdown file, Quarto will bend on Pandoc and any other things to build like regular documents.
And if you want to use R, then you would need to have like R and NetR for the engine, or if you work mainly with Jupyter, you need to have a Python installation and then Jupyter to work with the Jupyter kernels. And so, it's a system level component, and so it can be used with any kind of tooling. And it's why it's integrated in several places already. So, you can use Quarto through the IDE. The RStudio IDE will bundle Quarto and integrate with it. So, no need to install it directly, unless you want like a more recent version that is bundled. But VS Code can also work well with Quarto, because there is we developed VS Code extension, which makes the user experience great, as you can see on the screenshot.
If you're working with IE Power NB as your entry file, like it's better maybe to work in JupyterLab. There is an extension also for Quarto, which will recognize a different feature and so give you also the nice preview that you can get in VS Code or RStudio IDE. And there is a special tool, a visual editor for those who prefer like to work directly writing the document, not in text file with Markdown syntax, but a more visual way. So, it's what you see is what you mean type of editor. And it will write for you the source code. So, the initial source code is still like the screenshot is with RMD file, but it will be like QMD or other things. And it will work in VS Code and RStudio IDE.
Building the business report
So, that's for the generic part. So, of the introduction. So, now let's dive into a demo of our Quarto interworking. We will build a business report for stakeholders in an enterprise context. So, for this use case, we will start from a standard HTML document. So, the format HTML that Quarto provides by default. Then we will add some specific feature from Quarto to improve it a little.
And then we will work on styling to try to match some style guide from the organization. And then we will want to communicate this report. So, we'll see a demo of the publishing, how to share results in addition to this published document. And at last, we'll be customizing some scheduled email updates so that it's nicer to know when the new business report will be updated.
So, for this demo, we'll be working in RStudio IDE. We'll be working in the QMD file using R chunks. So, the NetR engine. I feel like this report, which is like a business report, we want to communicate on some results. And so, we'll go look at this report. For convenience of this demo, I will add some caching so that it will build quicker doing that. So, let's render. So, let's preview how this report looks like.
And we'll go through it. So, we are using the format HTML. We are setting some NetR option. We don't want to show the code. We just want to communicate on the results. So, this is what our reports look like. This report will use some R packages for data manipulation, like for graphics tables. And we'll use some parameters. This could have been some parameters to the report that we could pass, like parameters. But we just set them in this chunk, like some value for which we will filter our main data. And we'll use some helpers function to format the date. And we have the runtime, which is the time and the date for which the report will be built. Because we want to communicate for this date.
So, first, we add like it's a quarter feature. We will add a callout, like showing the date. And then we will retrieve some data. So, in real use case, this could be retrieved from databases, query, for each new date, each time the report is rendered. But here, like for the demo, we'll be using some CSV file export from like different database. So, like the current metrics, the previous metrics, and then some information about users.
The first thing we'll do is like compute the metric information, like binding the different data together, like doing some manipulation calculation. And then we will plot this information. So, we'll be using ggplot2, setting some width and height on the output. But we'll be using Plotly for this graphics that we can see here. And then we want to show a table, a summary table. So, we'll compute the summary and we format this table with GT.
So, we have the table here. So, I won't go into details, like how to create those tables and those Plotly objects, ggplot2 object, but like you will have access to the code if you want to look like deeper into this. But we want to like format the information in a way we can communicate this report to our stakeholders and interested parties. And we also want to share with our like consumer of this report some information that we'll put in an Excel table, Excel files, to have like the summary data or even to have like the main data set. So, this is a default report. It's looked like quite decent. This is a Quarto HTML format default. We did not customize anything.
Customizing the report layout
But we want to do we will want to do a bit more. So, as I said, we are creating a report and it would be nice to make this report like downloadable from the user directly. So, we can add something and like we can customize HTML format so that we can do something like that. So, we'll have like other links feature that you can find into the doc and we'll add the text. We will say that we want to put the file on this link and we will like set an icon to the download icon because this will be a way to download the file. So, this will re-render the document. Should be quicker because of the caching. And then now we have on the right a button where we can like download the report. Like if I click this button, it will like offer me to download the report. This is like first nice customization that we can do to make this report nicer.
But then we could also like as you can guess add a table of content to show the two party and quickly like jumps to the different headers. And so, we get the table of content on the right. And we could say also like the page is not maybe I could do this so that we can see how it looks like. This graph is nice. But as you see, we have like some layout in the page. And Quarto has nice feature to layout content in different ways. And we can take so on the chunk about the plot, we can use specific like new fields for Quarto which is colon. And we say like we will want to spread the graphics white on the page so that it goes also into the margins. Because we don't have anything in the margin and it would be nice if this like plot is wider. So, you see just by setting this information, we can like change the layout quickly. So, this is an example of what can be done. Like there is much more. And you can go look in the doc. But these are part of the feature, nice feature, article layout feature that you can use to make your report like less like default one and more customized to your needs.
Styling with themes and Sass
So, we are happy with the content with this report. But now like we would like to change like the style. We have like just black headers, like default color. This would look like any other report. So, there is a mechanism in Quarto to customize the themes.
So, we could use, for example, the Lux theme which is like bootstrap themes. So, Quarto will have some theme mechanism. It's powered by HTML document. We'll be using bootstrap. And we'll have included 25 themes from bootstrap. So, any of those themes can be used. And they will change like some default color or default font organization. Which was like it's based on bootstrap. And so, it's a nice addition. It will like be mainly have main impact for project like website, but you can have also like change in color for the callouts or for the headers. And also about the font. So, when we do that, we have now this report where we can see the font has changed. Like the font weight is a bit different. And so, we have customized our report this way.
We could also decide to change the title. So, let's say we want to say like term two instead of table of content. Because usually this is what we want to do in our report usually. And we may want to increase the font size, for example. So, let's say we'll use this as the font size. But this will re-render. And now we'll have a customized report. So, it will be like way bigger on the font. But when open in big screen and not in preview, it will be like nicer to read. So, we want that for our report. Maybe too big for the preview, but that's okay for the demo.
So, as you can see, Quarto offers some pretty easy customization through YAML fields only. And so, some viable like applying instead of doing CSS or changing the themes. Like we could change the theme and test different themes using that. I could like also change, for example, like the font color if I want. The main font, the monofont. So, could change different things from the YAML.
as you can see, Quarto offers some pretty easy customization through YAML fields only.
So, this is a nice report. But like usually in enterprise or in organization in general, it could be interesting to follow the style guide that we could have also for our report that we create through Quarto. So, for that, Quarto is using a siming system. So, this is explained a bit below. So, there is some sim option that you can customize using a CSS file. So, it's using a CSS, which is a tool to create some CSS document and extension language that will like be compiled and use a CSS. And Bootstrap is built using Sass. And so, when you provide like customization, it will be mixed and layered. And so, there is specific syntax to follow. I won't enter into detail, but I will show you an example. And this will allow you to customize some part of the default theme or the theme you choose. But you can also like override and provide your whole theme. Like it's a bit more complex, but you can also do that.
So, let's say we want to customize some of the rules and the option of this default report. So, we'll save this file. We'll use like say custom file. And so, this is the content that copied from what I prepared. So, let's say my organization is using a font. Like that should be using old documents. So, this font is available as a Google font. So, I can import this font. Here we'll be using Lato. And I can define this font using these variables inside. Those variables can be found like we have a list on the website of main variable. But as I said, it's based on Bootstrap. And so, any Bootstrap variable that is available can be used. So, all the variables can be seen in the code. But the main one that you could use should be changing the background, the color, the link, or the font size. So, some information in the code block. And there is also some variables specific to some features that we will use.
So, we are changing the font. And then we want to use our color theme like our style from our style guide. So, we have like a dark blue as the main color and then a gray for a second color. We want to be using the main color for our talk. So, here currently like it's dark gray. We'll want to use some link color. So, I think here it will be the link. And we want to set all our headings to be like the dark blue, the main color. And we'll want also like this is blue, like the callout is a default blue color for this type of callout, which is a node callout. We will also want to use like a dark blue color, but like a slight variation. And so, we'll use some of the Sass feature. And it's why Sass is powerful for that. So, we can adjust the color and like we'll use like a more lightened color for that. And we'll be adding tools for this example. Like we want to have like an H1 with an underline and like with customization and adding shadow like around that. Let's say that's how we do either in our organization. And H2, we want to be using the second color.
So, this is what it's like. And the specific rules here, this one, this one, and this one are specific to Quarto. So, SCSS is a format from the SS tool. So, Sass tooling. But we are usually you provide several files for that to be built. And in Quarto theming, when we talk about Quarto theme file, this is this one single file where we like catch everything and do the right thing in the right organization with bootstrap. So, let's do that. And let's add this custom theme to our current report. So, this will be rendered. Quarto will handle the merging of all the theme and should use the rules. So, the font should be changing. The color should be changing.
The color should be changing. The callout has changed. The link also color are changed here. And so, we have the title, the font changed. So, we have now a nice report that follows our theme file. So, we are happy with that. And now it's time that we want to share these results.
Publishing and scheduling the report
So, from the IDE. So, Quarto has some publishing features. So, as I said, Quarto is a CLI tool. So, we will have like some publish commands that one can use to publish to different provider. So, Netlify, GH page, like Connect. And we'll be using here the built-in thing from the built-in features from the IDE. And I already published because it's quite long to publish the first time because it needs to restore all the information. But we will publish everything to our Connect server. So, let's go to this Connect server.
So, this is like I activated the report. So, this is a report like we just built. It's now published. So, it's published. It has been like built directly through it's been built directly on the server. And it can be like consulted. So, if I send the URL to someone else, the report can be consulted as a standalone one. So, this is my report. So, I can send that. The user can like click and download the file that has been generated like on the server. So, it's a nice feature. And I can also schedule this report here. For example, to run at several times. Like as we said, like in a real use case, this report could be connected to like databases to query the information and then do the same computation, the same graphics, and like add a row to the table like for week 23. So, we could like say I want to run this weekly every Sunday to get like all the information from the last week and produce this new report. And it would be generated and I can like auto publish this report. But I can also like send email after update.
And so, we can see example of this email. And so, here I can like just have a preview or email this report to someone. And so, if I send this email, this is like what the default email look like. So, it's not like that great. But like so, it's a different feature. And it would be nice if we could customize this.
Customizing the email with Quarto email
So, we are now back on our document. And we want to customize email. So, Quarto Email is a new feature from 1.4 where a specific syntax can be added to an HTML document so that the content will be treated as the content of the email by RStudio Connect. So, I could use the email format and add specific part that I will do at the end of my document and with the syntax which is called like the div syntax.
So, I've prepared the example here. Let's go through it. So, we'll have email div with some chunks to prepare the data with some label here. So, let's typo. And we'll compute a specific subject using those data. And we would write the content of the email. So, dear all, please find below the latest like the name of my report and the date from which this report has been updated. And we want to highlight some specific metrics and social evolution. So, we would compute some like new summaries with specific formatting to highlight in the email and show the plots. Not the plotly output because it would not work inside of an email format. But the ggplot object. So, we can insert that and it will be inserted into the email as a file. And we want to show our summary data. So, tab was our summary data we computed above here. So, the same as in our document.
And we want to attach the XLS6 report that we produced above. So, this would require attaching adding some metadata to YAML like we would attach the XLS file. And we like also would attach the PNG file of our plot that we already inserted into the Excel file. So, this would require to add these specific fields into so, email attachment configuration in the YAML header so that Posit Connect would know how to deal with the attachment. So, let's render this with all those additions. And you'll see that our initial report is not a touch.
It will be exactly the same. But with the email information. So, if I'm looking at this, I get the exact like same report. And so, for now, the preview is like the reports. The same as the email format. But there would be a specific preview of the email that you can get here. So, this would be our email preview that Connect can send. So, it's interesting to see how it would look like in the directly in document. So, this is the same when I publish it. So, this is the document. But now, if I'm like scheduling and then sending email. So, if I send this email to show what it would look like. And so, this would be this would be my email. So, let's look at the email without the purple color. So, this would be the same exact same as the preview. The email that any stakeholder or any people subscribe to the report would receive.
The email that any stakeholder or any people subscribe to the report would receive. So, this is like nicely done compared to the default output.
So, this is like nicely done compared to the default output. And so, this could be sent to like any collaborators of the report that can be defined into the access part. So, this is about Connect feature. And this could be sent like just a reminder. This could be sent after each update. So, once I've done this with the Quarto document, I prepared my report. This report is connected through data and I'm scheduling it each week. Like if no updates in the graphics or anything needs to be done, then this would be automatically generating using Quarto. The email would be produced. I would get some updates. And this would be sent to everyone. So, this is how we can produce some business reports with Quarto.
So, this is a nice example for you to understand how Quarto works and what can be done. So, obviously, there is a lot to go into details to understand like each items and configuration I mentioned or did not mention. And so, I hope you will find I will put in the slide the repo to get the source. And if you have like any issue or question, you can go into the discussion board on Quarto and then we will have the QA session now. Thank you.
Thank you so much, Christophe. I am so excited to have this beautiful email example to be able to share with people as well. As I mentioned earlier, we are going to jump over into a live Q&A room right now. So, if you want to join us over there, YouTube will automatically push you over. But if you have any issues, there is a link in the YouTube details below where you can find that Q&A room. As a reminder, you can ask questions right in the YouTube chat there or use the Slido link, which is shown on the screen right now. But let's hop on over and see you in a second.
