Website Hero/Banner Image

[hectormz]

Request

Is there a way to make a Quarto website with a large hero/banner image above/below the nav bar? Something like this:

Current ability for Quarto websites

Currently it looks like the closest option is to set title-block-banner with image on a per-post basis, but that is just put behind an article's title. I'm looking to set a banner image above the title of an article, which is conserved across all parts of a website.

Close, but not quite options

The cover/banner image at the top of one of the PDF examples in the gallery:

and the sidebar logo in the Openscapes demo site made me think it might be possible

[jjallaire]

For main/splash pages, the best way to go is to use page-layout: full or page-layout: custom and the use the Bootstrap grid system to lay out all of your components. See docs here: https://quarto.org/docs/output-formats/page-layout.html

[DOH-FAA3303]

Hi @hectormz - I gave up :( I tried to use page-layout: custom and adjust the html but couldn't figure it out. Also, I think there are more issues with Quarto books, like params not behaving the same way they do in bookdown and other issues with formatting the book's style.

If I come across this again I'll keep you in mind and let you know!

[ramiromagno]

any luck yet?

[dragonstyle]

Something that might get you close to what you're looking for (especially when using custom background images and perhaps customizing things a bit with CSS) is https://quarto.org/docs/authoring/title-blocks.html#title-banners

[mcanouil]

I am likely to try some things about that next week, possibly using partials (https://quarto.org/docs/journals/templates.html#html-partials).

[ramiromagno]

Is there a quick way of setting the custom background image for the title block but fix the height while resizing the window horizontally? so that we have a constant title block vertically.

Example: https://www.ccmar.ualg.pt/

[mcanouil]

Using the banner:

Quarto document	HTML
--- title: "Quarto Playground" description: "A playground for Quarto" author: "Mickaël Canouil" date: "today" format: html: theme: slate title-block-banner: saga.png include-in-header: - text: | <style> .quarto-title-block .quarto-title-banner { background-position-y: center; height: 200px; } </style> --- This is a playground for Quarto.
--- title: "Quarto Playground" description: "A playground for Quarto" author: "Mickaël Canouil" date: "today" format: html: theme: slate title-block-banner: "#00000000" title-block-banner-color: "#ffffff" include-in-header: - text: | <style> #title-block-header.quarto-title-block.default .quarto-title-meta { color: #ffffff; } .quarto-title-block .quarto-title-banner { height: 0; } #title-block-header { background-image: url(saga.png); background-size: cover; background-position-y: center; height: 200px; } </style> --- This is a playground for Quarto.

Or using the template partials, although this completely discard the author block formatting (@dragonstyle any idea to get it back?)

Quarto document	title-block.html	HTML
--- title: "Quarto Playground" description: "A playground for Quarto" author: "Mickaël Canouil" date: "today" format: html: theme: slate template-partials: - title-block.html image: saga.png --- This is a playground for Quarto.	<header id="title-block-header"> $if(image)$ <style> .hero { background-image: url($image$); background-size: cover; background-position-y: center; height: 200px; } </style> <div class="hero"></div> $endif$ $if(title)$<h1 class="title">$title$</h1>$endif$ $if(subtitle)$ <p class="subtitle">$subtitle$</p> $endif$ $for(author)$ <p class="author">$author$</p> $endfor$ $if(date)$ <p class="date">$date$</p> $endif$ $if(abstract)$ <div class="abstract"> <div class="abstract-title">$abstract-title$</div> $abstract$ </div> $endif$ </header>

[dragonstyle]

Or using the template partials, although this completely discard the author block formatting (@dragonstyle any idea to get it back?)

Right now there isn't a way - the title block author formatting is implemented by an internal template partial which isn't currently documented. If you replace the title block, we're currently expecting you to take over presentation of all the title data including metadata like authors.

[mcanouil]

Any plan to "expose" this to users?

[fuhrmanator]

I was trying to make this work in a blog (converting to Quarto blog from a Jekyll style, e.g., https://fuhrmanator.github.io/2023/05/22/Open-Educational-Resource-in-French.html)

Since I didn't want to lose the block formatting by using a partial (see #1986 (reply in thread)), I made a compromise that uses a static file name for the banner image.

In case anyone wants to try this tweaked CSS setting, inside my blog's posts/_metadata.yml I have:

# include CSS style for title blocks
title-block-banner: "#00000000"
title-block-banner-color: "#ffffff"
include-in-header:
  - text: |
      <style>
      #title-block-header.quarto-title-block.default .quarto-title-meta {
        color: #ffffff;
      }
      .quarto-title-block .quarto-title-banner {
        height: 0;
      }
      #title-block-header {
        background-image: url(./banner-image.jpg);
        background-size: cover;
        background-position-y: center;
        height: 400px;
        opacity: 1; /* Adjust as needed */
        z-index: -1;
      }
      #title-block-header::after {
        content: "";
        position: absolute;
        top: 0;
        left: 0;
        right: 0;
        bottom: 0;
        background-color: rgba(0, 0, 0, 0.5); 
        z-index: -1;
      }
      </style>

