Extending Quarto - posit::conf(2023)
Presented by Richard Iannone What are Quarto shortcode extensions? Think of them as powerful little programs you can run in your Quarto docs. I won't show you how to build a shortcode extension during this talk but rather I'm going to take you on a trip across this new ecosystem of shortcode extensions that people have already written. For example, I'll introduce you to the `fancy-text` extension for outputting nicely-formatted versions of fancy strings such as LaTeX and BibTeX; you'll learn all about the `fontawesome`, `lordicon`, `academicons`, `material-icons`, and `bsicons` shortcode extensions that let you add all sorts of icons. This is only a sampling of the shortcode extensions I will present, there will be many other inspiring examples as well. Presented at Posit Conference, between Sept 19-20 2023, Learn more at posit.co/conference. -------------------------- Talk Track: Quarto (2). Session Code: TALK-1141
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
So my talk is on extending Quarto, and we do that with Quarto extensions, and I just want to say, Quarto really does a lot, like, when I first saw it, I was, it was unbelievable that it could do articles, websites, blogs, books, presentations, and even knowledge repos.
That is a lot in and of itself. But also, you can make products that contain computations performed with Python, R, Julia, Observable, and that's a lot more, that's just quite a comprehensive package that Quarto delivers. And now we have extensions, or we had extensions for quite a while, and they really can open up a whole world of customization possibilities.
And there's lots of them. I was really impressed that there's so many Quarto extensions. They can barely fit in this slide here, and that's only just a small, you know, portion of them. So there's lots. There's definitely people chomping at the bit to create extensions for Quarto, which is really impressive.
Types of Quarto extensions
Okay, so a big question is, we know there's lots of extensions. Where can you find these extensions? Where's the best place to sort of get introduced to them? Okay, the place I like to go, always, is the Quarto.org website. Okay, it's a great starting point for lots, you know, of Quarto things. And really, the section you want to go to is in the top nav, Extensions, which is just a huge section in and of itself.
So in there, you'll find just like, you know, just the extensions themselves. They're broken down by the type, and there's like a Creating Extensions section, which is also really comprehensive and huge. Pretty much everything you need to like learn about extensions in Quarto and to be a user or a creator of extensions is all in there.
Okay, I'm just going to like break down the four different types of extensions in case you've never heard of them or you just want a little more explanation. So the types of extensions are shortcode slash filter extensions. So with those, you modify select parts of a Quarto document, and shortcodes are a little bit different than filters. Shortcodes have a little syntax. I'll get into that a little bit more later. And filters just sort of automatically transform sections of your document.
If you're writing an article for a journal, you'll be happy to know that there's a whole world of journal article extensions, which is great. There's a large amount, and it's growing every day. This is sort of similar in spirit to the articles package in R, except this is all in Quarto. Custom formats, we saw before that there's already lots of formats. You can create your own format, which is quite amazing. So with extensions, you can write your own to create a custom format, which is just unbelievable to me.
Reveal.js, if you're using Reveal.js to create a presentation, it's great. There's extensions that create themes for these presentations. It's a really wonderful section of the site. For this talk, I just want to narrow it down to one type, because this is so huge, to one type of extension, and that's the class of shortcode slash filter extensions. And we don't have much time, so I just want to narrow it down even further to shortcode extensions.
Okay, and what are shortcode extensions? They act a little bit like functions, but you don't use them in computational cells. They kind of live in the prose of a document.
Icon shortcode extensions
Okay, and there's a number of shortcode extensions I want to share with you. There's so many I like. I just want to narrow it down to just a few that I really like. All of them deal with icons, because I really love icons. Okay, so there's fontawesome. That's great. You can insert all the fontawesome free icons in your document. It's almost like a household name these days, fontawesome. And there's material icons, which you may not know about. So it's good to have a second set, mix things up, and now we have another set you can use in a syntax that's very similar to the first set. All these shortcodes pretty much use the same sort of style for usage.
There's also BS icons. It's good to have a third set and really have lots of icons. As you can see, I'm just obsessed with icons. But if you want, these BS icons are actually really good, and there's the all-important hex icon there, which could be useful. So these are bootstrap icons.
Okay, one more. Well, actually, no, a few more, but this is one another. Academic icons. Okay, so if you're in academia, this is essentially an icon set. With icons, you'll find nowhere else. You can see Elsevier. You can sort of see Springer. You're not going to get those in the other ones. So this is pretty much essential if you're doing, like, an academic website and you want to pepper with icons.
One more. This is a special one. Okay, I just discovered it. Lord icon. Get this. These icons are animated. I don't know if you can see this. If you're at the back of the room, you might want to stand up. Because look at that. That's Chicago over there. A plot that's actually interesting, a checkmark that is dynamic, a cat, and a boombox. These are animated. And you can have all these and more in your Quarto document. Okay, imagine that. You can change the color. You can do all sorts of things. Okay, you can see why I love icons. It's a whole universe.
And you can have all these and more in your Quarto document. Okay, imagine that. You can change the color. You can do all sorts of things. Okay, you can see why I love icons. It's a whole universe.
How to use shortcode extensions
Okay, so I hope I got you sufficiently excited about these icons and, by extension, shortcodes. So if you haven't used them yet, I'll show you how to use it. So you start by adding the extension inside the working directory of a project. Okay, so in the console, you would use Quarto add, and then the repo that has the extension. The reason we do that is because we download the actual extension. It just becomes like a folder, an extensions folder, and you essentially commit that when you are doing, like, git. So when you run that, you'll be prompted to agree to this install. You'll actually get prompted twice, but in most cases it's good to say yes.
And this is how you use it. So for a document, so we have this little bit of text. We need some fontawesome icons. Here is one. And then we have the double curly braces, and then the greater than, less than on either side. And then, all importantly, you have to have a space. Then it works. Then it's F-A and the icon name. And to find out what the names are, you just go to the fontawesome website. There's a great icon listing. Just make sure you use a free icon, and it should work here. So, yeah, what you get in the output document is that thumbs up icon. It's nicely scaled to the text. It looks really good. It's quite satisfying to see it rendered like that.
So shortcuts, they're pretty easy to use. They can also offer more power through arguments. So here's some more examples with the fontawesome extension, just to keep it going. So you can do things like, you know, of course, you know, just have the icon, just give the name. But you can also use size equals LG to make it large. So that's great. There's different size classes. So just look at the documentation. Usually the documentation for a shortcut lives on the readme at that repo that the shortcut lives on. So all the instructions are there. So all these things should be explained. And some of these icon shortcuts allow for a title, which is great. So when you hover over, you can supply a title. And this is also great for accessibility because a screen reader will read this.
So, yeah, after running all this, we do get that output right there. So we get the thumbs up, the slightly larger envelope, and the really sized up battery.
Just some tips because, you know, I know you're going to use this right away. Around complicated values, given arguments like that battery thing, I would definitely use quotes, right, because Lua can't really parse sometimes. It's simple and it's fine, like the LG. But I would use quotes just to be safe. Also, this is not surprising, but just a little heads up, you don't get autocomplete for these inside a document. You just have to sort of like not make mistakes and have to remember things. So don't mess it up. So just go to the repo for guidance if you do mess it up.
Finding more extensions
Okay, so where to find even more extensions and other core resources as well. So this was recommended in last talk, the awesome Quarto on GitHub repo. So that's right there at that site, right there. And this is just a smorgasbord of, like, resources. They're really very current. It says the most up-to-date curated list of core docs, talks, tools, examples, and articles the internet has to offer. It's a bold statement, but it's true. It really is a place to go to.
And let me show you. Just to take you on a tour of this giant, like, readme. There's a section there on extensions. This is the most comprehensive list I've seen, and this is how I discovered most of those icon shortcode extensions.
Journal articles, this is part of that articles thing I talked about. I'm getting a little bit off the topic of icons, but that's okay. You'll find what's available in journal articles, like templates, it's all there. There's also presentations, HTML document templates, PDF documents, so many things, even, like, mixed multiple formats, DocX even. Wow. So that's all there. Awesome, awesome Quarto.
So I was inspired by all this, so I did a thing. I like icons a lot. That's obvious by now. And I enjoy documentation, too. I don't know if you know that about me. So I created a repo full of examples of how to use icons in Quarto. Okay. So I just made this public today. It's pretty good. All it is is just, like, a bunch of QMDs. It's got all the icons that are preloaded in there. I committed that stuff, like the extensions. And you could just clone this, you know, try it out, render some stuff, change things around.
It's actually surprisingly hard for some of these extensions to get them to work right. There's some missing tips and tricks that I put in there that help a lot, especially for the Lorticon thing. That's pretty valuable. You have, like, animated icons, so you've got to know how to do that right. So you can learn about how to use all five of those icon-based shortcode extensions, and plus how to use Iconify written by the same person who made the awesome Quarto GitHub repo. And this is just, like, this blew me away. This has, like, not thousands of icons, tens of thousands of icons in different libraries. It's rather nuts.
Creating your own shortcode extension
So at this point, you might be inspired to make your own shortcode extension. You know? It's not that bad of a thing to do. There's already a lot, but there aren't nearly enough. That's my opinion of things. So if you have the need to make one, why not make one yourself?
So if you're doing that, where do you start? Well, the Quarto website. Again, go to that. It has a great section on creating extensions. It's just extensions slash creating. And not only that, you can use other extensions which are already built as a model for a shortcode extension, like fontawesome. That one's incredible. I just went to the repo, went to the Lua file, and I just used that to make my own extension. It was great.
Let me show you that code. It's inspiring. So I'm going to do something which is ill-advised, show you a bunch of Lua code and a talk. But don't worry. I'm going to zoom in. I just want to show you that all the main logic for the fontawesome shortcode filter, it fits inside 40 lines of code. Like, all this value is in 40 lines. That's amazing. I mean, there's, like, other functions above, but, you know, don't worry about that. But all the main stuff is here, 40 lines of code.
First, I want to tell you that all the logic, it's a bit weird to start. You create a return statement, and that's just how it goes with these extensions. And then, okay, so if you remember the fontawesome demonstration, you use fa, then the name of the icon. So you sort of define a function, which is, like, fa, and then you have typically args and quarks.
Okay, so that's great. It's not too bad so far. You make a function. Okay, and then you have to, like, parse your own arguments, which is not too terrible. Again, we have this code here. It's there for posterity. It's not going to change, I don't think. But we can use this as a guide. And we're going to get, like, these, like, variables, and we can use that to sort of create, like, the icons themselves. Like, create the, essentially, the bit of, like, HTML that gets the icon. And just some nice clues in here that are kind of hard to figure out if you're not reading this code. You would use things like pandoc util stringify to get the argument values of strings. That's a nice little trick. And you see 1 and 2. That's, like, just, like, the arg position. And then if we have things which are, like, size, that's, like, quarks, keyword args instead of positional arguments. And then you can get the values from the named arguments, which is great.
And then this is, like, a pleasure to me. Like, when I started using Lua, it's string concatenation operator, dot, dot. It's really wonderful. It's just a joy to use. You just string together a bunch of things, and it's, like, paste in R, and it's quite nice to use. Okay, and another little trick. This will be really useful when you make your own extension, which is going to be pretty soon, I'm sure. When returning some HTML or LaTeX text, we need to typically use pandoc raw inline. Just remember that. And if returning nothing, pandoc null is the thing to use.
Okay, and you might see just in this little scan of, like, your first Lua code you've ever seen, probably, we have helper functions like is empty. That's defined above the code. Oh, just a show of hands, has anybody ever written some Lua in here, ever? Oh, not bad, not bad. I saw, like, maybe 10 people. That's good.
Okay, again, 40 lines of code, nice. I mean, not that much. We get a lot out of it. I mean, now we have fontawesome icons in Quarto.
Introducing Qformat
Okay, I was inspired by this, all this work I saw on shortcode extensions, so I made my own, and I'm calling it Qformat, and that's available today. So it's at this site, not site, my GitHub, essentially, and it's a formatting extension for Quarto. I'm going to show you that super briefly. It's a way to format numbers right now. You give it a number and some options, and it will nicely format it as a decimal value, as an integer value, or something in scientific notation. On that last point, it's actually super hard to make nice scientific notation without going nuts. In Quarto, it's pretty manual. With this, you get the right sort of, like, formatting, no matter whether you're using HTML or LaTeX, or PDF, I should say, in the end.
This thing, I hope, will sort of, like, catch on, and I'm planning on doing more, like, say, taking numbers and making currency values out of them, or helping with units notation and making that nicely formatted, and just doing other little things that, you know, would be nice for formatting.
Okay, so I'm going to show you a quick example of this extension, since it's so new, and I would say good formatting makes for a good document, and that's always true. Here's some examples. So in this first example, a floating-point number, and then we have the shortcode, and it starts with Q format, and then we have, like, a subcommand or, like, a type. I'm just saying num, because I want a number in the end, and we have this pretty big, complicated number with some, you know, decimal places. So I can just say decimals four, use separators. These are, like, the commas or the grouping separators. I'm just going to say no for this one. Okay, and in the end, at the very bottom, maybe scan down. Yeah, it has four decimal places, and, you know, that's pretty good.
If you have a large integer, that's, you know, you can express it as, you know, a very large thing in exponential notation. It'll just expand it out and use the separators right away. Scientific notation, you can do that. This is the sort of hard thing, so that's great. You don't have to use, like, a sup or a span if you're doing HTML. It just sort of does that for you, which is good.
Conclusion
Okay, so I want to conclude. My goal in this talk was to convince you that extensions are cool, and Extending Quarto, the name of my talk, is a good thing. So, yeah, all those things you get. But having extensions, you know, it just takes it out of this world. You can customize basically anything. It gives you a ton of control. The community has already made a ton of extensions, and so, you know, the future looks pretty bright. You know, I can imagine there'll be many more, and they'll get more sophisticated as time goes on. And thanks to the power of Lua, you write the extension code once, and then all these, like, you know, ways of expressing your computations, all those users benefit. So that can only be a good thing.
And thanks to the power of Lua, you write the extension code once, and then all these, like, you know, ways of expressing your computations, all those users benefit. So that can only be a good thing.
Okay, and that's it. I just want to say that my presentation is at my personal GitHub under Presentations. It's in there. And those two things I talked about that I did, they're also in my personal GitHub. And I just want to say thanks.
Q&A
We have a number of questions for you. Sure. First one. Our packages come from CRAN, but where do Quarto extensions come from? Yeah. Are they vetted at all? Wondering about corporate policy on installation. Yeah, it's right now a little bit of a wild west situation because it just lives in a GitHub repo. It could live in other repos as well, but the sort of default or the easiest way is GitHub. And because of that, you know, it's a little bit unsophisticated. There's no package down websites for an extension. There's just like the README, but hopefully the README has everything you need. There might be examples, but yeah, it's pretty much like not like that at all. So you set your own risk, basically. Pretty much, yeah.
Second question is kind of a feature request. Yeah. Can you create an R package to create extensions so we don't have to learn Lua? Maybe not. I mean, Lua is not that bad. Like, I'm trying to dissuade the person to ask that question. Kind of avoiding the question, though. I'm avoiding the question, but I'm giving an alternative, right? Lua is not bad. Like, I learned it just by looking at different, you know, for short codes at least, at different code. It was nice. I looked at a YouTube video or two on Lua. Sort of like helped me out a little bit more. I'm just going to say no to the question.
Okay, next question. Can you inject R code or objects into short code? I believe you can use, no, you cannot do that. No. It's Lua all the way down. By the time we get to Lua, Uniter has already executed the main issue. Right, right. What Carlos said is no. It's not a short code, but it includes statements. So it's tricky. Ask us about it, and we'll try to solve it. Thanks, Rich. Thank you.
