HTML

Introduction

This resource is designed to help you leverage the powerful features of Quarto to enhance your HTML documents.

You will learn:

  • HTML basics: Get started with the essentials of creating HTML documents, including table of contents, section numbering, and CSS styling.
  • Advanced formatting: Explore advanced options like tabsets, external links, and embedded resources to create rich, interactive content.
  • Document customization: Learn how to include CSS styles, scripts, and other assets to personalize the appearance and functionality of your HTML pages.
  • Interactive features: Discover how to add interactive elements such as lightboxes, tabbed content, and comments to engage your audience.
  • Code integration: See how Quarto integrates code from languages like R and Python, allowing you to embed live code outputs directly into your HTML.
  • Theming and layout: Get insights into applying themes and customizing the layout to make your documents visually appealing and easy to navigate.

This guide will improve your ability to create sophisticated HTML documents, well-organized web pages that stand out in terms of both functionality and aesthetics.



Basics

Use the html format to create HTML output:

---
title: "My document"
format:
  html:
    # Table of contents
1    toc: true
2    toc-depth: 3
3    toc-expand: 1
4    toc-title: Contents
    # Section numbering
5    number-sections: true
6    css: styles.css
---
1
Add an auto-generated table of contents.
2
Set section levels in the TOC, defaulting to 3 (levels 1 to 3 included).
3
Control the TOC’s expansion level. The defaults is 1 with auto-expansion as the user scrolls.
4
Customize the title used for the table of contents
5
Number section headings in the output document.
6
Add a CSS stylesheet to your document.

Tabsets

Make a tabset with ::: {.panel-tabset} in markdown. Each heading inside becomes a tab. Example:

::: {.panel-tabset}
## R

``` {.r}
get_sum <- function(a, b) {
  a + b
}
```

## Python

``` {.python}
def get_sum(a, b):
  return a + b
```

:::

Output:

get_sum <- function(a, b) {
  a + b
}
def get_sum(a, b):
  return a + b

Tabset Groups

Use group for tabsets with the same tab names to sync their selection across the group.

::: {.panel-tabset group="language"}
## R

Tab content

## Python

Tab content
:::

Self Contained Document

Create an entirely self-contained HTML document with embedded resources (images, CSS style sheets, JavaScript, Mathajax etc.):

format:
  html:
    embed-resources: true
    self-contained-math: true

This will produce a standalone HTML file with no external dependencies.

Commenting

Enable Giscus comments stored in a GitHub repo’s ‘Discussions’:

comments:
  giscus: 
    repo: quarto-dev/quarto-docs

Requirements for repo:

  • Must be public.
  • Have the Giscus app installed.
  • Have discussion enabled

See Giscus documentation for setup and additional options.

Disabling Comments

Disable comments for a specific page :

title: "Home Page"
comments: false

Include a file

If you want to include additional content in your document from another file, you can use the include-in-* options:

Option for Include Description
include-in-header Include contents of file at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents or to inject commands into the LaTeX preamble.
include-before-body Include contents of file at the beginning of the document body (e.g. after the <body> tag in HTML, or the \begin{document} command in LaTeX). This can be used to include navigation bars or banners in HTML documents.
include-after-body Include contents of file at the end of the document body (before the </body> tag in HTML, or the \end{document} command in LaTeX).

You can specify a single file or multiple files for each of these options directly, or use the file: subkey. To include raw content in the YAML header, use the text subkey. When using text:, add the | character after text: to indicate that the value is a multi-line string. If you omit file: or text:, Quarto assumes you are providing a file.

Example:

format:
  html:
    include-in-header:
      - text: |
          <script src="https://examples.org/demo.js"></script>
      - file: analytics.html
      - comments.html
    include-before-body: header.html

Code Blocks

Hiding Code

Hide executable code in documents with echo: false in execute options:

---
title: 'My Document'
execute:
  echo: false
jupyter: python3
---

Override this option for individual code blocks as needed:

```{r}
#| echo: true

plot(1:10)
```
Note

Code block options go in a comment at the top, marked with #|.

Folding Code

Hide code by default with code-fold; Click Code to view.

Code 
plot(1:10)

Set code-fold: true and customize summary text (default is ‘Code’):

format:
  html:
    code-fold: true
    code-summary: "Show the code"

Code Tools

Activate a Code menu in the document header with code-tools: true :

format:
  html:
    code-fold: true
    code-tools: true

With folded code blocks, the Code menu offers options to show/hide code and view full source.

code tools

Code Annotation

See code annotation

Executable Blocks

See how to include executable code blocks.

To include non-executable code blocks for documentation, wrap the language (e.g. python, r, etc.) in double curly braces rather than one. For example:

```{{python}}
1 + 1
```

Will be output into the document as:

```{python}
1 + 1
```

If you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````) and use the two curly brace syntax for code blocks within. For example:

````
---
title: 'My document'
---

Some markdown content.

```{{python}}
1 + 1
```

Some additional markdown content.

````

Theme Customization

See Quarto HTML Themes documentation.

Image Lightbox

Click on an image to view it’s zoomed version:

Applying Lightbox to Specific Images:

![A Lovely Image](mv-1.jpg){.lightbox}

Group images into a ‘gallery’:

![A Lovely Image](mv-1.jpg){group="my-gallery"}

![Another Lovely Image](mv-2.jpg){group="my-gallery"}

![The Last Lovely Image](mv-3.jpg){group="my-gallery"}

Using lightbox with computational cells:

---
lightbox: auto
---

```{r}
#| label: fig-basic
#| fig-cap: Simple demo R plot 
plot(1:10, rnorm(10))
```

Read more