Using Markdown Headers and Quarto Configuration

Oct 13, 2025 by wbrum.org 96 views

Introduction

In this milestone, we will be converting our existing Jupyter Notebook (.ipynb) and R Markdown (.rmd) files into Quarto documents (.qmd). This will enable us to create a more polished and professional report that is easy to read and understand. Our goal is to make the report so well-structured and formatted that non-data scientists would not be able to tell that code was used to perform the analysis or format the report.

Step 1: Editing the Quarto Document

The first step in converting our files is to edit the Quarto document so that its sole job is to narrate our analysis, display our analysis artifacts (i.e., figures and tables), and nicely format the report. This means that we need to remove any code that is not necessary for the report and make sure that the code that is left is properly formatted and hidden from view.

Using Markdown Headers and Quarto Configuration

To create a table of contents in our Quarto document, we need to use markdown headers and Quarto configuration. We can do this by adding the following code to the top of our document:

---
title: "My Quarto Document"
output:
  quarto::html_document:
    toc: true
---

This code tells Quarto to create a table of contents in our HTML document.

Adding Inline Bibtex References

To add correctly formatted inline bibtex references to our document, we need to use the @ symbol followed by the citation key. For example:

This is a sentence with a citation [@author2020].

This will create a nicely formatted reference list at the end of our document.

Editing Figure Formatting

To edit the figure formatting in our Quarto document, we need to use the figure environment and add the following code:

```{figure}
  caption: "My figure"
  label: "fig:my-figure"
  fig.width: 6
  fig.height: 4

This code will automatically number our figures, add a label for easy cross-referencing, and control the figure sizes so that they are not too big.

Adding Table Description Argument

To add a table description argument to our Quarto document, we need to use the table environment and add the following code:

```{table}
  caption: "My table"
  label: "tab:my-table"
  table.width: 6
  table.height: 4

This code will automatically number our tables and use cross-referencing to link to the table if/when it is discussed in the text.

Editing Narrative

To edit the narrative in our Quarto document, we need to use cross-referencing to refer to the figures and tables instead of having their reference hardcoded. For example:

This is a sentence that refers to figure @fig:my-figure.

This will create a nicely formatted reference to the figure.

Replacing Hard-Coded Values

To replace any hard-coded values in our Quarto report narrative text with inline Quarto code, we need to use the r function. For example:

This is a sentence with a hard-coded value: `r 2020`.

This will automatically update the text with the correct value.

Changing Code Chunk Options

To change the code chunk options in our Quarto document so that no code is viewable in the rendered report, just the code outputs where needed (e.g., figures and tables), we need to use the echo and results options. For example:

```{r}
  echo: false
  results: "hide"

This code will hide the code from view and only show the code outputs.

Conclusion

Q: What is Quarto and why do I need to convert my files?

A: Quarto is a new document format that allows you to create professional reports and documents using a simple and intuitive syntax. Converting your existing Jupyter Notebook and R Markdown files into Quarto documents will enable you to create a more polished and professional report that is easy to read and understand.

Q: What are the benefits of using Quarto?

A: The benefits of using Quarto include:

Easy to use: Quarto has a simple and intuitive syntax that makes it easy to create professional reports and documents.
Flexible: Quarto allows you to create a wide range of document types, including reports, articles, and books.
Customizable: Quarto allows you to customize the appearance and layout of your documents using a variety of themes and templates.
Collaborative: Quarto allows you to collaborate with others on documents using a variety of tools and features.

Q: How do I convert my .ipynb/.rmd files into .qmd files?

A: To convert your .ipynb/.rmd files into .qmd files, you will need to follow these steps:

Install Quarto: First, you will need to install Quarto on your computer. You can do this by following the instructions on the Quarto website.
Open your .ipynb/.rmd file: Once you have installed Quarto, you can open your .ipynb/.rmd file using the Quarto editor.
Edit the Quarto document: The Quarto editor will allow you to edit the Quarto document and make any necessary changes.
Save the document as a .qmd file: Once you have made any necessary changes, you can save the document as a .qmd file.

Q: What are some common issues that I may encounter when converting my files?

A: Some common issues that you may encounter when converting your files include:

Formatting issues: You may encounter formatting issues when converting your files, such as changes to the layout or appearance of the document.
Code issues: You may encounter code issues when converting your files, such as changes to the code syntax or structure.
Reference issues: You may encounter reference issues when converting your files, such as changes to the way that references are formatted or cited.

Q: How do I troubleshoot common issues when converting my files?

A: To troubleshoot common issues when converting your files, you can try the following:

Check the Quarto documentation: The Quarto documentation provides a wealth of information on how to use Quarto and troubleshoot common issues.
Check the Quarto community forums: The Quarto community forums provide a place for users to ask questions and share knowledge and expertise.
Check the Quarto GitHub repository: The Quarto GitHub repository provides a place for users to report bugs and request features.

Q: What are some best practices for using Quarto?

A: Some best practices for using Quarto include:

Use a consistent syntax: Quarto has a simple and intuitive syntax that makes it easy to create professional reports and documents.
Use a consistent layout: Quarto allows you to customize the appearance and layout of your documents using a variety of themes and templates.
Use a consistent style: Quarto allows you to customize the style of your documents using a variety of fonts, colors, and other visual elements.
Use a consistent structure: Quarto allows you to customize the structure of your documents using a variety of sections and subsections.

Conclusion

In this Q&A article, we have covered some of the most common questions and issues that users may encounter when converting their .ipynb/.rmd files into .qmd files. We have also provided some best practices for using Quarto and troubleshooting common issues. By following these tips and best practices, you can ensure that your Quarto documents are professional, polished, and easy to read and understand.