Resources
Aug 30, 2022 |
1h 12min
|
12.9k views
|

Building a Blog with Quarto | Led by Isabella Velásquez, RStudio

Led by Isabella Velásquez

A few helpful links upfront:
✨ Quarto documentation https://quarto.org/
✨ Meetup presentation: https://rstd.io/build-quarto-blog
✨ Blog exercise GitHub repo https://rstd.io/quarto-blog-exercise-repo
✨ Blog exercise Cloud project https://rstd.io/quarto-blog-exercise-cloud
✨ Upcoming events: rstd.io/community-events
✨ Welcome to Quarto Workshop: https://youtu.be/yvi5uXQMvu4

For the examples above, please ensure you are running Quarto Version: 1.0 or higher.

Timestamps: (to be updated)
42:03 - Add a blog post

Abstract:
A blog is a fantastic opportunity to record your data stories, gain exposure for your expertise, and support others in their data science journey. In this talk, I will discuss building a blog with Quarto. Quarto is the multi-language, next-generation publishing system from RStudio, with many new features and capabilities. Quarto websites include integrated support for blogging. You can quickly get up and running with a blog and focus on customization and style. Quarto also allows you to publish executable code blocks to include R, Python, Julia, or Observable JS output in your blog posts.

Speaker Bio:
I am a content strategist, data enthusiast, and author. My main goal is to drive engagement around all the awesome things happening at RStudio.

image: thumbnail.jpg

Transcript#

This transcript was generated automatically and may contain errors.

With all of that said, thank you so much Isabella for getting us all started with building a blog with Quarto. Isabella is a content strategist, data enthusiast, and author with a goal to drive engagement around all the awesome things happening at RStudio.

Thank you so much Isabella and I will pull you on stage here with me.

Thanks for joining us. Awesome. Hello everybody. It is so nice to meet you. My name is Isabella Velásquez. I have the great pleasure of working with Rachel at RStudio and I am a senior product marketing manager and I focus on the strategy and the content creation for the RStudio blog.

I am almost at my one-year mark here at RStudio. It's been an amazing time. I'm active in the R community and sometimes I post on my personal blog on topics like data cleaning and other data science things. And I gave a talk on building a blog with R packages like Blogdown and Distill a few months ago and I am really excited to talk about building a blog with Quarto with you today.

First up, I would love to hear from you. Do you have any technical blogs or data science blogs that you love to read? Please put them in the chat and share why.

To get started, I am actually going to do something a little different today in that I don't have slides. I have everything available as a Quarto blog and will be going through content this way. And one reason I wanted to try this out was to showcase the really cool things that authoring in Quarto can do. And so all of the code is available on GitHub if you see something and you'd like to replicate it on your own Quarto blog.

And so for today's agenda, we're going to be going through possible reasons for creating a blog, a recap of Quarto, which is an open source scientific and technical publishing system built on Pandoc, how to create a website in Quarto, and then more specifically how to build a Quarto blog and write posts. And so we do have some assumptions for today. First is that you know a bit of R and R Markdown. Second is that you know about Quarto and just need a bit of a refresher. So I won't be covering everything in full detail today, but if you find yourself wanting to start from the beginning, you can watch Tom Lok's webinar from a few weeks ago called Welcome to Quarto to Catch Up.

And finally, we assume that you're interested in using the IDE for RStudio Desktop. So we'll be using RStudio for this talk and running the commands in the IDE. On the Quarto website, there are step-by-step instructions if you use VS Code or JupyterLab, as well as anything you may need for running the command line instead of RStudio.

And so for how today will work, you have a few options. So this website is available at rstd.io build-quarto-blog. And you can click the GitHub icon up here if you'd like to see the source code. If you'd like to follow along the exercises I have, you can clone the GitHub repository available at rstd.io-quarto-blog-exercise-repo. And you can follow along in the example blog that I've created for you. You can also work off the RStudio project available at rstd.io-quarto-blog-exercise-cloud.

And the advantage of RStudio Cloud is you don't have to install RStudio on your computer. Everything can be done in your browser. You could also create a whole new Quarto blog on your computer, which we will cover in a few minutes. But it won't have the notes that I included, and you have to make sure that you have the latest version of R Markdown installed.

So no, I won't be stopping for the exercises very long. So another way that you can participate is just follow and listen to my soothing voice. And the recording will be available on YouTube immediately after this presentation. And the GitHub repositories and RStudio Cloud project will remain up and available to you as well. And another thing is across the site, I'll have links to the Quarto website's documentation's relevant page. So the Quarto documentation is excellent. I honestly recommend reading every page. And so we're just going to cover the basics of creating a blog. But say you have a question like, how do I write this? How do I do this? Please check the documentation first.

Why build a blog?

Awesome. So before we dive into using Quarto, you may be wondering, why should I build a blog in the first place? So while the title of the talk is building a blog with Quarto, let's talk generally about different types of websites. So blogs are a certain type of website that usually have a chronological order. They can be indexed and syndicated on RSS feeds. And while some website pages are static and not updated very frequently, a blog is dynamic and usually updated pretty often. There are other forms of websites that support dialogue and knowledge like forums and wikis. But blogs specifically add time as a factor to consider as they will only be successful with continuous engagement and creation. And the type of content is different too. So more real-time events. So while we're talking about Quarto blogs today, just know Quarto actually supports other types of websites as well.

