Devin Pastoor | Websites & Books & Blogs, oh my! Creating Rich Content with Quarto | RStudio (2022)

My name is Devin, I'm a Solutions Engineer at Posit, and I'm really thrilled to be up here today to talk about Quarto, because in many ways, the vision of Quarto, that reproducible research is a core part of high-quality scientific communications, was a key driver in actually nudging me along my career journey that ultimately has brought me to Posit.

Almost 10 years ago, as a graduate student, R Markdown blew me away when all of a sudden I could shortcut an enormous amount of the tedious interactions from working in R scripts and actually taking the outputs of those, getting them into Word or PDF documents to distribute.

Now, as many graduate students are inclined to do, I also dabbled in figuring out how I could use the tools I was learning, in particular R, in fun, new ways.

From R Markdown to bookdown and blogdown

So about that time, a new tool emerged called Gitbook, and it was really fascinating to me because the idea was to take a bunch of Markdown documents, jam them through this processor, and out popped a website that had navigation and styling, and it kind of looked like a book. And so I said, hmm, that seems kind of interesting. I wonder if I can take R Markdown documents, get them to Markdown to put them through Gitbook. And so I put together some really, really scary-looking code, but thankfully the RStudio team was also keeping an eye on such ideas, and bookdown entered the scene.

This ability to build on a unit of an R Markdown document into more complex content felt like a taste of opportunities to come.

And so similarly, when I started playing around with what it was going to be like to build a blog, I found Hugo, a static site generator that you could also make most of your content with Markdown. And so by using that content in Markdown, plus a little bit of metadata and configuration, you could generate a professional-looking site.

Again, the RStudio team responded with blogdown. And it was so exciting to me, because there's actually official tools to support these janky workflows that I was trying to come up with. That integration between Hugo and Markdown was able to help bring content to life.

But as fascinating as these experiments were, as fascinating as learning those tools were, it was undeniable that there were some significant points of friction and frustration in figuring it out, especially around the tooling boundaries. It was never fun to see a Hugo theme that just kind of didn't work for how you wanted to lay it out, or something that worked in bookdown that you couldn't put into blogdown. And so as powerful as these tools were, it was clear that the separation of the communities that we were trying to meld together left some gaps to make this approachable to everyone.

Quarto unifies the ecosystem

But here we are today. As Mine and Julie have explained, and hopefully as everyone is getting so excited about, Quarto builds on the learnings of the past decade. It unifies teams across language boundaries and procedural differences. And in the same vein, Quarto can also unify the way you consider building those books, blogs, websites, or all sorts of other complex content, so you can focus on enabling users to discover, consume, and navigate in the ways that you would like to help them.

And by doing so in a single, unified toolchain, it really does give you an unparalleled ability to control the processing and ultimately the production of the content that you're working on.

And by doing so in a single, unified toolchain, it really does give you an unparalleled ability to control the processing and ultimately the production of the content that you're working on.

Now one thing that some of you may be thinking is, this seems like a lot. One tool that can do so much. How may I even start learning all of the things that it can do? So today, I'm going to do something that hopefully the presentation gods will be with me, and I'm going to show you just how easy it is to get going with Quarto and do some pretty cool stuff. And hopefully also demonstrate about some of the thoughtfulness that the Quarto team has put into its design.

Live demo: creating a website

So, let's drop into RStudio. Now, one of the things that you can always do in RStudio is if you want to go play around with a somewhat recent version of RStudio, you can go in, create a new directory, and Quarto is front and center. But the Quarto team has wanted to make sure that Quarto is available even if you're not using RStudio, if you're using VS Code or any other editor. And so many to all the things that you can do in the IDE, you can also do on the command line.

In this case, we want to get going with a website. So in this case, I can, from the terminal, say Quarto, create project, type equals website. And what this is going to do is start me off with a scaffold. It has a couple of these QMD files that you've been hearing about, and it has this Quarto.yaml. This is the magic, the ability to say I have the area that I'm going to write my content, and I have a hub where I can control how I want that content to be rendered.

So, if I want to take this content, maybe add a little bit more structure to it, so here is a header, and maybe we'll add a list, some markdown, some more interesting stuff, and I can render it. And what's going to pop up is my site.

