Sidebar navigation

quartodoc can generate a sidebar on the lefthand side of the page, with a list of your functions.

In order to create a sidebar for your docs, add the following options to your _quarto.yml:

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


# tell quartodoc to generate the sidebar file
quartodoc:
  sidebar: "_sidebar.yml"
  # other options ...

Note that running python -m quartodoc build will now produce a file called _sidebar.yml, with a Quarto sidebar configuration. The Quarto metadata-files option ensures it’s included with the configuration in _quarto.yml.

Note

Here is what the sidebar for the quartodoc reference page looks like:

website:
  sidebar:
  - contents:
    - api/index.qmd
    - contents:
      - api/Auto.qmd
      - api/blueprint.qmd
      - api/collect.qmd
      - api/get_object.qmd
      - api/preview.qmd
      section: Preparation Functions
    - contents:
      - api/MdRenderer.qmd
      - api/MdRenderer.render.qmd
      - api/MdRenderer.render_annotation.qmd
      - api/MdRenderer.render_header.qmd
      - api/MdRenderer.signature.qmd
      - api/MdRenderer.summarize.qmd
      section: Docstring Renderers
    - contents:
      - api/Builder.qmd
      - api/Builder.from_quarto_config.qmd
      - api/Builder.build.qmd
      - api/Builder.write_index.qmd
      - api/Builder.write_doc_pages.qmd
      - api/Builder.write_sidebar.qmd
      - api/Builder.create_inventory.qmd
      section: API Builders
    - contents:
      - api/create_inventory.qmd
      - api/convert_inventory.qmd
      section: Inventory links
    - contents:
      - contents:
        - api/layout.Layout.qmd
        - api/layout.Section.qmd
        - api/layout.Page.qmd
        - api/layout.SectionElement.qmd
        - api/layout.ContentElement.qmd
        section: Structural
      - contents:
        - api/layout.Doc.qmd
        - api/layout.DocFunction.qmd
        - api/layout.DocAttribute.qmd
        - api/layout.DocModule.qmd
        - api/layout.DocClass.qmd
        - api/layout.Link.qmd
        - api/layout.Item.qmd
        - api/layout.ChoicesChildren.qmd
        section: Docable
      - contents:
        - api/ast.DocstringSectionSeeAlso.qmd
        - api/ast.DocstringSectionNotes.qmd
        - api/ast.DocstringSectionWarnings.qmd
        - api/ast.ExampleCode.qmd
        - api/ast.ExampleText.qmd
        section: Docstring patches
      section: Data models
    id: api
  - id: dummy-sidebar

Customizing the sidebar

sidebar can also accept additional sidebar options from the choices available in Quarto. These options are passed directly to Quarto, and can be used to customize the sidebar’s appearance and behavior, or include additional content.

When using a dictionary for sidebar, use file to specify the sidebar file (defaults to _quartodoc-sidebar.yml if not provided). You can also provide additional content in the sidebar. Tell quartodoc where to include your package documentation in the sidebar with the "{{ contents }}" placeholder.

quartodoc:
  sidebar: 
    file: "_sidebar.yml"
    style: docked
    search: true
    collapse-level: 2
    contents:
      - text: "Introduction"
        href: introduction.qmd
      - section: "Reference"
        contents:
          - "{{ contents }}"
      - text: "Basics"
        href: basics-summary.qmd