And so we should also talk about why build a blog. And so I'd like to share some insights I've gleaned from really amazing talks by David Robinson, Miles Salmon, Rebecca Barter, Alison Hill, and many others on this topic. And I have a link to a YouTube playlist on the website for you as well. So you may have heard David Robinson's advice that if you've shared something three times, it's time to write a blog about it. And so in terms of the skills needed for data science, a blog can help showcase collaboration and communication. A blog provides a platform to share the things you've learned, like any cool packages you've tried or created, how-tos, other processes, and write about your opinions, give updates, and so much more.

Another thing about blogs is they provide a platform to practice writing for someone other than yourself. And they can form a sort of portfolio that makes it easy to share. And since it's all in one place, it allows for centralization of your work rather than having it in different spots. And so here are some examples of existing Quarto blogs. And we can learn about these writers and the awesome stuff that they're doing, and how they can help you with that. And not only that, they also share their knowledge in that they also share their code. And looking at other people's code is a wonderful way of learning. And I really highly recommend doing that when you're creating your own Quarto blog. I know I did.

Another thing about blogs is they provide a platform to practice writing for someone other than yourself. And they can form a sort of portfolio that makes it easy to share.

And so usually we talk about reasons to create a personal blog, especially if you're looking for a job, say. But I also want to note your team or organization could benefit from having a blog as well. So external blogs, like the ones we have at our studio, are examples. We keep the community up to date with events and product updates. We share stories from others who use our tools to show what's possible with them in a variety of contexts. And internal blogs and organizations can help you share information between team members in an easy and efficient way. So have you ever tried to find some advice that your colleagues sent to you via email? It can be really hard to find. And so with a blog, key information can be searchable and in one place, speeding up communication. Folks can search for information from the past while easily seeing what's the newest info. It also gives your colleagues the opportunity to collaborate and share thoughts very quickly rather than having them siloed in conversations or in email. And ideally, it fosters a community that's open and inclusive and shows that you care about each other's work and opinions.

And so in terms of the sorts of posts that you can consider for your blog, let's say we want to create a blog for an internal data science community. Topics can include the reflections on projects that just happened, how things went, lessons learned, where to find outputs. And besides the type of post, you also want to consider the content of the post that you create. So it's about finding a sweet spot between length, media, like text, images, and photos, and other formats that resonate with your audience. And so here's an example of using a blog listing page to showcase various talks and presentations.

And so when considering building a blog, ask yourself, why do you want to create a blog? And having a clear goal can help you develop your blog and explain its purpose to others. And then what are the values you want to instill in your blog that's meant to be a place for inclusivity and openness and motivation? You want to make sure that your blog demonstrates those values. And then what is valuable and relevant content? So key to the success is knowing what others would find valuable and relevant and making sure that is what is put on the blog. And also, you don't want your blog to be a big imposition or burden to maintain. If it's something that's easily done or even fun, then it's a lot easier. And there's a technical aspect of building a blog. Hopefully, you can build the skills and the infrastructure that you need to keep your blog going. And with that, we can get to the technical part.

What is Quarto?

So let's start off by saying, what is Quarto? As I mentioned earlier, you may have joined Tom Locke's webinar from a few weeks ago called Welcome to Quarto. If you did not join, I highly recommend watching the recording on YouTube. Tom does a spectacular job introducing Quarto and how to author documents. He's been a major help in putting this presentation together. So thank you so much, Tom. I'm going to do a high-level recap of some of the points mentioned in the webinar that are crucial for explaining how to build a blog with Quarto. So first up, what is it? It's an open-source scientific and technical publishing system. In terms of how it works, while our markdown needs are to run, Quarto is a command line interface that does not need any programming language. Quarto renders plain text like markdown files and mixed formats like Jupyter Notebooks into static PDFs or Word documents or HTML pages, reports, and like we'll see today, websites. And so Quarto is not language-specific, meaning you don't have to have any particular programming language to run it. So for those of you who use our markdown, it lets you go beyond R and mid-R and use other languages like Julia or Python natively.

So Quarto also allows you to have client-side interactivity, which means that you can run Shiny apps directly in the browser. And Quarto also has built-in native JavaScripts like HTML and observable.js. So here's an example of a Shiny app within a Quarto document. You can see it changes just within the browser.

So Quarto is also not tied to any one integrated development environment. Authors can use RStudio VS Code, et cetera, and different members working on the same Quarto project can use different tools to write their documents rather than having to conform to a specific one. Essentially, Quarto lets you mix and merge and interact across languages, so it's a very big deal for folks in all different communities. If you want to see everything that Quarto can do, you can run quarto-help in the terminal. Discussions and bug reports can go on GitHub. There are a lot of friendly folks on Twitter and the RStudio community where you can go to the Quarto tag and ask questions, as well as in FAQ as well.

So now that you know what Quarto is, let's discuss why you may want to use it to build a blog. So if your work is technical in nature, it's helpful to use the same tools for writing in your blog. If you're going to write about data analysis, then it makes sense to use a tool that lets you see and run the code. So in my early days of blogging, I used a popular platform, and anytime I'd write R code, I'd have to change the little lesson sign to manually each and every time. And so things were not reproducible for the readers, which is not good if you're trying to write, say, a tutorial. So it was a big pain. And so writing with Quarto means that you can do all the nifty things that you usually can do, like have syntax highlighting and executable code while you're writing the text. And you know when you run it, you'll get the same output as before. And there's also other things that make it easier, like integrating with GitHub, having full control of your page, all static files, no databases or logins.

