GitHub Pages部署失败：Hugo shortcode 'note'模板未找到求助

一、解决构建失败：找不到note短码模板 #

报错核心是Hugo无法找到note短码对应的模板文件，结合你使用的toha主题，按以下步骤排查：

• 同步主题子模块：toha主题作为Git子模块存储在仓库中，复刻后未初始化子模块会导致主题文件缺失。执行以下命令拉取完整主题：

  git submodule update --init --recursive
  

  note短码模板位于主题目录的layouts/shortcodes/note.html，子模块同步后即可找到该文件。
• 校验短码调用格式：检查index.bn.md第13行的短码写法，toha主题的note短码需使用方括号包裹（而非百分号），正确格式为：

  {{< note >}}
  你的提示内容
  {{< /note >}}
  

• 匹配Hugo版本：查看原仓库的GitHub Action配置文件（.github/workflows/gh-pages.yml），确认其中指定的Hugo版本（需使用Extended版本），确保你的Action配置使用相同版本，避免版本差异导致的短码解析错误。

二、解决部署后仅显示README文件 #

该问题通常是GitHub Pages源配置或构建分支异常导致：

• 调整Pages源设置：进入仓库Settings → Pages，将Source选项设置为gh-pages分支的/root目录。若选为主分支根目录，会直接显示仓库根目录的README。
• 确认Action构建推送状态：查看GitHub Action的运行日志，确认构建步骤成功生成public目录，且已将该目录内容推送到gh-pages分支。若之前因短码错误导致构建失败，gh-pages分支未更新，会显示旧内容。
• 检查gh-pages分支内容：确认gh-pages分支存在，且包含Hugo构建后的静态文件（如index.html、assets目录等），而非仅README文件。若分支不存在，需先修复构建错误，让Action成功运行一次生成该分支。

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