website hybrid configuration help

[RFanalytic]

Description

I have a successful quarto generated website project to present many pages generated from R code. It is currently configured as sidebar, and compiles results for an entire year. I would like to show results from multiple years, reconfiguring the website using navbar for years and retaining the sidebar for each year. I have read the quarto documents for hybrid configuration but have issues not yet resolved.

1.  Do all .qmd documents need reside in the same directory at the time of render?
2.  I wish to retain current R code base, but this will give the same file names for many files that are auto-generated for each year.  

This would be a conflict if all .qmd files need reside in the directory at the time of render. If they can be segmented into separate directories for each year I am hoping I can arrive at a yaml configuration that will achieve this.

I have reviewed this discussion but it did not resolve my issue https://github.com/orgs/quarto-dev/discussions/8117

Thank you
Robert

[mcanouil]

What do you mean by "the same directory"? The files have to be in the project.

I wish to retain current R code base,

This is also unclear what it concretely mean.

Could you share or create a simple reproduction of your setup?

Meanwhile, have you looked at custom listings?

[RFanalytic]

I can make an example, but if my explanation suffices, perhaps that step not needed.
I run a script that reads a large amount of data and auto-generates the .qmd documents and currently places them into one directory from which the website is rendered, that works as expected. To grow the site, I would like to produce the same format, in a 2nd (perhaps more) directory possibly named as the year. The years would be the navbar items. Each directory(year) would have different data but files named the same (100+ files). I was thinking there would be some yaml syntax that said which allow selection of which directory to render each section:

I have not looked at custom listings, and will do that.

Another thought I had was to generate each directory independently for _site output and then a script to assemble all the results, but thinking this may be overly complicated.

[RFanalytic]

Below is an example of the _quarto.yml I am trying to create (and allow successful render). Since I generate so many files, I am wanting to have the .qmd files, each in their own year directory for project organization. Currently they would have the same names (but in different directories). I am trying to prevent naming every file for the website a unique name and locating them all in the project directory. Is this possible? If not, the backup idea is to append every file with quarter/year (Q1/2025) syntax to differentiate, but this will be messy to manage.

project:
type: website

website:
title: "hybrid_test"
navbar:
background: "khaki"
left:
- text: "Home"
href: index.qmd
- text: "2025_June_30"
href: document_1.qmd
- text: "2025_December_31"
href: document_1.qmd

sidebar:
- title: "Home"
style: "docked"
background: "lightsteelblue"
search: true
contents:
- index.qmd
- title: "2025_June_30"
contents:
- document_1.qmd
- title: "2025_December_31"
contents:
- document_1.qmd
- document_2.qmd

• title: "2026_June_30"
  contents:
  - document_1.qmd
  - document_2.qmd

format:
html:
theme: yeti
mainfont: "Fira Sans"
grid:
sidebar-width: 500px
body-width: 800px
margin-width: 10px
gutter-width: 1.0em
css: styles.css
toc: false

[RFanalytic]

My apologies. The proposed example is below:

project:
 type: website

website:
 title: "hybrid_test"
 navbar:
   background: "khaki"
   left:
     - text: "Home"
       href: index.qmd
     - text: "2025_June_30"
       href: documnet_1.qmd
     - text: "2025_December_31"
       href: document_1.qmd
     - text: "2026_June_30"
       href: document_1.qmd

 sidebar:
   - title: "Home"
     style: "docked"
     background: "lightsteelblue"
     search: true
     contents:
       - index.qmd
   - title: "2025_June_30"
     contents:
       - document_1.qmd
       - documnet_2.qmd
   - title: "2025_December_31"
     contents:
       - document_1.qmd
       - document_2.qmd
   - title: "2026_June_30"
     contents:
       - document_1.qmd
       - document_2.qmd

format:
 html:
   theme: yeti
   mainfont: "Fira Sans"
   grid:
     sidebar-width: 500px
     body-width: 800px
     margin-width: 10px
     gutter-width: 1.0em
   css: styles.css
   toc: false

[mcanouil]

@RFanalytic You don't need to repost, you can simply edit any of your post.

[mcanouil]

contents is path, up to you to have subdirectory1/document1.qmd and subdirectory2/document1.qmd.

I'm not sure to understand your issue or what you are asking.

Maybe worth you go through the documentation of the sidebar again: https://quarto.org/docs/websites/website-navigation.html#side-navigation

[RFanalytic]

I will review before checking back. I am traveling so regret delays.

[mcanouil]

A suggestion if you are generating the sidebar but not necessarily everything else from the project configuration.

Generate a "sidebar" YAML file, e.g.: _sidebar-getting-started.yml

website:
  sidebar:
    - id: getting-started
      align: center
      collapse-level: 2
      contents:
        - section: "Getting Started"
          href: getting-started/index.qmd
          contents:
            - getting-started/installation.qmd
            - getting-started/installing-extensions.qmd
            - getting-started/explorer-view.qmd
            - getting-started/using-templates.qmd
            - getting-started/reproducible-docs.qmd
            - getting-started/troubleshooting.qmd