Now, let's look at this site really briefly. I have a title. I have a home and an about page. You can see my header that I can actually link to in case I want to get someone directly there if it's a longer page. And I even have a table of contents if I have more elements so I can see how I would navigate through that page.

Now, you could go build this today in blogdown, no problem. But where things start to get exciting to me in Quarto is just how flexible you can be when you say, what if I want to move things around? So, in this case, you can see how this is laid out. I have my website. I have a title that I can change. I also have a nav bar, so that top strip is a nav bar. But if I instead said I want to move my content so it's on the left, right, which is actually one of the big things that would differentiate for like a book, it's quite simple. I could just say this is a sidebar.

And if I go back here and I want to regenerate it, my site now has no nav bar, and instead my contents are on the side. You don't have to decide up front, is this a book? Is this a blog? Because Quarto is giving you the ability to put things in the way you want, and you can combine the ideas that make books great, blogs great, or any other different type of layout. And much of that is accessible directly with a couple lines of code in this configuration file.

Adding a blog with listings

And so I'm going to bring back the nav bar for a little bit, and let's talk about blogs because I think that's one entry point for a lot of people where you can start to dabble with things that you're learning. Maybe it's stuff at the conferences. Maybe it's some of your own personal learnings that you want to put up to the world. And so what I want to do is I want to add some more organization to this content. And so I'm going to make a posts directory. And in that posts directory, I'm going to make a Quarto document. My first post.

Now one of the things that you're going to see coming up right here is the visual editor. Now this isn't directly enabled only by Quarto, but this is something that to me is so exciting about the blend of what Quarto offers plus what the RStudio IDE can also bring to the table. So for some people, the ability to write markdown is fine for text, but as soon as you start doing more complex things like dealing with images, it becomes tedious to remember. Oh, what is that? Is it exclamation point bracket or is it parentheses? I can't keep track. How do I get stuff in? And suddenly going back to a Google Doc or something feels a lot more approachable.

With Quarto and the visual editor, you get that what you see is what you get interface if you want that. Now I can always switch back to the source if I'm comfortable writing that, but the visual editor has some pretty nice goodies hidden inside of it. For example, if I wanted to clear all of this out, and say I'm here at conf. RStudio has just rebranded. And you know what? I think it would be great to also add a screenshot.

So I'm going to save this into my posts. And let's go over to the new Posit website. And for fun and games, I'm going to grab a little screenshot maybe. Boom. I grab that screenshot. I'm going to copy it to my clipboard. Now before the visual editor, I'd have to save this out. I'd have to put it in a directory. I'd have to move that around. I much prefer just pasting it. And the visual editor has now taken that and stuck it in an images directory for me.

These quality of life improvements are all throughout the Quarto ecosystem. To showcase another one real quick, if I look here and I wonder, you know, oh, what was it? Was it sidebar? Was it side something? I can start typing. And with some tab completion, it's going to tell me what my options are. Now notice, this isn't a long list of every possible option. It's just the options relevant for that level of indentation. In this case, I could say true or false. Or if I indent again and then ask and say, tell me what things I could do with the sidebar, you see this come up right here. And I can say, oh, yeah, I could put some contents in.

The things that could frustrate you, make you feel like you needed to pull your hair out, the IDE in Quarto and the tooling built around it is trying to help you not have to deal with that and be able to focus on your content.

And so I have this first kind of conference experience page here. And what I'm going to do is I'm also going to go kind of steal, just for the sake of time, another kind of post starter that I grabbed right off of the Quarto website. So we can also stick this in the posts page.

So what we have here is I've added another more complex Quarto document that has a bunch more stuff going on to it. The majority of the intent of this doesn't matter so much. This is on the Quarto website, so you can explore about it. But the point is I'm starting to build up multiple blog posts. And so how are you going to display those for your user? If we think about what a blog might have, you might have something that's sorted by date. It shows an author, maybe an image preview. It gives that stuff to you so you can see what's going on.

