I’m currently building a Culver’s-inspired restaurant menu website using Jekyll as the static site generator, and the project has grown more complex than a typical blog-style setup. The site includes multiple menu categories, deeply nested item structures, pricing data, descriptions, images, and promotional flags that vary by context. Most of the content is generated from YAML and JSON data files combined with Liquid templates and includes, and while everything builds and renders correctly in local development, I’m encountering inconsistent behavior in production builds. Certain menu sections occasionally fail to render, some collections appear incomplete, and in rare cases entire pages generate without expected data even though the source files remain unchanged.
As the site evolved, I introduced more advanced Liquid logic to reduce duplication, including nested loops, conditional rendering based on front matter variables, and shared includes for menu cards and category layouts. Over time, this has led to very large templates with multiple layers of abstraction, making it difficult to trace where data is being transformed or filtered. I suspect that some of the issues may be related to variable scoping or Liquid’s handling of reassigned variables inside loops, especially when the same include is reused across different layouts. Debugging this has been challenging since Jekyll does not provide strong runtime diagnostics beyond basic build warnings.
Another layer of complexity comes from how data files are structured and updated. Menu data is frequently modified to reflect new items, limited-time offers, or price changes, and these updates sometimes cause unexpected side effects in the generated output. For example, adding a new key to a YAML file can cause unrelated sections of the menu to stop rendering, or sorting logic to behave inconsistently across builds. I’m unsure whether this is due to malformed data, YAML parsing quirks, or Liquid filters behaving differently when encountering missing or optional fields, especially when combined with where, sort, and group_by filters.
I’ve also noticed differences between jekyll serve and jekyll build outputs, particularly when incremental builds are enabled. In some cases, clearing _site and rebuilding resolves missing menu sections, which makes me wonder if caching or incremental build behavior is causing stale data to persist. This is concerning because the site relies on automated builds for deployment, and manually cleaning the output directory each time is not a sustainable workflow. I’d like to better understand how Jekyll determines when data files or includes should trigger a full rebuild and whether there are recommended practices to avoid these inconsistencies.
Performance and maintainability are also becoming concerns. Because the menu is content-heavy, build times have increased significantly, and small changes to a single menu item can trigger rebuilds of many pages. I’m trying to strike a balance between using Jekyll collections versus centralized data files, but it’s not clear which approach scales better for this type of structured content. Additionally, the Liquid templates are becoming harder to reason about, and I’m worried that future changes will introduce subtle bugs that are difficult to catch before deployment.
Overall, I’m looking for advice from experienced Jekyll users on best practices for structuring large, data-driven sites like a restaurant menu, debugging Liquid rendering issues, and ensuring consistent builds between development and production. Are there recommended patterns for organizing complex data files, avoiding Liquid scoping pitfalls, or improving build reliability and performance? Any insights into tooling, plugins, or architectural approaches that work well for non-blog, content-heavy Jekyll sites would be extremely helpful. Very sorry for long post