So one question you may have, especially if you are an R Markdown user, is whether you need to use Quarto to create a blog. And the answer is no. The R Markdown and the down family are not going away. So the blog down and distilled packages are still excellent options for you. And so if you like using R Markdown, there's no reason to switch. R Markdown will continue

to be supported and work as it always has been. So the switch is not impacted. But if you're on a multilingual team or primarily a Python user or want to use the features available in Quarto, then you may consider trying it out. All right. Now let's talk about Quarto and RStudio.

So as I mentioned earlier, we're going to focus on Quarto in the RStudio IDE. Quarto is now included with RStudio version 2022.07.1 and above. So what that means is that there's no need for a separate download or installation if you have the latest version of RStudio. So if you'd like to follow along with the exercises, please make sure that you have this version ready to go.

RStudio has a bunch of features that make technical authoring easier. So one of these is the visual editor mode. So if you write Markdown code, it will render changes in real time. And the visual editor mode includes extensive support for Quarto, like adding tables and images and citations, all sorts of things. And so here, I'm going to show you how to use Quarto in RStudio.

And so here is an example. We create a heading and see it immediately, and we can type it out. From here, we can go to the editor toolbar and insert a table, add a caption if necessary. And then I have render on save on, so I can preview my site and see what it will look like. So the table is down here. And so say I want to change from column one to column A. I could change that and then save, and then the preview will update so I can see what exactly it will look like. And there's more documentation. In addition, the IDE has a nifty outline feature that makes it easy to scroll through your document. So here is an example. The outline is there on the right, and clicking on the different headings takes us to that part of the page immediately.

YAML intelligence in RStudio

And one last thing I wanted to mention is the YAML intelligence. So YAML stands for Yet Another Markup Language. It's the metadata of your document, and it's included at the top. So what it does is it uses key value pairs to denote what options you'd like to specify in the desired choice, and YAML also has options to control more about our document as well. So it's very particular. You have to be very careful about the characters that you use, the spacing that you're using. So just take a note of that. If you've ever run a document and encounter an error, make sure your YAML is correct. And so in the RStudio Visual Editor, YAML completion is available for project files, front matter, and executable code options. So that means when you type YAML and press tab, it will give you a list of the options to complete your YAML field. And this is both for the option name and the option selection.

And so here is an example. I start typing what I want. I see the list that is available. Scroll to the one I want, and then I also see a list for the possible options.

And to note, the IDE will also highlight if you have incorrect YAML. So it will highlight the error and when the documents are saved. You can see this little red X. Okay, with that quick intro to RStudio and Quarto, now let's get started building a blog.

Building a blog with Quarto

All right, let's build a blog with Quarto. So project directories, or Quarto projects, I'm sorry, are directories. They provide a way to render all or some of the directory files with a single command. They share YAML configuration across multiple documents. They have the ability to redirect artifacts to another directory. And also you can freeze outputs. So let's go ahead and to another directory. And also you can freeze outputs, which we will talk about in more detail later.

So one type of Quarto project is a Quarto website. And so this is a convenient way to publish a group of documents. And documents that are published as part of a website share navigational elements, rendering options, and visual style. And they can be published to a variety of destinations. So Quarto websites, books, and blogs are very similar in that they associate these multiple pages and resources into a connected resource. And so like we talked about earlier, there are specific things that make a blog a blog. And so a Quarto blog is a Quarto website with specific opinions already made. And it includes a listing created from a directory, and we can customize those listings in various ways. So let's get started.

Like with everything else, you could use the command line to create the blog. Alternatively, we're going to use the RStudio IDE by going to file, new directory, giving the directory a name, and opening up the project. And this will create the scaffolding for a simple blog.

So here is a video, go to file, new project, new directory, Quarto blog, give it a name, create a new blog, create project. And there on the bottom right, you can see the scaffolding that has been created.

Previewing and rendering the site

So there is a workflow that you should use to view your site. You could, again, use the command line interface, or you could use RStudio's build tab to render and preview a website. So my recommendation is to first preview the website, and make sure that render a save is on. So every time that you save a file, you can see what changes have been made in your viewer or in your browser. So here is an example of clicking render and save and previewing the site. When anytime I type something and save, I can see the changes in the viewer.

Here's render and save, preview website. I'm going to add some text on this page at the top. When I save, I can see test test showing up there on my website now.

And so, note, if you make changes to the global options, you'll need to fully re-render your site to have all of the changes reflected. And you should always fully render your site before you deploy it to your publishing platform, even if you've already previewed the changes to some of your pages in this viewer.

All right. If you want to try out the exercises, you can now either create a whole new blog in RStudio, clone GitHub repository, or open the RStudio cloud repository. RStudio cloud project. And so, like I said, I won't be leaving too much time to go through this, but I will do it on my own screen if you'd rather just watch.

So I have the RStudio cloud project here. And I will see the project.

Isabella, do you want me to ask any questions? Oh, yes, of course. Okay. There's a few questions that are coming in right now. And one was from Scout. Is it possible to add a blog to a project that began as a Quarto website? Yes, that's right. You can. And so, if you start off as a Quarto website, essentially what defines a blog is having this listing page that we will talk about later. And so, you can create the listing page by adding it as a Quarto file later on, if you decide that you'd like to have a blog. So, yes.

Awesome. Thank you. And somebody else had asked what is the blog that you're using in the presentation. So, I just wanted to show that here on the screen again as well. Sure. Should I switch back to it? Nope. No, I just put it up as like a caption. But I'll keep some of the other questions until after you go through this as well.