As you can see, it loads the ./banner-image.jpg which is local to each post. In the post YAML I specify image: banner-image.jpg to have consistency with the blog's overview.

It's not super flexible for putting the image wherever you want (with whatever name you want), but it works and it's "good enough" for my blog. I've not deployed it yet (live) because I'm still working on the comment solution and the aliases: to make sure links don't break.

Here's a capture of the result:

[mcanouil]

Thanks for sharing!

[jimjam-slam]

Nice work, @fuhrmanator! Also remember that background takes multiple values, so you can apply your image and overlay together and ditch the ::after pseudoelement altogether if you'd like 😊

[fuhrmanator]

Thanks @jimjam-slam -- using that StackOverflow answer, I came up with something that is simpler and has a better explanation:

# include CSS style for title blocks
title-block-banner: "#00000000"
title-block-banner-color: "rgba(255, 255, 255, 0.9)"
include-in-header:
  - text: |
      <style>
      #title-block-header.quarto-title-block.default .quarto-title-meta {
        color: rgba(255, 255, 255, 0.9);
      }
      .quarto-title-block .quarto-title-banner {
        height: 0; /* hide */
      }
      #title-block-header {
        background: 
          /* top, transparent black, faked with gradient */
          linear-gradient(
            rgba(0, 0, 0, 0.7),
            rgba(0, 0, 0, 0.7)
          ),
          /* bottom, image */ 
          url(./banner-image.jpg);
        background-size: cover;
        background-position-y: center;
        height: 450px;
        opacity: 0.7; /* image opacity, lower means lighter */
        z-index: -1;
      }
      </style>

[mcanouil]

I've made another attempt at this that tries to keep it as easy to use as possible.

• code: https://github.com/mcanouil/quarto-issues-experiments/tree/main/test-hero-banner
• website: https://m.canouil.dev/quarto-issues-experiments/hero-banner/

Only the "post-with-code" post has the hero banner in this example and here is how it was achieved in the Quarto document:

---
title: "Post With Code"
author: "Harlow Malloc"
date: "2025-10-13"
categories: [news, code, analysis]
image: "image.jpg"
---

![]({{< meta image >}}){.hero}

This is a post with executable code.

The extra padding/margin is on purpose to avoid having a thin banner where we wouldn't be able to see the image.
As it's all CSS, it can all be tweaked.

---

I might turn this into a Quarto extension

[royfrancis]

Is there an option to cover the navbar as well?

[mcanouil]

What do you mean?

[royfrancis]

I mean like this:

The hero image extends up under the navbar. If the navbar color is set to transparent, the image is visible underneath.

[mcanouil]

You need to find the right CSS and possibly tweak the navbar background.