merging _sidebar.yml with other sidebar options

[anielsen001]

I'm trying to merge the _sidebar.yml file appropriately with some other sidebar formatting information, but I cannot get it to work. If I add any options into the sidebar section of the _quarto.yml, the sidebar fails to show altogether.

For example, I have this block of yaml in my _quarto.yml and the sidebar does not appear.

# tell quarto to read the generated sidebar
metadata-files:
  - _sidebar.yml

website:
  title: "documentation"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: reference/index.qmd
        text: API Reference
  sidebar:
    style: floating

If I remove the last bit, then the sidebar appears, but only on the reference documentation, not the first page index.html.

# tell quarto to read the generated sidebar
metadata-files:
  - _sidebar.yml

website:
  title: "documentation"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: reference/index.qmd
        text: API Reference

the _sidebar.yml looks like this:

website:
  sidebar:
  - contents:
    - reference/index.qmd
    - contents:
      - reference/file1.qmd
      - reference/file2.qmd
      section: API
    id: reference
  - id: dummy-sidebar

I asked a similar question on the quarto discussion and learned that the contents tag in the yaml should not be part of an array and should be an object, but it does sort of work. I'm trying to figure out if I'm using the output of quartodoc correctly or if there is something else I should do? I'd like to be able to style the sidebar and add other content to it.

[machow]

Hey, thanks for writing up this issue. What do you want the sidebar to look like across the site? If I'm understanding, you're hoping to...

• Have the sidebar included on every page (including the index and about pages)
• Set some other options on the sidebar. Can you say more about what options you want to set?

[anielsen001]

I would like to integrate with quartos hybrid navigation so that the sidebar adjusts on context.

For other options, I would like to be able to set the style from floating to docked, include a logo and add additional boilerplate content.

Do you understand if the contents tag as an object or array is an issue with this?

[machow]

I would like to integrate with quartos hybrid navigation so that the sidebar adjusts on context.

This should be possible now. For example, the quartodoc site has a sidebar for its Get Started Guide, and another for its API Reference. You should be able to add the sidebar for you other page (e.g. the Get Started Guide), and see the sidebar there.

metadata-files:
  # sidebar for API reference ------------------
  - api/_sidebar.yml

website:
  title: "quartodoc"
  page-navigation: true
  navbar:
    left:
      - file: get-started/overview.qmd
        text: Get Started
      - href: api/
        text: Reference

  sidebar:
    # Sidebar for get started guide ------------------
    - id: get-started
      title: Get Started
      style: floating
      align: left
      contents:
        - get-started/overview.qmd
        - section: "Basic Use"
          contents:
            - get-started/basic-docs.qmd
            - get-started/basic-content.qmd

For other options, I would like to be able to set the style from floating to docked, include a logo and add additional boilerplate content.

Currently, I think the only way to modify the API reference sidebar is to use a script to read the _sidebar.yml and then replace it with the settings you want added :/. For example,

# generates sidebar yaml file ----
quartodoc build

# replaces sidebar yaml file to include the options you want ----
python modify_sidebar.py

[machow]

I've opened an issue with the quarto team, that should make it easier to extend the sidebar!

quarto-dev/quarto-cli#8449

[anielsen001]

thank you for doing this, and figuring out what the correct issue should be for quarto.