存在.nojekyll文件仍执行jekyll-build-pages@v1，报错原因咨询

问题背景 #

我正在将.md文件转换为.html文件，计划部署到GitHub Pages。虽然已经在项目中添加了.nojekyll文件，但jekyll-build-pages@v1仍会自动执行，而我的项目并非基于Jekyll框架，因此触发了构建错误。

错误日志 #

Run actions/jekyll-build-pages@v1
with:
source: ./docs
destination: ./docs/_site
future: false
build_revision: f4c9e5c0cb46a994aeb7066e4f4f11c4596de8ff
verbose: true
token: ***
...
Configuration file: none
  Logging at level: debug
      GitHub Pages: github-pages v228
      GitHub Pages: jekyll v3.9.3
             Theme: jekyll-theme-primer
      Theme source: /usr/local/bundle/gems/jekyll-theme-primer-0.6.0
         Requiring: jekyll-github-metadata
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
  Conversion error: Jekyll::Converters::Scss encountered an error while converting 
'assets/css/style.scss':
                    No such file or directory @ dir_chdir - /github/workspace/docs

我的GitHub Actions配置文件（docs.yaml） #

name: Build and Deploy Docs
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: write
jobs:
  build-and-deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3

      - name: Install pandoc
        run: sudo apt-get update && sudo apt-get install pandoc

      - uses: actions/setup-node@v3
        with:
          node-version: 18.x

      - name: Install styling
        run: npm install github-markdown-css

      - name: Build 🔧
        run: |
          #!/bin/bash

          mkdir dist
          touch dist/.nojekyll
          mv node_modules/github-markdown-css/github-markdown.css docs/github-markdown.css
          cp docs/*.css dist/
          if [ -d "docs/img/" ]; then
            cp -r docs/img/ dist/img/
          fi

          for file in docs/*.md; do
            name=$(basename "$file" .md)
            pandoc "$file" -f markdown -t html -o "dist/$name.html"
          done

          for file in dist/*.html; do
            name=$(basename "$file" .html)
            content=$(cat "$file")

            echo -e "<!DOCTYPE html>
            <html lang=\"en\">
              <head>
                <meta charset=\"UTF-8\">
                <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\">
                <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">
                <title>Docs</title>
                $(for cssfile in dist/*.css; do
                    cssname=$(basename "$cssfile")
                    if [[ "$cssname" != "github-markdown.css" && "$cssname" != "style.css" ]]; then
                      echo "<link rel=\"stylesheet\" href=\"./$cssname\">"
                    fi
                  done)
                <link rel=\"stylesheet\" href=\"./github-markdown.css\">
                <link rel=\"stylesheet\" href=\"./style.css\">
              </head>

              <body class=\"markdown-body\">
              ${content}
              </body>
            </html>" > "dist/$name.html"
          done

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: dist
          branch: docs

原因及解决办法 #

核心原因 #

GitHub Pages默认会对命名为gh-pages或docs的分支自动触发Jekyll构建流程，.nojekyll文件的作用只是让Jekyll跳过处理下划线开头的文件/文件夹，无法阻止Jekyll本身被执行。你当前部署的目标分支是docs，所以自动触发了Jekyll构建。

解决方案 #

有两种可行方式：

1. 修改部署分支名称：把部署目标分支从docs改为其他名称（比如gh-pages-docs），修改Actions配置中Deploy步骤的branch参数：

   - name: Deploy 🚀
     uses: JamesIves/github-pages-deploy-action@v4
     with:
       folder: dist
       branch: gh-pages-docs
   

   之后在GitHub仓库的Pages设置中，将发布源切换为这个新分支。

2. 禁用Jekyll构建：进入仓库的Settings → Pages → Build and deployment，选择"Deploy from a branch"后，展开"Advanced settings"，勾选"Disable Jekyll build"选项，这样即使分支是docs，也不会触发Jekyll构建。

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