And so instead of making it look like it's magical and I can remember how to do this off the top of my head, this is a great opportunity to go over to the Quarto site to say, if this was the first time I was considering trying to build a blog and I wanted to go look at it, I can go and look through the search, and Quarto is going to give you a whole bunch of information on that site about what to do for blogging. And so in this case, I can scroll down a little bit, and they say, hey, if you are dealing with a blog, you can grab this, and what we can see here is the idea of some configuration that allows us to say, you're going to want to display some listings, you have some content that's going to be a bunch of different post, you know, QMD documents or otherwise, and you're probably going to want to do something with this. So let's just steal this right from the site.

So now I have this blog QMD file, and I just have to say where I want it to be. In this case, I'd be completely fine with it being right next to that home and that about, so I'll say text is blog, and href is blog.qmd.

Now notice the contents is this posts folder. If I had a different folder name, I'd give it a different thing. So now let's go check at what this whole site is going to look like. So everything got rendered. I can go to my about page. I can go to my blog, and you can see here that I have these pages that I can click in, and I already have a pretty great-looking thing right out of the box that shows all sorts of information about it. You can see the author, the publication date, and a whole bunch of images.

Publishing with Quarto Pub

Now, content is great looking at it on your laptop. But realistically, the true excitement is when you can actually get this out to the world. And so the Quarto team has also wanted to make sure they could make this as easy as possible for everyone.

So let's go back to the Quarto command line. In this case, I can say... Quarto publish. And there are a number of different endpoints. If you use RStudio Connect, that is, of course, one of them. There's Netlify, if you've ever heard of Netlify. But one other thing that I'm so excited to show is Quarto Pubs. And in this case, I can say, I would absolutely like to publish. I have a site that by default is going to be the folder name, but I can give it any name I want. And up it goes. It's uploading all of the elements to the site. It's deploying it. And in just a moment, we now have a live site available to the world.

Quarto extensions

And to me, the thing, if I look at this blog, and I look at this fun, photography-filled site with a bunch of complex layout that is great to kind of inspect and analyze, this is all well and good, but wouldn't it be nice if we could add some more interactivity? And so one of the things that kind of made me a little nervous when looking at Quarto, you know, one tool chain to rule them all, is what if you want to do something that's not in the tool chain? And so what the Quarto team has done is they've built up this concept of Quarto extensions.

We have a couple extensions already out there, and so in this case, one of the extensions is called the Lightbox extension. And so this allows you to add some styling to images. And so you can see right here, there are some great installation instructions. So let's just see what happens if we run this. I'm going to say, absolutely, I do trust the authors. I have now installed an extension right from GitHub into my site, and then I can go, and I can go to this pictures page, and in the configuration we can see you need to add this extra little bit of syntax on filters and Lightbox.

So let's take a look at what this looks like now. So if I go to this, fun photography. So now I have what to me comes out as a much more professional photography-looking website. I can pop things out. You can scroll across them with the magic of pulling in an extension. And extensions can do this and so much more. If you want to think about themes for your company, layouts for documents, or all sorts of other advanced functionality, there's a whole bunch of delight that these extensions are bringing to the table.

You might have heard of Vetiver. One of the cool things about Vetiver is it is multilingual, but that meant bringing multilingual code snippets throughout the entire site. But if you want to go and you're interested in Python, I don't want to have to click through Python across every single tab on the site. One Quarto extension made now all of my tabs are synced across the language that I pick every single time I come back to this. So the Quarto extension ecosystem is going to allow the community and the Quarto developers to really take Quarto and expand to do so much more beyond what I can even do out of the box.

Closing thoughts

So there's so, so much that we haven't had time to talk about today with Quarto. So I want to close with one suggestion. There's a gallery in Quarto that covers a whole bunch of stuff that you can do with it. Go there for some inspiration. Of course, things like the Quarto website is there, but there are people that are generating some really awesome hybrid sites that can do so much.

One of my favorites that I've seen is this MLR3 book. This is what a book looks like with Quarto that you can make, and there are so many little good bits, like the fact that you can actually embed the code that generated the site right there to pop out. If you like things like light themes or dark themes or otherwise, there is so much to discover there. So take a look, read around, and most importantly, go out and play with Quarto. You can get going so fast, and you can have so much fun while you're at it.

And while you're along that, please don't hesitate to reach out to the Quarto team. And so with that, I'll just kind of leave this up there, but I really hope you all go out and build. Thank you.