Quarto Blog Tutorial 3: Default blog source code

Start page of my L3Lab blog (Screenshot from 2024-07-23)

In this article, I will explain and explore the source code that was automatically generated when I created my blog with RStudio as described in Initializing a Quarto Blog with RStudio.

Virgin Title Page

Here is the source code of the main index.qmd after the initialization:

index.qmd

---
title: "quarto-pb-blog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---

And here is the look of the blog’s home page after the first rendering:

Figure 1: First rendering after initializing a Quarto blog (Screenshot)

As you see the title banner shows twice the name of the R project folder ‘quarto-pb-blog’.

Change Title

The first line of the homepage’s YAML header in index.qmd is the title. If I change the title to “L3Lab,” only one part of the title banner will change.

Figure 2: Screenshot of the blog’s homepage after changing the blog listing title in index.qmd

The reason is that the upper left text is written in the Quarto project file.

_quarto.yml

project:
  type: website

website:
  title: "quarto-pb-blog"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: twitter
        href: https://twitter.com
format:
  html:
    theme: cosmo
    css: styles.css

The top left name is the website’s title (and not the blog title). A website can have several components, such as a web page and a blog. I will call the website “Life Long Learning Lab,” the blog’s name remains “L3Lab”.

Figure 3: Screenshot of the blog’s homepage after changing the title of the website in _quarto.yml

The website’s header doesn’t look nice. I will change the blog’s design (color, font size, layout, etc.) later in a separate post.

Explore Listing

Contents Directive

Listings enable you to automatically generate the contents of a page from a list of Quarto documents. In our case, the blog’s title is actually the home page’s listing title.

Instead of listing: default for a list of all documents in the directory and a drop-down menu for sorting direction, order criteria, and a search bar, we have specified with content: posts that only the documents in the folder “posts” should be listed. Have a look into the “posts” folder by selecting the “Files” tab in the bottom right pane of RStudio and click on the “posts” folder to open the directory.

Figure 4: Content of the posts folder immediately after the initialization process

The two folders “post-with-code” and “welcome” contain the two dummy articles generated automatically in the initialization process. I will explain the function of the _metadata.yml file later in another post.

Besides to list all articles of a folder, you can also write much more complex rules for including content by using globs and a list of targets in the contents directive. See for more details the two sections of the Quarto documentation: Listing Contents and Custom Listings.

Listing Types

There are three built-in types of listings you can choose from:

Table 1: Quarto blog listing types

Type	Description
default	A blog-style list of items.
table	A table of listings.
grid	A grid of listing cards.

I am going to use for my blog the default blog-style list of items. However, it is instructive to see the other types to get a sense of their different appearances.

Grid Listings

Figure 5: Dummy articles after the blog initialiation in grid listing mode (Screenshot)

Table Listings

Figure 6: Dummy articles after the blog initialiation in table listing mode

Default Listings

Figure 7: Dummy articles after the blog initialiation in default listing mode (Screenshot)

Sort articles

Using the sort option controls the order of the listing. Each sort key can include a field name and optionally either asc or desc to control whether to sort in ascending or descending order. Since the default order is ascending, I had to add desc to get the most current article at the top. The sort key can also contain more than one field to sort.

Listing options

For every listing type, there are several listing options to specify details, such as:

• The maximum number of items: max-items
• The height of the image: image-height. The width is automatically determined and the image will fill the rectangle without scaling (i.e., cropped to fill).
• A placeholder for the image: image-placeholder. The default image for items if they do not refer to a special image. For more options, see Listing Options and Advanced Options.

Categories

Listings can also automatically add a list of categories to the page on which they appear. To turn on this behavior, you must set the option for categories to true: categories: true. You can choose between a few different category display styles: numbered, unnumbered, and word cloud.

When users click a category, the page will be updated to show only a listing of the items that match the selected category.

Sort- and Filter- Interface

Listings support interactive tools that allow the listing viewer to sort, filter, or page through listings.

I have turned off the sort and filter user interface and applied the default number of items per page for the default listing type: page-size: 25.

Page Layout

Quarto provides three different default layouts for HTML pages:

• The article layout provides a content area with a page-based grid layout that provides margins, areas for sidebars, and a reading width-optimized body region. I am going to use this layout type for article content. See for more information on article layout.
• The full layout uses the article grid system but automatically expands the content area to use the sidebar and margin region if no content is placed within those regions. This is useful for layouts that don’t need to be constrained to reading width, and that will benefit from additional horizontal space (e.g., landing or index pages). It is also often appropriate for listing pages.
• The custom layout provides the possibility to create an individual layout. Learn more on the Page Layout page.

Title Block Banner

HTML pages rendered with Quarto include a formatted title block at the start of the article. The title block contains the title, subtitle, authors, date, doi, and abstract. There are several options to style the title block. In addition, if you’d like a more prominent title block, you can use title-block-banner to create a banner-style title block.

For my blog, I don’t want (at the moment) a title block banner. Setting title-block-banner to false saves space on the title page and feels more prosaic and less business-like.

Figure 8: Blog homepage without banner for the title block (Screenshot)

Git and GitHub

Here I will pause and commit these changes to Git and GitHub. It is interesting to note that there are – besides index.qmd and _quatro.yml – several other files that have changed.

Figure 9: List of changed files expalined in this blog post (Screenshot)

I haven’t even touched many of these files. But the title change propagates the new name into all blog post titles of articles already written and also in the corresponding navigation bars. This is shown with the example of the about page in the next screenshot (Figure 10).

Figure 10: Changes in the about.qmd file (Screenshot)

And I have committed all these changes I’ve got with this second commit a new status in my GitHub repo.

Figure 11: Updated GitHub repo after second commit (Screenshot)

Summary

I have explained the different YAML directives for the blog’s homepage file index.qmd, which are generated automatically when the Quarto blog is initialized. During this tour I have changed two options:

• The title of the blog listing in index.qmd and of the website in _quarto.yml.
• I got rid of the title block banner.

To follow the next sequence of my blog tutorial, check if you have the same starting position.

The changes of the source code of the home page index.qmd result to:

index.qmd

---
title: "L3Lab"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: false
---

There are also a change in the website title in the _quatro.yml file:

_qarto.yml

project:
  type: website

website:
  title: "Life Long Learning Lab"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: twitter
        href: https://twitter.com
format:
  html:
    theme: cosmo
    css: styles.css

Then I have committed these changes to Git and my dummy GitHub repo.