Thank you. Yeah, for sure. So, we're going to be talking about styling your blog a little bit later. In terms of the theme I'm using, it's the Litera theme. And then I did some custom HTML in order to make the fonts and the colors look the way that I'd like. And so, if you look at the source code of the website on GitHub, you can see, you know, what exactly does the CSS look like, as well as the website configuration page, which we will talk about in a little bit. And yeah, there's like a lot of different ways of customizing your website to make it look, you know, exactly how you would like.

Cool. And so, here in the RStudio Cloud project, for this first exercise, it is previewing the website just to have it ready to go for whenever we make changes with the exercises later on. And so, previewing the website gives you the view that you're interested in.

All right.

Oh, it sounded like you were underwater for a second. I think maybe. Sorry about that. Okay. So, I'm trying to find my place. And then I'll be right back. Okay.

Blog scaffolding and the index file

Okay. Excellent. Awesome. So, when you create a blog for RStudio, you'll see some automatically created files in the project. Like I mentioned, the bottom right. And so, let's go through each of these. So, first up, we're going to talk about QMD file. This is your home directory, which will be the landing page for your site. So, when somebody goes to www.yoursite.com, this is the first thing that they will see. And so, in this default blog, it is a special type of document called a listing page that lists all the other documents. So, when creating a new blog, the listing page or the landing page will default to this listing page for the documents in that post directory. That is, it will default to your blog. And so, there are ways to customize. Like, say you'd rather have the about page as your landing page. Whatever is your index.qmd file in your home directory will be your landing page. So, you could change that to index.qmd and change your current index.qmd to something else. And I've listed a blog post on how to do this under the resources of this website. And so, this is the YAML in your default index.qmd file. So, it helps configure that document. So, let's talk through each line.

So, in title, title is the title of your listing. Listing generates the content of a page or region of a page from a set of portal documents and other custom data. And so, this is essentially what makes up a blog. Contents control what documents are included in the listing by specifying a list of input files. So, in the default blog, the listing includes all the portal documents in the post directory. Or all the, I'm sorry, all the documents in the post directory.

Sort controls the order of the listing. So, by default, it is, will be ordered by their date. You can also change it to title. You can also change it by title instead. Change it to ascending by using ASC. Here's by title. And you can also sort it by more than one attribute, like so.

Type controls how the listings look. There are three built-in types of listing that you can choose from. So, there's grid, there's table, or there's default. And you can also create custom listings by using embedded JavaScript templating. So, or EJS. So, EJS is a templating language that lets you generate HTML markup with plain JavaScript. And so, just to toot my own horn, this is what my personal website looks like. And so, you can control things like the placement, the size, and all sorts of styling for your listing, if you would like, with EJS.

And so, with categories, you can add a list of categories to the listing page. You can see them here on the right. And so, when users click a category, the page will be updated to only include the listing items that match that selected category. So, you can also choose from a few different displays. So, by default, it is numbered. You can also choose unnumbered or cloud.

The sort UI will give users a selection box to choose how to sort the items in the listing. By default, the sorting control allows the user to control by title, date, or author. And you can also control which fields are included by providing the list under sort UI, or you can also just turn this off by setting it to false. And filter UI is similar. It provides a filter box position on the top right of the listing content. And the filter box allows readers to perform a search of the listing contents. And you can also disable this option.

Page layout controls the layout used for the page. By default, Quarto documents display content centered or at a width that's optimized for

readability. But if you want to use other layouts, you can customize it here.

And then there's title block banner, which positions a formatted title block at the top of the page. And so, we'll talk a little bit more about this later. So, now let's go back to our exercise. So, in the index.qmd file of your Quarto blog, change the title of your listing page, add another listing type, change sort to date ascending, and see what happens when you change filter to true. So, if you open up, say, your project, the index.qmd file is here in your home directory. I won't say in case you're trying to do this on your own.

And I've also included the instructions down here. Another listing type.

So, if you tried it out, you should be seeing a new title, a new listing type, a filtering, and also a different way of organizing the blog posts.

The about page

Cool. So, now let's move on to another file that's automatically created, the about.qmd file. So, the about.qmd file is a special template that's designed to present a person or organization. It'll be automatically included or added when you build a blog. And so, please see the YAML here on the right. Let's walk through each line of the YAML.

So, again, title will be the title of your about page. Image will be the image for the about page. About tells us to use the special template that looks the way that you can see there. And then template controls more specifically how the about page looks. And so, there are five built-in templates you can use. There's Hoya, Treles, Solana, Marquee, and Broadside.

Continuing on in the YAML, links share a set of links to other resources. So, you can add URLs and text and icons. And so, there is a note by default, the about page will be rendered using the entire documents of the page. You could also choose to only use a portion of the page to populate the templates. And there's more about that in the Quarto documentation.

All right. So, let's go back to our exercise. In the about.qmd page of your blog, edit the title of your page, change the template to Marquee, and update the links to your own profile pages.

And so, if you have done that and go back to your preview, you should see the updated about page now.

The _quarto.yaml configuration file

Okay. So, the next file we're going to dig into is the underscore Quarto.yaml file. So, this is the configuration file for your website. And here's what the YAML looks like. So, let's walk through each line together.

