Diagnosing Jekyll Build Failures Due to Malformed Front‑Matter YAML

Recognizable condition

When you run jekyll build or jekyll serve the command exits with status 0, but the generated _site directory contains empty HTML files or is missing expected sections. In some cases the console shows Liquid errors such as "Undefined method" or "Invalid YAML in file …". These symptoms usually indicate that the front‑matter of one or more Markdown or HTML files is not valid YAML.

Cause/diagnostic table

Cause	Typical symptom	Quick check
Missing --- delimiters	Liquid parse error or empty output	Look for the opening and closing front‑matter lines
Invalid YAML (stray tabs, unquoted colon, etc.)	Build aborts with a YAML error message	Run jekyll build --verbose and note the file cited
Date field not a valid timestamp	Post omitted from collections	Verify the date matches YYYY-MM-DD HH:MM:SS (optional timezone)
Unexpected Liquid tags inside front‑matter	Content rendered as raw tags	Ensure only YAML keys/values appear between the delimiters

Ordered checks

1. Run a verbose build

   jekyll build --verbose 2>&1 | head -n 20

   Capture the first error line; if it mentions YAML, note the file path.
2. Verify delimiters Open the cited file and confirm it starts with a line containing exactly three hyphens (---) and ends with another such line before any body content.
3. Validate YAML syntax Use Ruby’s YAML parser or a linter:

   ruby -ryaml -e \"YAML.load_file(ARGV[0])\" path/to/file.md

   If the command raises an exception, the YAML is malformed.
4. Check date fields For any key named date (or similar), ensure the value follows the pattern YYYY-MM-DD HH:MM:SS (optional +HHMM or -HHMM timezone).
5. Look for Liquid inside front‑matter Scan between the delimiter lines for {% or {{. These belong only in the body.
6. Re‑run the build After each correction, run jekyll build --quiet and verify that no error lines appear.
7. Inspect generated output Open _site/index.html (or the expected page) and confirm it contains non‑zero size and expected markup from the body.

Fixes tied to findings

• Missing delimiters: Insert a line with --- before the first key and another after the last key.
• Invalid YAML: Replace tabs with spaces, quote values that contain colons, commas, or special characters, and keep indentation at two spaces per level.
• Bad date: Reformat to Jekyll‑accepted form, e.g., 2023-09-15 14:30:00 +0000, or store the date as a string and use the date filter in the Liquid template.
• Liquid in front‑matter: Move any {% or {{ blocks to the body of the document or to an include, leaving only plain YAML keys/values.

After applying a fix, repeat step 5 of the ordered checks (jekyll build --quiet) to confirm the error disappears.

Verification

• Run jekyll build --verbose and ensure the output ends with a line like "Site generated in …" and reports a non‑zero file count.
• Check that expected HTML files (e.g., index.html, post pages) under _site have size > 0 bytes and contain a known string from the page body.
• Optionally run jekyll doctor; it should report no warnings related to deprecated configurations or missing dependencies.

Escalation criteria

If the build still fails after correcting front‑matter, consider the following:

1. Run jekyll doctor to spot plugin or dependency issues.
2. Examine Liquid syntax in the body with jekyll build --trace to see a full stack trace.
3. Confirm Ruby and Jekyll versions match the project’s requirements (jekyll -v).
4. If the problem persists, open an issue on the Jekyll repository, attaching the full verbose log and the offending source file.

Limitations

This guide addresses only front‑matter YAML problems. It does not cover:

• Errors arising from plugins or custom generators.
• Build failures due to missing dependencies or incompatible Ruby versions.
• Issues caused by symbolic links or filesystem permissions.

Always keep a backup of the original source files before editing front‑matter, as an incorrect edit can silently drop content.