Quarto HTML文档配置brand.yml显示logo失败问题排查

问题场景 #

用Python内核在VSCode中渲染带Logo的Quarto HTML文档，终端显示渲染成功，但Logo始终无法显示；调整配置后仅能看到导航栏头部，Logo依旧不出现。

已完成的配置 #

1. QMD文档头部配置 #

title: "Test Report"
author: "HQ"
format: 
  html:
    fontsize: 10pt
    code-overflow: wrap
embed-resources: true
smooth-scroll: true
code-tools:
    source: false
    toggle: false
    caption: none
toc: true
toc-location: right
echo: False
warning: False
message: false
jupyter: python3
theme:
  light: lux
  dark: slate
brand: brand/_brand.yml
include-in-header:
  - text: |
      <style>
      .cell-output-stdout code {
        word-break: break-wor !important;
        white-space: pre-wrap !important;
      }
      </style>

2. 项目结构 #

• 项目根目录下存在brand文件夹
• brand文件夹内包含_brand.yml配置文件及对应的Logo PNG图片

3. _brand.yml配置内容 #

color:
  palette:
    blue: "#ddeaf1"
  background: blue
logo:
  medium:
    light: brand/logo-HQ.png
    dark: brand/logo-HQ-dark.png

排查修复方案 #

从类似问题的处理经验来看，可以从这几个方向入手：

• 核对文件路径：确认_brand.yml里的Logo路径和实际文件位置完全匹配，注意部分系统区分文件名大小写，比如Logo-HQ.png和logo-HQ.png会被识别为不同文件。若QMD文件在项目根目录，brand/logo-HQ.png需对应真实的文件存放路径。
• 关闭资源嵌入测试：当前配置启用了embed-resources: true，该选项会将所有资源嵌入HTML，但Quarto的Brand Logo在该模式下可能存在加载异常。先注释掉这一行，重新渲染文档查看Logo是否显示。
• 切换主题验证：当前使用的lux（浅色）和slate（深色）主题可能与Brand功能存在兼容性问题，尝试切换为默认主题（删除theme配置或设置为theme: default），验证Logo能否正常显示。
• 移除自定义CSS：检查include-in-header中的自定义CSS是否意外覆盖了Logo的显示样式，暂时移除这段CSS代码，重新渲染文档测试。
• 升级Quarto版本：若使用的是旧版本Quarto，Brand功能可能存在已知Bug，建议升级到最新稳定版后重试。

内容的提问来源于stack exchange，提问作者ViSa