Project is the type of the project. So, whereas a blog is a specific type of Quarto website, you could also do a book or other sorts of projects. And the configure title is the title of your blog. And then there is the navigation bar. So, this is the top navigation bar that you can see. And right specifies to write this in the right side of the top navigation bar. You could also do left. And then the following three are the files to be linked. So, these can be pages inside and outside of your website. And just a note, there's also a sidebar and hypernavigation if you want to check those out in the Quarto documentation.

So, like, let's try this out. So, in the underscore Quarto.yaml file of your Quarto blog. Oh, I apologize. I missed this. I forgot to mention. So, the features and functionality are very extensive and you have a lot of options for customizing your site. So, for example, you can change the color of your navigation bar by adding background and then a color underneath. And there are also options for the individual navigation items. So, while up top, the default blog has links to share, here we are just sharing some text. Like so. Now, let's try it out. In your project, open up the Quarto.yaml file, change the background to a different color, add another hyperlink, and then add your name to the left side of the top navigation bar.

And change the background.

So, one thing to note is, again, spacing is very, very important in YAML. So, make sure that you're lining up things accurately.

Saving that. Gives us this new configuration. In my case, I made it a red banner. I called it new site.

Themes and syntax highlighting

So, the next section of the Quarto.yaml file adds your theme. So, blogs can use any of the 25 boot swatch themes that are included with Quarto. You can also create your own themes. And so, the default blog uses the Cosmo theme. And the Quarto websites will also let you do dark and light themes. But we'll get to that in a sec. So, here's an example of some of the boot swatch themes. Cosmo, the default. You can change it to darkly by specifying theme darkly. Or another one called sketchy. And I've included a list of the 25 over here.

And so, if you specify a dark theme, a toggle will allow your readers to switch between light and dark. And so, you specify it in your Quarto.yaml file by adding light and dark underneath theme. And then the themes that you would like. And here's an example of the toggle up top. And it just moves back and forth.

And another thing that if you'd like to customize is you can change the syntax highlighting or the color of the fonts of your code chunks. And so, you can run a command line interface to see all of the options or use YAML intelligence to see all the options as well. And so, here's an example of the Espresso highlight theme or highlight style. So, you denote it this way. Here's what Eiffel looks like. Or ZenBurn. And so, if you like, you can try it out. Change up your theme on your Quarto blog. Add a dark theme with another boot swatch theme. And then change the syntax highlighting to Espresso. So, Quarto.yaml file.

I'm going to change this to... Let's see. Which is the one I'm using for my current. Here is the syntax for light and dark. And then finally, syntax highlighting is by using highlight style.

And here's the YAML intelligence.

And here's the Espresso style.

And now, we can see the new theme has been added. I don't have any code right now, but if I did have code, you would be able to see it. I should have added it. Apologies.

CSS styles and the styles.css file

And so, last thing that's on that Quarto.yaml file is the styles.css file. So, this is the CSS style sheet. So, CSS style sheets, stylized elements, written in markup language. And so, you can change things like what your headings look like. So, the default blog comes with a file called styles.css. And you could also use a Sass file instead of CSS. So, Sass stands for syntactically awesome style sheets. And it's a great way of modularizing your CSS and generally making styling a bit easier. So, let's change the title or sorry, the font of our headings. So, you can in your styles.css file, add this command or this script, and then it will change the font in your blog. So, in here, if you have I'm just gonna copy and paste it a bit faster.

Save it. This might be one of those global configurations that you need to rerun. There we go. Like I mentioned earlier, some things will show in the preview and some things you'll need to fully re-render your site. In this case, we were able to see our new font after we re-rendered.

In this case, we were able to see our new font after we re-rendered.

Adding a blog post

All right. Congratulations. We built a blog with Quarto. And so, now that we have our listing and our page looking the way that we'd like, we can write a blog post. So, let's create a new post. So, posts are saved in an individual folder. Oh, sorry. Posts are saved in a folder. Here, you can find it. Post. And then each post is an individual folder within a document saved inside. Like so. And by default, in the default blog, the posts that make up the contents of the blog are located in the post directory. And you can add a new post by creating a subfolder within the post folder and then adding an index.qmd file inside that subfolder. And you can create these manually or, as usual, you could also do it through RStudio, whatever works best for you.

So, this is what it would look like within RStudio. You could do new folder, give it a post name, and then create an index.qmd file by new blank file, and then providing it there.

So, that qmd file is the new blog post. So, when you render the document, the home page will automatically update to include the new post at the top of the listing. And the folder name will be the slug or the part of the URL that identifies the page. And the name of the qmd file will be the latter part of the slug. So, if you want your post to have the names of your folder, you would just call the post index.qmd.

So, additionally, you can also add a metadata.yaml file to the post folder. And that creates shared metadata with all the files in the folder. So, while the Quarto.yaml file sets a configuration for the entire website, this is only to the post within that post directory. So, if you open up the metadata.yaml file, when you create a new blog project, you'll see this freeze set to true. So, when a post is rendered with freeze set to true, the markdown output from the underlying engine, like Jupyter or Nidar, is saved. And so, when the entire site is rendered, those computations will not be rerun, but read from previously frozen results. So, essentially, if set to true, freeze means only rerun when I explicitly say so. And this can save a lot of time when you're trying to rerun all the documents in your website.

And as mentioned earlier, there's also a title block banner, which creates a banner style title block for all the posts in the listing. And so, this can be a color. It can also be an image. So, let's try this out in our own blog and change the title color banner to color to something else and then go check out one of your posts. So, within the post file or folder, there's the metadata.yaml. And let's just

change it to this color. I closed my preview.

So, clicking on a post gives us that new banner color. And so, one other thing to note.

