helaili/jekyll-action部署后gh-pages分支内容未同步至线上站点的问题排查求助

Let’s break down why your live GitHub Pages site is showing a blank Blog Posts page even though your gh-pages branch has the correct content, and walk through actionable steps to fix it.

1. Double-Check Your GitHub Pages Source Configuration #

First, rule out the simplest mistake: GitHub might not be serving from your gh-pages branch at all.

• Head to your repository’s Settings → Pages.
• Confirm the Source dropdown is set to the gh-pages branch, and the folder is set to /root (unless you configured your build to output to a subfolder, which doesn’t sound like the case here).
• It’s easy to forget this step after setting up the Action—even if you push valid content to gh-pages, GitHub will serve whatever branch/folder is selected in this setting.

2. Bust GitHub Pages Caching #

GitHub Pages uses aggressive caching to speed up load times, which can cause stale content to stick around even after your gh-pages branch updates.

• To force a full cache refresh: Go to your Pages settings page, make a trivial change (like toggling the “Enforce HTTPS” setting off and back on), then save. This triggers GitHub to reprocess your site.
• For browser-side caching, append a query string to your blog URL (e.g., your-site.com/blog?refresh=1) to bypass cached content temporarily.

3. Audit Your GitHub Action Workflow and Build Logs #

Your Action might be failing silently or not pushing all the necessary files to gh-pages.

• Go to your repo’s Actions tab, find the latest run of your helaili/jekyll-action workflow, and dive into the logs.
  • Look for errors related to your Medium plugin: Did it successfully fetch posts and populate the medium_posts_json collection?
  • Confirm the workflow is pushing the full build output (including your populated blog page HTML) to gh-pages. Sometimes misconfigured build paths can lead to missing files.
• Manually compare the blog/index.html file from your local build with the one in the gh-pages branch. If they’re identical, the issue is on GitHub’s end; if not, your workflow isn’t building the site correctly.

4. Ensure .nojekyll Exists in the gh-pages Branch #

Even though you’re pre-building the site with your Action, GitHub Pages might still attempt to run Jekyll natively on the gh-pages branch if it doesn’t see a .nojekyll file. Since custom plugins aren’t allowed in native GitHub Pages builds, this can break your content.

• Check the root of your gh-pages branch for the .nojekyll file. If it’s missing:
  • Either add it to your repo’s root so the Jekyll build includes it in the output,
  • Or update your workflow to copy it into the build directory before pushing to gh-pages.

5. Validate URL Paths and baseurl Configuration #

If you’re hosting a project site (not a user/org site at username.github.io), incorrect baseurl settings can make content appear missing.

• Open your _config.yml and confirm baseurl: "/your-repo-name" is set correctly (matching the repository name in your GitHub URL).
• View the source of your live blog page (right-click → View Page Source) and check if links to your Medium posts are using the correct paths. If they’re pointing to /blog/post-name instead of /your-repo-name/blog/post-name, the browser can’t find the content, making the page look blank.

Step-by-Step Debugging Checklist #

To wrap up, follow these ordered steps to narrow down the issue:

1. Confirm GitHub Pages is set to serve from the gh-pages branch.
2. Force a GitHub Pages cache refresh via the settings page.
3. Review Action logs for build errors or missing files.
4. Compare local build output with gh-pages branch files.
5. Ensure .nojekyll is present in the gh-pages branch root.
6. Verify baseurl in _config.yml matches your site’s URL structure.

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