and in your _quarto.yml

...

metadata-files:
  - _sidebar-getting-started.yml
  - _sidebar-reference.yml
  - _sidebar-api.yml

See real life use case for this: https://github.com/mcanouil/quarto-wizard/tree/main/docs

[RFanalytic]

Your links help, I am mostly understand. I think I still do not understand navigation as well as I should. I show my minimal example project tree. And after that the _quarto.yml that I use to render. For this configuration it does not show the sidebar or document_2 for either of "2025_June_30" or "2025_December_31". I tried (for example 2025_June_30) in the sidebar, contents: 2025_June_30/, but this did not produce document_2. Thank you for the effort for me to pursue further learning.

├── 2025_December_31
│ ├── document_1.qmd
│ └── document_2.qmd
├── 2025_June_30
│ ├── document_1.qmd
│ └── document_2.qmd
├── _quarto.yml
├── hybrid_test.Rproj
├── index.qmd
└── styles.css

project:
  type: website

website:
  navbar:
    search: false
    background: "khaki"
    left:
      - text: "Home"
        href: index.qmd
      - text: "2025_June_30"
        href:  ./2025_June_30/document_1.qmd
      - text: "2025_December_31"
        href: ./2025_December_31/document_1.qmd
  sidebar:
    - title: "Home"
      style: "docked"
      background: "lightsteelblue"
      contents:
        - index.qmd
    - title: "2025_June_30"
      contents: 2025_June_30/
        - document_1.qmd
        - documnet_2.qmd
    - title: "2025_December_31"
      contents:
        - document_1.qmd
        - document_2.qmd


format:
  html:
    theme: yeti
    mainfont: "Fira Sans"
    grid:
      sidebar-width: 500px
      body-width: 800px
      margin-width: 10px
      gutter-width: 1.0em
    css: styles.css
    toc: false

[mcanouil]

The issue is not the understanding of the navigation, but understanding of YAML.
Your YAML is invalid and I believe Quarto raised an error in this case.

The items under `contents' are paths. See the example I shared and follow it.

[RFanalytic]

I looked at the example website and the files that compose it from github. I would like to ask if my understanding is clear. I do like your website example and execution looks clear, but I am missing some steps to perform it properly.

I first create a metadata extension to my project directory. That project directory is "hybrid_test", and I use the same extension name as your example "metadata-files". The result is a scaffold with the following structure:
hybrid_test/metadata-files/_extensions/.metadata-files/

Inside that lowest directory there was created a template file _extension.yml. I performed a minor edit on that file:

title: Metadata-files
author: RFA
version: 1.0.0
quarto-required: ">=1.8.0"
contributes:
  metadata:
    project:
      # your per-project metadata goes here
      - _sidebar_2025_June_30.yml

Inside that same directory I create a second file named _sidebar_2025_June_30.yml with contents shown below

website:
  sidebar:
    - id:"2025_June_30"
      align: center
      collapse-level: 2
      contents:
        - section: "2025_June_30"
          href: 2025_June_30/index.qmd
          contents:
            - 2025_June_30/document_1.qmd
            - 2025_June_30/document_2.qmd

To associate that extension in the main _quarto.yml file in the project root, I add the following syntax:

metadata-files:
    - _sidebar_2025_June_30.yml

When I render the website, I get the error "property name metadata-files is invalid", and "The error happened in location website:metadata-files."

I am looking for guidance to correct this error. I estimate some possible errors on my understanding, _sidebar_2025_June_30.yml is in the wrong directory and perhaps belongs in root. I also may have referenced in _extension.yml improperly. Third I may need a step to some how add this meta-files functionality (similar to library()) but not sure, it is not clear to me in https://quarto.org/docs/extensions/metadata.html

[mcanouil]

Would you mind sharing a Git repository and a clear step by step guide to what you do?

[RFanalytic]

Thank you for taking the time to evaluate my work.
The minimal example repo is at: https://github.com/RFanalytic/hybrid_test/tree/main

The explanation is in the README

[mcanouil]

• _extensions/ should be alongside _quarto.yml.
• metadata-files is not a key under website.
• There are various YAML errors, such as missing spaces after colons.
• Not sure why you want a metadata extension here as the content seems to be quite specific, thus no reuse of this extension.
• Your metadata-files entries do not exist, you have typos as YAML files do not match.

You need to read carefully the documentation and provided examples.
More generally, before making complex things, better to start small, then once you understand and it's working, complexify.

[RFanalytic]

Thank you for pointing where to look. I have re-read the documents and simplified my approach. Can you please critique my implementation and provide advice if there is a better method? I am wondering if use of href in navbar is proper for larger document construction. Thank you

A new minimal example is located at: https://github.com/RFanalytic/hybrid_test_2

[RFanalytic]

hybrid_test_2 example sufficiently solved my issue