Sorry. So, now let's go into a file within a post folder. Again, you'll see the YAML set up at the top of the document. Let's go through each line. Title is the title of the post. Author is the author of the post. Or you can also have multiple authors. You can list them with a list or like so. There's two different ways. Date is the date of the post. Posts for the future will still show up on your site. Please note. And categories are the categories that you have set up for your posts. So, categories are set to true in the core.yaml configuration file from before. You'll see these categories show up on your listing page. And like authors, there's a few different ways if you'd like to write multiple categories for a single post. And note that you can also set your post as drafts to true so that your post doesn't show up even if you have deployed your site.

Creating a new post

So, let's create a new post called my first post. And then create the YAML for the file. So, we could do that. In the post folder.

There we go.

Just so you can see what this would look like.

You could set it up this way if you'd like.

Sorry about that.

And here's my new post in the listing page.

All right. So, with that, below the YAML that you just created, you would actually write your post. So, let's see how to author some posts.

Q&A

Rachel, any questions so far? I know that...

Yeah. Lots of questions.

I'm looking at you.

Yeah. Definitely. Thank you.

Go over to... Let's see. We'll ask one from LinkedIn. I see Deepsha just asked. She said, this is great, Isabella. How did you add the videos with play buttons and also the RStudio snippet where you live wrote the code and ran it on the fly within the blog? Is that as an aspect of RStudio Connect or is that a Quarto functionality?

I see. So, the videos that I'm playing, that's actually not either. That's a video site called Wistia that lets you embed videos. So, the embed file or, sorry, link is through HTML. And then I just... You can embed any HTML that you'd like into a Quarto document. And so, that's how I have embedded the videos.

Awesome. Thank you. Another question from earlier was, so, does Quarto work with Hugo and BlogDown?

Yeah. So, you can actually add Hugo to your Quarto website. And there is documentation on the Quarto website, documentation website, quarto.org. And I have to admit, I haven't tried it myself. When I switched over to Quarto, I just stopped using Hugo. I came from BlogDown. So, definitely check that out. And I do have a section on migrating from RMarkdown that I'll try to make sure that we get to.

Okay. Awesome. I'll ask two more questions here, and then I'll send it back to you with a presentation. But Santiago had asked on LinkedIn, is it possible to host the blog somewhere other than Quarto Pub?

Yes. I'm actually going to go ahead and skip the literate programming in Quarto, just because Tom does a fantastic job covering this in his previous webinar. And if you're familiar with RMarkdown, it essentially just goes through how to build things, etc. And so, we'll talk about publishing in your blog next.

Okay. Awesome. Okay. Let me just do over to one more question from the Slido, where just a reminder, you can ask anonymous questions over on Slido as well. And somebody had asked, can you put a bunch of HTML files in the posts folder and have it render in a listings page?

Yeah. There are different ways of adding documents that you didn't create through Quarto to Quarto. If you go to the Quarto documentation and look up resources, it shows you how to do exactly that. And actually, the example that I showed from Sylvia at the beginning, she had creating a listing page with her talks, and none of the talks were actually hosted on Quarto, and she was still able to create a listing page. I recommend looking at that. That's under introduction, create a blog.

Awesome. And the first one that you said was in the documentation, is that the document listings section? I was just trying to find the link to share. We could share them after. Awesome. I'll send it back over to you, and then we'll see some other questions for after too. Yay. Thank you. Awesome. So, yes.

Authoring posts and publishing

Actually, I'll just show this really fast so you know what exactly is here. But like I mentioned, this will just cover some markdown basics. Fenced divs are amazing. Again, if you've never seen these before, I really, really recommend just checking all the different options that you have, the things that you've seen, like those call-out notes or the tab sets throughout this website or through these fenced divs, and they're super cool. I also know a little bit on using Julia and other programming languages within Quarto and how to render the documents, which is very similar to what we have been seeing with rendering the website. So, if you are interested, please check out the section with the cute cat with glasses.

And in terms of publishing your blog, yes, you can publish Quarto in a variety of ways. I chose Quarto Pub, which is a free service that you can sign up for that's very nice for hobby projects, things that you don't mind being public, and things like that. In addition, you can also use things like GitHub Pages, RStudio Connect, Netlify, all these other sorts of platforms that let you customize your website in the way that you'd like. So, if you'd like to use continuous integration so that every time you change your site, you know how to render, things like that, you can configure these platforms as you wish. RStudio Connect is a great option if you're within your organization and you want your blog to be private and shared among your team members. Netlify also has options if you have a bigger website that you want to host or if you want to add password protection and things like that.

And so, in this case, I used Quarto Pub. It was actually my first project on Quarto Pub, so that was pretty exciting. Like I mentioned, you have to know that it's publicly visible, that it has a size limitation, but generally a really great option for hosting your website. And so, I won't go through how to do this, which is on account of time, but if you would like to publish the Quarto Pub on your local computer, you can do so after you set up an account and running Quarto Publish, and it will literally walk you through every single step that you need in order to publish your site. And then your site will be online, like this one is.

And one quick thing to know, if you'd like to publish your blog, say the one that you're creating on RStudio Cloud, it is slightly different in terms of the steps involved, but it's not too many more steps. You just have to manually give your RStudio Cloud account your access token as opposed to using the built-in Quarto Publish ability of like opening up the authentication in a new page. So, just wanted to note.

Migrating from R Markdown

