Diagnosing Jekyll Pages That Build Without Errors but Are Missing from _site

Recognizable condition

You run jekyll build (or bundle exec jekyll build) and the command finishes with exit code 0 and no error messages. Yet a file that exists in your source tree — for example _posts/2024-09-01-my‑post.md — is either absent from the generated _site folder or, when served, returns a 404.

Jekyll does not abort; it simply skips the file for one of several well‑defined reasons.

Common causes (most frequent first)

#	Cause	What happens
1	Missing or malformed YAML front matter	The file is copied verbatim (if it has no front matter) or ignored entirely if the front matter block cannot be parsed.
2	published: false in front matter or inherited from defaults	The post is treated as a draft and omitted unless --unpublished is passed.
3	Post date in the future relative to the build machine’s clock	Future‑dated posts are excluded unless --future is supplied.
4	Filename does not match YYYY-MM-DD-title.slug.ext for posts	Jekyll does not recognize the file as a post and skips it.
5	File excluded via exclude in _config.yml or located in an underscored/hidden directory	The file is never read during the site generation pass.
6	Permalink misconfiguration that routes output to an unexpected path	The file is generated, but you look in the wrong location (e.g., a subdirectory or a different URL).

Ordered diagnostic checks

1. Run a verbose build and confirm the file is read:

   bundle exec jekyll build --verbose 2>&1 | grep -i "your-post.md"
   

   If the file does not appear in the output, Jekyll never opened it (likely cause 5).

2. Inspect the front matter block:

   head -20 _posts/2024-09-01-my-post.md
   

   Look for:

   • Two lines consisting only of three hyphens (---) surrounding YAML.
   • No tabs inside the block (YAML forbids tabs).
   • A key published set to false.
   • A date value that is later than today’s date.

3. Check _config.yml for excludes and defaults:

   grep -E '^exclude:|^defaults:' _config.yml
   

   Note any glob patterns that could match your file or directory.

4. Force inclusion of drafts, future posts, and unpublished items:

   bundle exec jekyll build --drafts --future --unpublished --verbose
   

   If the file now appears in _site, the issue is one of the filtering flags (causes 2 or 3).

5. Verify the actual output path:

   find _site -type f -name "*my-post*" -print
   

   If a file is found but under an unexpected path, a permalink setting (cause 6) is redirecting it.

Fixes tied to each finding

Missing or malformed front matter

• Ensure the file starts with --- on its own line, ends with a matching --- line, and contains valid YAML in between.
• Remove any tab characters; use spaces only.
• If you do not need front matter for a plain page, add an empty block (---\n---\n) so Jekyll processes it.

published: false

• Delete the line or set it to true.
• Alternatively, override via an environment variable: JEKYLL_ENV=production bundle exec jekyll build --unpublished.

Future date

• Adjust the date: value to today or a past date.
• If you intentionally want to preview future posts, add --future to your build command (common in CI preview jobs).

Incorrect filename

• Rename the file to match YYYY-MM-DD-title.slug.md (or .markdown).
• Keep the title part lowercase with hyphens; avoid leading numbers besides the date.

Over‑broad exclude

• Edit _config.yml to narrow the pattern, e.g., change exclude: ["assets"] to exclude: ["assets/**"] only if you truly want to skip the entire assets folder.
• Test with a minimal config (see verification step below).

Permalink redirect

• Set an explicit permalink in the file’s front matter: permalink: /blog/my-post/.
• Or remove any permalink: entry from _config.yml that may be affecting the collection.
• After changing, rebuild and verify the file appears under the expected path.

Escalation criteria

If after performing the checks above the file still does not appear in _site:

1. Disable plugins one at a time (remove gems from Gemfile or comment out plugins: in _config.yml) and rebuild with --verbose. A generator or hook could be silently discarding the file.
2. Temporarily strip _config.yml to a minimal version containing only:

title: Test Site
markdown: kramdown

Re‑run the build. If the file appears, the problem lies in your configuration (exclude, defaults, or collection settings).

3. Verify that no custom collection or type: override is affecting the file’s processing.
4. If the issue persists, file an issue on the Jekyll repository with the verbose log, your _config.yml, and the exact source file contents.

Version‑sensitive notes

• --unpublished and front‑matter defaults scoping changed between Jekyll 3.x and 4.x. Run jekyll build --help to see which flags are available.
• Kramdown is the default Markdown engine from Jekyll 2.x onward; if you rely on an older engine, ensure it is explicitly declared.
• The exclude list behavior (whether it replaces or extends defaults) varies; consult the changelog for your specific version.

Practical verification steps

1. Run a comprehensive build that bypasses all common filters:

   bundle exec jekyll build --verbose --drafts --future --unpublished
   

   Check that the target file appears both in the verbose “Reading” list and in the generated _site directory.

2. Isolate configuration‑driven exclusion:

   cp _config.yml _config.yml.bak
   cat > _config.yml <<'EOF'
   title: Minimal Test
   markdown: kramdown
   EOF
   bundle exec jekyll build --verbose
   # observe whether the file is now present
   mv _config.yml.bak _config.yml
   

3. Confirm your Jekyll version and flag support:

   jekyll version
   jekyll build --help | grep -E "--unpublished|--future|--drafts"
   

Limitations

• The guide assumes a standard Jekyll setup with the default kramdown Markdown converter. If you use a different converter (e.g., redcarpet) some front‑matter handling nuances may differ.
• Timezone‑related future‑date exclusions depend on the build machine’s clock; CI runners in other zones may drop posts that appear locally.
• If you rely on third‑party generators or custom plugins, the escalation steps (disabling plugins) are necessary to rule out their influence.