Page-level `sidebar: <id>` and `navbar: true` remove the site's sidebar and navbar

Open
#1,217 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
rust

Research direction

Start with resolve_website_value in crates/quarto-config/src/website.rs:39, then trace how page navigation values reach sidebar_for_page in crates/quarto-navigation/src/sidebar.rs:670 and resolve_navbar in crates/quarto-navigation/src/navbar.rs:417. Reproduce the reported cases with the supplied q2 render steps and check whether each page retains its site's configured navigation. Done means the reported sidebar: <id> and navbar: true cases match the expected Quarto 1 behavior.

Written by the indexing model from the issue text.

Description

This issue was written by Claude while adding q2 support to Great Docs. The output shown comes from running each repro.

Bug description

In Quarto 1, a page picks one of the site's sidebars with sidebar: <id> in its front matter, and
navbar: true leaves the site's navbar in place. In q2, both options remove the navigation they
name.

  • sidebar: <id>: the page gets no sidebar.
  • navbar: true: in a site with no sidebar, the page gets no navbar. In a site that also has a
    sidebar, the page kept its navbar.

The cause looks like resolve_website_value (crates/quarto-config/src/website.rs:39). It merges a
page's top-level sidebar or navbar with website.sidebar or website.navbar, and the top-level
value wins. So the scalar replaces the site's whole sidebar or navbar definition:

  • sidebar_for_page (crates/quarto-navigation/src/sidebar.rs:670) reads the page's choice from
    site-sidebar, not sidebar.
  • resolve_navbar (crates/quarto-navigation/src/navbar.rs:417) treats navbar: true as absent,
    because "the plan drops this shorthand".

Great Docs puts sidebar: <id> on its API reference pages to give them the API sidebar, and on
user guide and recipe pages for theirs. Under q2 those pages lost their sidebars. Great Docs now
renames the key to site-sidebar and removes navbar: true before a q2 render.

Steps to reproduce
mkdir -p page-nav/sidebar page-nav/navbar && cd page-nav/sidebar
cat > _quarto.yml <<'EOF'
project:
  type: website
website:
  navbar:
    left: [index.qmd, a.qmd]
  sidebar:
    - id: main
      contents: [index.qmd, a.qmd]
EOF
printf -- '---\ntitle: Home\n---\n\nHome.\n' > index.qmd
printf -- '---\ntitle: A\nsidebar: main\n---\n\nA.\n' > a.qmd
q2 render
grep -c 'id="quarto-sidebar"' _site/index.html _site/a.html

cd ../navbar
printf 'project:\n  type: website\nwebsite:\n  navbar:\n    left: [index.qmd, b.qmd]\n' > _quarto.yml
printf -- '---\ntitle: Home\n---\n\nHome.\n' > index.qmd
printf -- '---\ntitle: B\nnavbar: true\n---\n\nB.\n' > b.qmd
q2 render
grep -c 'id="quarto-header"' _site/index.html _site/b.html
Actual behavior
_site/index.html:1
_site/a.html:0
_site/index.html:1
_site/b.html:0

a.html has no sidebar, and b.html has no navbar. With site-sidebar: main in a.qmd, the
sidebar appears. Without navbar: true in b.qmd, the navbar appears.

Expected behavior

As in Quarto 1.9.37:

_site/index.html:1
_site/a.html:1
_site/index.html:1
_site/b.html:1
  • Read a page's string sidebar as the id of the sidebar to use, as site-sidebar is read now,
    rather than merging it over website.sidebar.
  • Read a page's navbar: true as "keep the site's navbar". Only false should turn it off.

If q2 drops these forms on purpose, a warning when a page uses them, and a note in the Quarto 1
differences docs, would help. Right now the navigation just disappears.

Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.