And for some other things in terms of migrating from R Markdown, this isn't specific to Hugo. Just in general, if you're interested in R Markdown, if you have a bunch of R Markdown posts and you'd like to move them over to our Quarto blog, it's just some things to note. This is actually the process that I went through migrating from R Markdown to Quarto. So, Quarto can render any existing R Markdown document without really changing too much. And if you change .RMD on the file name to .QMD, it forces it into a Quarto document. And so, that is essentially what I did. I just took all my post folder and I pasted it over to my new project, my new Quarto project. And so, if you do run into any errors, just go into the file and see what occurred. So, one thing that I ran into is the YAML categories in my old blog were different than they were in Quarto. So, for example, like summary is now description. So, I had to go through and manually change all of that in the YAML in order for it to run. But if you look at the source code, they're actually all still RMD files. I didn't change anything within the text itself. Just had to change the YAML.

And so, one other thing to note is Quarto uses a different styling for the code chunk options. So, whereas before they would be listed on the first line of a code chunk, now you can add them within the code chunk itself using this very handy hashpipe comment. And so, like so. And one thing to note, though, you can still use the old way of doing it, but we recommend switching over as it will help with compatibility in the future. And so, in the newest version of NIDAR, which actually very recently came out, there's actually a function called convert chunk header that you can use. And it will help you convert all your old in header chunk options to the new in body chunk options. And so, this is what it looks like. You would give it the file to convert and then the output file that you would like. And it doesn't have to be a Quarto document. It can also be an R Markdown document.

And thank you all so much. I really appreciate being able to build a blog with you. I added there's so many fantastic resources, both official Quarto documentation and just amazing examples, tutorials, and features from the community. So, like so many of the things that you saw today were contributed by members of the community. Quarto has extensions that lets you modify the behavior of Quarto. So, those things like being able to click on a picture and having it zoom is a Quarto extension that you can install. In addition, there are specific things that you may like to add to your blog, like RSS feeds and subscriptions. And there's detailed documentation on how to do that as well.

And like I mentioned before, if you are interested in migrating, you may want to add redirects to your slugs. And so, Daniel Navarro wrote an awesome post on how to do that, as well as more information on continuous integration. So, really like check out the Quarto pub hashtag on Twitter, follow along on GitHub, and just really check out all the really amazing things that are happening around Quarto. So, thank you.

Awesome. Thank you so much, Isabella. That was great. I see a lot of you can't see this right now, but a lot of people in the chat right now just saying awesome overview. Thank you so much, Isabella. There are a lot of questions here, so we'll make sure that we get to them as well. But also, so everyone knows, Isabella runs the RStudio blog, so I am sure that we will get some of these questions covered in a blog post, too.

But let me go over to some of the other questions. And if you want to stop your screen share, you can see them as I pull them up, too. Here, I'll pull it over. Okay.

One of the questions earlier was, what does Quarto offer over Blogdown?

Yeah. So, it really is what tool you would like to use. So, Blogdown specifically uses Hugo, as well as R Markdown. And Hugo allows folks to really heavily, like, customize their blog exactly the way that they would like. Perhaps it's just, you know, a tool that they prefer. And so, if, you know, if that is your preference, then there is, again, no reason to switch over from Blogdown. Specifically, like, what does Quarto offer over Blogdown is those sorts of Quarto features, like being able to use other languages like Python and Julia natively, being able to use the other features that are being developed in Quarto. And so, again, it's

just, like, what is the right tool for your blogging platform, and then deciding and going with that. Great. Thank you. I know you just briefly covered the extensions at the end, but Eugene had asked, do you use any Quarto extensions? Yes. And so, if maybe I can share my screen, let me find it really fast. Can you see my screen all right? Yes. Yeah. Awesome.

So, this in particular is called a Lightbox extension. This ability to click into a photo, scroll through them, have it, like, kind of pop up and have a background so that you can focus on it. I've linked to it here. It's called Quarto Lightbox. In terms of installation, you run something on the command line, add the feature to your YAML, and then you're ready to go. Another one that was posted pretty recently is this Quarto Nutshell extension. And so, I didn't go too deep into this, but say you have information that you want some folks to click on and some don't, or some not to, this extension lets you do this little, like, drop down of more information if you click on this link. And so, a very handy little extension. And so, yeah, there are lots of things that are being developed. And so, another extension that I linked to in the resources is being able to use shortcodes for Twitter and for YouTube rather than having to embed the HTML. So, lots and lots of different extensions available.

Q&A: post formats, navigation, and rendering

Cool. Thank you. Another question, I think this maybe came over from LinkedIn, but Corey asks, so the posts don't have to follow the standard year, month, date format like in Distil? No, there are ways of customizing it, and you probably know what I'm going to say. It's in the Quarto documentation. Great. Yeah, and you can try and find these specific links to the documentation too. Yeah. Another way is, oh, sorry, the EJS template name that I mentioned that lets you, like, control how to customize your listing is another way of controlling what the date looks like too.

Okay, cool. I see. Also, Jeff asks, how do you navigate through your Quarto blog through the browser? It doesn't seem like you're clicking anything. Oh, I was actually clicking on something. I didn't know that. Yeah.

Let's see. Lots of great questions. Thank you, everybody. Somebody asked anonymously, how can I render my QMD files inside GitHub? Oh, I have to, I don't know. You have to follow up on that.

