[Shock][CLI] - docs template produced broken links

[emmanuelrosa]

I generated a brand new static site using the docs template, and the following links were broken:

• Get Started
• Guide 1
• Guide 2
• Guide 3
• Concept 1
• Concept 2

I fixed it by making two edits to navMain.jinja

For the top-level menu item I added a trailing "/" to the href:

<!-- Top-level menu item -->
<li><a href="{{  item.url  }}/">{{  item.title  }}</a></li>

For the group of menu items, I removed the leading "/" in the href.

    <!-- Group of menu items -->
    <div class="link-group">
      <span class="title">{{  item.title  }}</span>
      <ol>
        {% for page in pages.byTag(item.tag, sortBy=item.sortBy) %}
        <li><a href="{{  page.data.url  }}">{{  page.data.title  }}</a></li>
        {% endfor %}
      </ol>
    </div>

[otabekoff]

How I fixed the problem?

Note

I've written this and paste AI to refine the answer.

Summary

This page explains the "Failed to hydrate template for page: null" / NoSuchMethodError: The method '[]' was called on null error that can occur when Jinja templates access nested data (for example github[org][repo]) while rendering component or layout templates with an incomplete context.

The error

When building or serving the site you might see:

Failed to hydrate template for page: null
Error: NoSuchMethodError: The method '[]' was called on null.
Receiver: null
Tried calling: []("github")

or repeated lines like Rendering page 'null' content as 'jinja'.

Root cause

The site generator renders component/layout templates in multiple contexts. Some of those render passes supply only a minimal context (for example when indexing or pre-rendering components). If a template does a direct lookup into a nested mapping that doesn't exist (for example github[package.github.organization][package.github.name]) the Jinja runtime throws a NoSuchMethodError because github (or one of the intermediate keys) is null.

Another related cause is wrapping entire templates with a top-level {% if package and github %} guard: when the generator renders the template in a partial context the whole template can return empty output, producing blank pages.

How I fixed it (concrete steps)

1. Add defensive checks before accessing nested keys. Prefer checks like:

{% if github and package and package.github and package.github.organization and package.github.name and
     github[package.github.organization] is defined and github[package.github.organization][package.github.name] is defined %}
  {% set contributors = github[package.github.organization][package.github.name] %}
{% endif %}

2. Avoid wrapping an entire layout or component in a top-level guard that prevents the template from rendering at all during partial renders. Instead, keep small, specific guards around the risky sections only.

3. Ensure package.github is defined in source/_data.yaml when your templates expect it. Example:

package:
  name: my_package
  title: My Package
  github:
    organization: my-org
    name: my_package
    url: https://github.com/my-org/my_package

4. Optionally disable contributors lookups while debugging by setting navigation.show_contributors: false in _data.yaml.

Quick diagnosis checklist

• Search templates for github[ or package.github and add null-safe checks.
• Do not block the entire template with a single {% if %} that may be false during partial rendering passes.
• Run shock build to reproduce the error locally and check the stack trace for the template and line mentioned.

Reproduce & verify

Run:

shock build

Fix a template, then rebuild. When serving locally, shock serve will inject a websocket auto-reload script — that is normal.

If it happens again

1. Read the error and stack trace: it shows the template and node where Jinja tried to access a missing key.
2. Search the codebase:

• grep "github\[" -R source/_includes
• grep "package.github" -R source/_includes

3. Add defensive guards around the found spots and re-run shock build.

Notes

• Keep guards as narrow as possible to preserve correct rendering in production builds.
• If you want the contributors panel to work, populate the github.contributors.repositories structure or enable your GitHub plugin so github[org][repo] is available to templates.

---

Short and focused — add any project-specific details below if needed.