Create a Quarto Document in Positron (Python Example)
Watch Charlotte Wickham's Positron Quarto tutorial to see the full process of creating, rendering, and publishing your first Quarto document with ease. Discover why Positron is the best environment for Quarto documents. We walk you through key features that streamline your work: • Quarto CLI and the Quarto extension are pre-installed. You can start creating and rendering right out of the box! • Use handy buttons, commands (Quarto: New Document, Quarto: Preview), and shortcuts to complete common tasks quickly. • Get comprehensive support for code cells with code completion, linting, and integrated documentation for R and Python. • Benefit from suggestions and warnings as you configure document and code cell options in the header. • Easily access the full quarto command-line interface, including the powerful quarto publish command. Read the blog post: https://posit.co/blog/create-a-quarto-document-in-positron/ Resources Mentioned: • Quarto in the Positron Guide: https://positron.posit.co/quarto.html • Getting Started with Quarto in Positron (R/Python): https://quarto.org/docs/get-started/hello/positron.html • Positron in the Quarto Guide: https://quarto.org/docs/tools/positron/ #Quarto #Positron #DataScience #QuartoTutorial #PositronIDE #DataVisualization #Publishing #RStats #Python #CodingWorkflow
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi, my name's Charlotte Wickham and I'm a Developer Educator at Posit. In this video, I'll show you how to create a Quarto Document in Positron.
Here I am in Positron, and you can see from the File Explorer I've got a folder open called Penguins, but there's nothing in it, except I have set up a virtual environment with uv, you could use pip or conda, or perhaps you're using R. You can see that the Python from that environment is active up in the Session Picker, and that it is running down in my console.
Creating a new Quarto document
The first thing I'm going to do is open up a new Quarto Document, and there's lots of ways to do that, one of which is to use this New button, say I want a new file, and then pick Quarto Document from the dropdown.
I like to use the Command Palette, so I'm going to open up the Command Palette with Command Shift P, or Control Shift P, start typing Quarto to see the Quarto commands, and select Quarto New Document.
Either way, you're going to end up with a new Quarto Document, it's going to have some boilerplate in the YAML header, but otherwise no other content. So I'm going to go ahead and change that title to Penguins, and I'm going to save that file, I'm going to call it penguins.qmd.
The content in a Quarto file is Markdown, so I can just start typing Markdown, hash hash is Markdown for a header, so I might have an introduction, and I might just say this is an exploration of the penguins data.
So you can write Markdown here in the Source Editor, Positron comes with a Visual Editor too, you can use this toggle up here to switch to it, and in that Visual Editor it appears a little bit more like how it's going to render, and there's some tools in there to help you write that Markdown syntax if it's a little unfamiliar. Let me jump back to the Source Editor.
Quarto extension and CLI in Positron
So a couple of things to note. The command I used to create that document, Quarto Create New Document, is being provided by the Quarto extension. But because the Quarto extension comes pre-installed with Positron, you have all those commands from the start.
The other thing to notice is down in the status bar, you'll see what version of Quarto Positron's picked up. If you've never installed Quarto before, you'll just get the Quarto that's bundled with Positron. If you have installed it before, you'll see the version of Quarto that you might have installed before, and if you need to update it, you can just head to quarto.org, grab the new version, and Positron will pick it up.
Previewing the document
Now we have this very minimal Quarto document. I'm going to get Quarto to render it so we can see what it looks like. There's a couple of ways to do that. Again, there's this button, Preview, up in the Editor toolbar. There's a command, Quarto Preview. There's also a shortcut. I'm going to use the shortcut Command Shift K or Control Shift K.
And when I hit that shortcut, you'll notice what happens is down in the terminal, Quarto is running. The command it's running is Quarto Preview on this document I have open in the Editor. And once it's finished rendering, it's going to pop up that preview in the Viewer pane in Positron.
So now we've got the side-by-side view of our source in the Editor and our rendered document previewing in the Viewer. The other thing to note is that when that document got previewed, it got fully rendered and out came the file penguins.html, and you can see that that is in our folder over here in the File Explorer.
Adding Python code cells
Of course, the power of Quarto isn't in turning Markdown into HTML documents. It's being able to incorporate code and its output into those documents. So let's go ahead and add some code to this document.
Before I go ahead and add a code cell, I'm just going to add a few requirements to my virtual environment. So down in the terminal, not in the Quarto Preview terminal, I'm going to leave that preview running. But in another terminal, I'm going to add some requirements.
The first one I'm going to add is Jupyter, so uv pip install Jupyter. And Jupyter is required by Quarto to be able to execute Python code cells. So if you've got Python code cells, you're going to need the Jupyter package. And then the other thing I'm going to install is Plot9. This is now my analysis-specific. I'm going to make some plots with Plot9, so I'm going to install that package as well.
Now we can go ahead and add a code cell. And again, there's lots of ways to do this. There's an Insert Code Cell button up in the toolbar. There's a shortcut for that. There's also a command for that called Quarto Insert Code Cell. I'm going to click that button, and then a dropdown comes up for which language this code cell will be in, and I want a Python code cell. So I just hit Enter for that.
So now I can write my Python code. The first thing I want to do is import some packages. So from Plot9, I'm going to import all the functions, and from Plot9 Data, I'm going to import penguins.
Now I'm just writing this code in a code cell. I haven't done anything to execute it. But the nice thing here is it's really easy to take this code and send it down to my console. Again, lots of ways to do it. There's this Run Cell button that'll appear above any code cell. If I click that, it sends it off to my console.
You can also do this with keyboard shortcuts. So Command or Control Enter will send one line, your current line, to the console. Or if you do Command or Control Shift Enter, you'll get all the lines in that code cell sent down to the console. That makes it really easy to write your code here in the Quarto document and just send it down to the console when you're ready.
Writing and running a plot
Let me add another code cell. This time I'm going to use the keyboard shortcut, and I'm actually going to try and make a plot using Plot9. So there's the ggplot function. And you'll notice that in this code cell in a Quarto document, you get all the help you would expect from code in a script document in Positron. So I'm getting completions, I'm getting this pop-up help for functions, that kind of thing.
I am going to make a plot of this penguin's data. And on the x-axis, I'm going to have FlipperLength in millimeters. It's a very long variable name. And on the y-axis, I'm going to have BillLength in millimeters. And I need to add a geom to make sure there's something in my plot. So again, I can use my keyboard shortcut to send that to the console. You'll notice that a code gets run down in the console, and the plot pops up in this Plots pane.
And we were looking at the viewer, we were looking at our preview of the Quarto document. When that plot popped up, Positron switched back to the Session pane. You can see this is where all the information is about what's in my Python session, and also the current plot from Python.
I'm going to add a little bit extra here. I'm just going to set the color of these points to be the species variable. And I can rerun that, and there's my new plot.
There are other ways to run cells in Quarto documents. So you can see now I've got two code cells. There's a little bit of an extra command up here. I can run all the cells above this one. So that's really useful if you've restarted your session, just want to run everything up to this point. You can see in the previous, there was a Run Next Cell button. And if you bring up the command palette, you'll see if you look for Quarto Run, there's a ton of different commands you can use to run cells and do various things, and they've all got shortcuts there.
Previewing with code output
Okay, so I'm pretty happy with that plot. We've had a look in the Plots pane. This has all been running in my interactive console. But let's take a look at how my Quarto document is looking now. So I'm going to rerun that preview command. Let me do it by clicking the button this time. So in the background, Quarto is running. You can see down in the status bar for a moment, it said rendering this document. Once it's done, up pops that new preview. And there is our document now with our code cells and that plot.
Now there's a few things that are bothering me about this document at the moment. One of them, you'll notice there was a warning about some missing values. So I should certainly investigate what that was about. But if I just want to get rid of it in my output, that's something I can do with the code cell option in Quarto. So code cell options start with a comment character followed by a pipe, and then you write the code cell option. And in Positron, you can get help on what possible options you might have by hitting Command Space. And these are the completions on offer. I'm looking for the one that is warning, and I'm going to set it to false.
So this is part of the sort of YAML intelligence you get through the Quarto extension in Positron. Now if I repreview that document, you'll notice that that warning is omitted from the output.
So I'm going to go back up to the header. This is also using YAML syntax. And I'm going to change one thing about my document. I don't actually want any of the code to show up. So there's an option called echo, and it takes a few values, one of which is false, which just says do not echo the code in my document. If I repreview, you'll see that that code is no longer in the document.
So this is part of the sort of YAML intelligence you get through the Quarto extension in Positron. Now if I repreview that document, you'll notice that that warning is omitted from the output.
Previewing other formats
So another great thing about Quarto is that you're not limited to sending things to HTML. So right now, I've got format HTML up in the header here. If you want to just take a look at what it might look like in a different format, there's another Quarto command called preview, just like we've been running, but it's called preview format. So if you hit that command, it's going to give you some options. It's going to start with any formats that are actually defined in the YAML header, and then give some other options. So let me have a look at this PDF via Typed. So this is format Typed.
Typed is an alternative to LaTeX. It creates PDFs. One of the great things about it is it's bundled in Quarto. So you can create PDFs with Quarto without any other installations. And up pops a preview of it that's now a PDF document. And I'm viewing that in the viewer pane.
If I run preview again, so now I'm just using the shortcut, it's going to stick with that format that I selected from preview format. If I want to go back to HTML, I'm going to need to rerun that preview format command and get back to HTML.
Publishing with Quarto publish
So if I'm happy with this document, the last thing I want to do is put it somewhere where I can share it with other people. So one of the ways to do that with Quarto is through its Quarto publish command. So down in the terminal, I'm going to kill that Quarto preview process. I just hit control C. And I'm going to run the command Quarto publish.
And I'm going to tell it I want to publish this document, the standalone document. So penguins.qmd. And Quarto publish will pop up a list of places you can publish. I'm going to choose Quarto pub because that's just a really easy, quick way to get started. I already have an account on Quarto pub with my email address. And it's going to ask me what I want to call this document. I'll just call it penguins. And Quarto will handle the rest. It's going to rerender that document, make sure it's up to date. It's going to send all those files up to Quarto pub.
And then once it's done, it's actually going to open up a browser and send us to view that document. And you can see that that document now lives on Quarto.pub. And this is a public URL. Anyone else can visit this and see my document.
Where to learn more
That's it for our walkthrough of Quarto and Positron. If you head to the Positron docs, you can learn a bit more about the relationship between Quarto and Positron. But if you want more detail, the best place to go is the Quarto documentation site. There we have a tutorial for learning about Quarto in Positron. And you can work through the examples there, either using Python or using R. There's also a whole section in our tools section of our guide all about using Positron with Quarto. I hope you enjoy making Quarto documents in Positron.