Great. Let me see. Sorry, I'm collecting things from all over the place. On YouTube, LinkedIn, or Slido. Let me jump back over to YouTube. Can, somebody had asked, can we have the same QMD file for a blog and a book? This, I am not sure. If I had to guess, I would say that you would need to have separate projects, and perhaps you can link across projects. But this, I would also have to double check.

EJS templates and listing customization

And I know you just touched upon EJS, and I might need to be reminded of exactly what that means. But Jason asked, would EJS be the way to add a new listing option, such as location? Yeah, that's right. And there are other ways of adding, like, different fields, you know, if you are interested, as well. Okay. And could you explain EJS again for me? Sorry. Yeah, of course. So, it is a template that lets you use HTML for, oh, sorry. I had it, like, written down. But it essentially lets you use HTML to create JavaScript templates. Okay. Yeah. Great. Thank you.

Okay. We'll take a few more questions here. One fun one is, great presentation, Isabella. Did you draw the cats? I did not. I would have loved to draw the kitty cats for you. They are both from the AI generator called Dolly. And so, I would do things like illustration of cats, maybe with printing press. And also, raw pixels, which provides public domain illustrations and images, as well.

R Markdown migration and reproducibility

I'll have to play around with that. Somebody had asked anonymously, the challenge for R Markdown migration is that the code or data from old posts is stale. What do you do then? And they mentioned using freeze going forward. Yeah. That's very, very, very true. There are some blog posts out there that share a workflow for making your blog post reproducible, like, from R Markdown. There are things like using RM and to record things like the package version. And, you know, you could get even more by using Docker to, like, specify the operating system and things like that. And so, yeah. It's very much the case that freeze will definitely help in terms of, you know, if you're using a Quarto blog moving forward. But if, you know, if you have a blog post and it's using an old version of a package that in the function no longer works, it may have to just, like, update the yeah, I would say, like, you either have to update your code or if you have, like, the HTML rendering of that R Markdown file, you can port that over to Quarto instead and try to, like, mitigate, you know, all the manual work that you're going to have to do.

It's very much the case that freeze will definitely help in terms of, you know, if you're using a Quarto blog moving forward.

Upcoming meetups and community events

Thank you. I see a question here that might actually be for me. But what Victor asked, when is the next meetup? So, we have meetups like this every Tuesday at 12 Eastern time. So, the same time as the one today. And then we also have a data science hangout every Thursday. And so, those are a little bit different. But the hangout every Thursday is not a presentation. It's just an informal time for the community to join and ask questions to a different data science leader each week. So, Tiger Ting from Carfax is joining us this Thursday if you want to join us at that. And if you want to join the next meetup next week, we have a talk on collecting and acting on employee engagement data at the Veterans Affairs and using Shiny. So, that will be a great talk as well. I'm going to share on the screen right here just where the calendar of those events is too. And that's actually the first Quarto document that I ever made.

Extensions, accessibility, and publishing

Let's see. Okay. I'm going to ask you just a few more questions. Is that okay? Okay. I see Arun asked, can we use custom icons or the about.qmd similar to postcards? Yeah. So, oh, I forgot to mention, this is also an extension. There is a Font Awesome extension that lets you use Font Awesome icons. And actually, the GitHub icons that you see throughout the website are from that extension. And so, yeah. So, I recommend looking that extension up.

Great. And I see Abu Bakar, you asked, you said publishing to Quarto Pub is free. Please explain more. I was going to share the link to Quarto Pub in the chat as well. But Isabel, if you have anything else to add, you want to jump in? Yeah. It's exactly that. You can sign up. You'll have an account. When you press or type Quarto Publish on your blog, it will ask you to authenticate. So, if you're already logged into your browser or you log into your browser, when you come back to your, say, RStudio ID, then it will let you publish it directly there. Like I mentioned, there are a few limitations. I think it said like 100 gigabytes for the site and a soft limit as well. And another thing to note, your documents will be publicly available. So, you have to make sure there are things that you're okay sharing with other people. But yeah, completely free.

Thank you. Another great question on Slido from Mary, does Quarto have any built-in accessibility tools or a checker to be sure the blog meets accessibility requirements? Yes, there are a ton of accessibility features. And during the development process, this was like consistently part of like, you know, what do we add? How do we add it? Like, how do we make sure it's available? Of course, the Quarto documentation goes into it. One example is in the, say, the top navigation toolbar. If you want to add accessible links to that title, href icon or whatnot, you can do so. If you check out a Quarto tip a day, and I have linked that in the resources as well, if you go there, there are actually several posts there on specific accessibility features that you can use in Quarto.

Awesome. Thank you so much, Isabella. I think we got to most of the questions. I'll just do a double check here in the chat. Oh, one more question that just came in. Can we use, is it Reveal or ReelJS slides on Quarto Pub? Yes, I believe so. I think anything published on Quarto can be published in Quarto Pub. I'll double check, but I'll leave the answers here. Thank you. And again, we will gather all these questions as well and group them. And also, at the same time, we are doing that with the Welcome to Quarto workshop questions, which there are a lot as well. So maybe, Isabella, we can work together on some blog posts to share all of those as well. Absolutely. Thank you so much. Thank you, everybody, for joining. Thank you so much, Rachel.

Yeah. Thank you so much. Really, really appreciate it and love to see all the great questions here as well. Thank you all so much for joining us. One last thing, the recording will be here immediately after the talk as well, so it's the same exact link on YouTube. If you're watching on LinkedIn, I'll be sure to just share that link with you all there on LinkedIn right now. Thank you all. Have a great rest of the day. Take care. Bye, everybody.